For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

Midnight — system, account, grandpa, offchain, archive, midnight, sidechain, childstate (2/3)

API reference for Midnight. All methods ->

Part 2 of 3: 1 · 2 · 3

archive_unstable_header​

Fetches block header from archive.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <string> (block hash): The hash of the block for which the header should be retrieved.

Returns​

  • <object|null>: The block header object or null if the block hash does not exist.

Typical block header fields include:

  • parentHash (string): The hash of the parent block.
  • number (string): The block number (in hex).
  • stateRoot (string): The root of the state trie after executing this block.
  • extrinsicsRoot (string): The root hash of the block’s extrinsics.
  • digest (object): Consensus-specific digest items, such as logs from BABE or GRANDPA.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "archive_unstable_header",
    "params": [
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
    ]
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "parentHash": "0xdef456def456def456def456def456def456def456def456def456def456def4",
    "number": "0x0f0f0f",
    "stateRoot": "0xaaaabbbbccccddddeeeeffff1111222233334444555566667777888899990000",
    "extrinsicsRoot": "0xbbbbccccddddeeeeffff0000111122223333444455556666777788889999aaaa",
    "digest": {
      "logs": [
        "0x0642414245fc"
      ]
    }
  }
}

archive_unstable_storage​

Returns historical storage values.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: The storage key to query (hex-encoded).
    2. <string>: The block hash at which to read the storage value.

Returns​

  • <string|null>:
    • The hex-encoded SCALE-encoded value stored under the given key at the specified block.
    • null if the key does not exist or the block hash is invalid.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "archive_unstable_storage",
    "params": [
      "0x1a2b3c4d5e6f",                                    // storage key
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"  // block hash
    ]
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x01020304"
}

Sidechain & Midnight-specific:

midnight_apiVersions​

Lists supported API versions for the Midnight node.

Parameters​

  • id (integer; required): a request ID (example: 1).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

Returns​

  • <array<object>>: A list of available API versions supported by the Midnight node. Each object typically contains:
    • api (string): The name of the RPC API (e.g., "chain", "state", "system").
    • version (number): The supported version number for that API.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "midnight_apiVersions",
    "params": []
  }'

Response example​

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        2
    ]
}

midnight_contractState​

Fetches the on-chain state of a specific Midnight contract.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: The contract address whose state is being queried.
    2. <string>: The block hash at which to retrieve the contract state (optional depending on implementation; may use latest or be omitted for the latest state).

Returns​

  • <object>: The current state of the specified contract, which may include:

    • storage (object): Key-value pairs of the contract’s storage slots (hex-encoded keys and values).
    • metadata (object, optional): Information about the contract (e.g., ABI hash, deployment block).

  • null: Returned if the contract does not exist or no state is available at the given block hash.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "midnight_contractState",
    "params": [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",  // contract address
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"   // block hash
    ]
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "storage": {
      "0x0000": "0x01020304",
      "0x0001": "0x0a0b0c0d"
    },
    "metadata": {
      "deployedAt": "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
    }
  }
}

midnight_decodeEvents​

Decodes event data emitted by Midnight smart contracts.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: The block hash for which to decode events.
    2. <string>: The raw events data (hex-encoded SCALE-encoded bytes) typically obtained from chain storage (system.events).

Returns​

  • <array<object>>: A list of decoded events from the specified block. Each event object typically includes:
    • section (string): The pallet/module name that emitted the event (e.g., balances).
    • method (string): The specific event name (e.g., Transfer).
    • data (array<any>): Event parameters, decoded according to the runtime metadata.
    • topics (array<string>, optional): Event topics, if applicable.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "midnight_decodeEvents",
    "params": [
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1",  // block hash
      "0x01020304aabbccdd"                                                  // raw events data
    ]
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "section": "balances",
      "method": "Transfer",
      "data": [
        "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
        "5FHneW46xGXgs5mUiveU4sbTyGBzmstT8dQ8x6b8S1uZxZ8M",
        1000000000000
      ]
    },
    {
      "section": "system",
      "method": "ExtrinsicSuccess",
      "data": []
    }
  ]
}

midnight_jsonBlock​

Returns a full block in a JSON format.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <string>: The block hash of the block to retrieve in JSON format.

Returns​

  • <object|null>: A JSON representation of the specified block, or null if the block does not exist.

Typical fields include:

  • block:

    • header: Standard block header fields:
      • parentHash (string): The parent block hash.
      • number (string): Block number (in hex).
      • stateRoot (string): State trie root.
      • extrinsicsRoot (string): Extrinsics trie root.
      • digest (object): Consensus-specific digest logs.
      • extrinsics: (array<string>): List of extrinsics included in the block.

  • justifications (array, optional): GRANDPA justifications if present.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "midnight_jsonBlock",
    "params": [
      "0x3cc34cd9d6a758999d66e977779b0d2f3bbeeb83fcd8dc8a361e7fe76905f0c6"
    ]
  }'

Response example​

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": "{\"header\":{\"parentHash\":\"0x62975104b79de4cb21a747c6edbd590fb4226eb51bcaa16e008b8528252731a7\",\"number\":\"0xf315b\",\"stateRoot\":\"0xd4962bed8eac446b29a3a5128bac1f0dc873355f1341e87120f2f4ee1ae67077\",\"extrinsicsRoot\":\"0x7e3b01b1f843be8994081418391ced306dd5e5cb03977bb292739b943942ef4c\",\"digest\":{\"logs\":[\"0x06617572612055426b1100000000\",\"0x066d63736880593d93a5de83054c0383f8e2e9e13209afb622807b8675b7d39b8a471d282bc6\",\"0x044d4e535610e02e0000\",\"0x056175726101012ca4b4d8924f801071b84d836cf248ee979b2c26021ff3f02123768fe20dd539701edf4a75062884f555b0894d23fd9a4b0333e6489cf23d496adb4d2a8e3480\"]}},\"body\":[{\"Timestamp\":1753452030000},\"UnknownTransaction\"],\"transactions_index\":[]}"
}

midnight_jsonContractState​

Returns human-readable JSON format of contract state.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: The contract address whose state should be retrieved.
    2. <string>: The block hash at which to query the state (optional in some implementations; if omitted, the latest state may be returned).

Returns​

  • <string|null>: A JSON object encoded as a string representing the contract state or null if no state is available.

The JSON string (when parsed) typically contains:

  • storage: Key-value pairs for the contract’s storage slots (hex-encoded).
  • metadata: Optional information about the contract such as ABI or deployment details.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "midnight_jsonContractState",
    "params": [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",  // contract address
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"   // block hash
    ]
  }'

Response example​

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "{\"storage\":{\"0x0000\":\"0x01020304\",\"0x0001\":\"0x0a0b0c0d\"},\"metadata\":{\"deployedAt\":\"0xabc123...\"}}"
}

midnight_zswapChainState​

Returns ZSwap contract state information.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: ZSwap contract address (hex-encoded). This must be a valid deployed ZSwap contract address.
    2. <string> (optional): Block hash at which to query the chain state. If omitted, defaults to the latest block.

Returns​

  • <string|null>: A JSON object encoded as a string representing the ZSwap chain state, or null if no data is available.

The decoded JSON string typically contains information such as:

  • pools: Active liquidity pools and their parameters.
  • tokens: Supported tokens and balances.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "midnight_zswapChainState",
    "params": [
      "0x<zswap_contract_address>"
    ]
  }'

Response example​

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "{\"pools\":[{\"id\":1,\"tokenA\":\"ZUSD\",\"tokenB\":\"ZBTC\",\"liquidity\":\"1000000000\"}],\"parameters\":{\"fee\":\"0.003\"}}"
}

sidechain_getAriadneParameters​

Gets Ariadne protocol parameters used for privacy.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <integer> (u32; required): Epoch ID (must be greater than or equal to the minimum supported epoch, which is usually 2 on testnet).

Returns​

  • <object>: A set of Ariadne protocol parameters used by the Midnight sidechain. Typical fields may include (structure depends on the node implementation):
    • epochLength (number): Number of blocks per epoch.
    • committeeSize (number): Number of validators in the Ariadne committee.
    • finalityThreshold (number): Threshold required for finality (e.g., percentage or quorum count).
    • otherParams (object): Any additional Ariadne-specific configuration values.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sidechain_getAriadneParameters",
    "params": [<integer>]
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "epochLength": 100,
    "committeeSize": 21,
    "finalityThreshold": 15,
    "otherParams": {
      "rewardRate": "0.05",
      "slashRatio": "0.02"
    }
  }
}

sidechain_getEpochCommittee​

Returns the validator committee for the current or given epoch.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <integer>: The epoch number (u32) for which to retrieve the committee information.

Returns​

  • <object>: Committee information for the specified epoch. Fields:
    • sidechainEpoch (number): The sidechain epoch number queried.
    • committee (array<object>): A list of committee members, where each object contains:

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sidechain_getEpochCommittee",
    "params": [
      243000
    ]
  }'

Response example​

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "sidechainEpoch": 243000,
        "committee": [
            {
                "sidechainPubKey": "0x0203ae55458c8b9123b37a61ddd7f2a334ff35a80385825a2265eb490688cdebc5"
            },
            {
                "sidechainPubKey": "0x0250159344a81b11aa21d9b4d2b5f24000682a95eb6564caccfe67b96ade9e202a"
            }
        ]
    }
}

sidechain_getParams​

Fetches current configuration parameters for the sidechain.

Parameters​

  • id (integer; required): a request ID (example: 1).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

Returns​

  • <object>: Sidechain parameters object.
    • genesis_utxo (string): Identifier of the genesis UTXO (Unspent Transaction Output) in the sidechain, including the transaction hash and output index (e.g., "46876a22...b11#0").

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sidechain_getParams",
    "params": []
  }'

Response example​

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "genesis_utxo": "46876a2250ec0e523eccc30b0fc6d6fa55c61dd200b83140acaab291edeb0b11#0"
    }
}

sidechain_getStatus​

Returns current sidechain status including sync state and parameters.

Parameters​

  • id (integer; required): a request ID (example: 1).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

Returns​

  • <object>: Contains the status of both the sidechain and the mainchain. Fields:

    • sidechain (object): Status information for the Midnight sidechain.

      • epoch (number): Current sidechain epoch number.
      • slot (number): Current sidechain slot number.
      • nextEpochTimestamp (number): UNIX timestamp (ms) for the start of the next sidechain epoch.

    • mainchain (object): Status information for the connected mainchain.

      • epoch (number): Current mainchain epoch number.
      • slot (number): Current mainchain slot number.
      • nextEpochTimestamp (number): UNIX timestamp (ms) for the start of the next mainchain epoch.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sidechain_getStatus",
    "params": []
  }'

Response example​

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "sidechain": {
            "epoch": 243570,
            "slot": 292285076,
            "nextEpochTimestamp": 1753711200000
        },
        "mainchain": {
            "epoch": 1007,
            "slot": 87054433,
            "nextEpochTimestamp": 1753747200000
        }
    }
}

Child State Access:

childstate_getKeys​

Returns the keys from child storage.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: Child storage key (hex-encoded) identifying the child storage.
    2. <string>: Key prefix (hex-encoded) to filter keys. Use 0x for all keys.
    3. <string>: Block hash at which to query state. If omitted, defaults to the latest block.

Returns​

  • <array<string>>: An array of keys (hex-encoded) stored under the specified child storage, filtered by the provided key prefix.
  • []: Returned if there are no keys matching the given prefix.
  • null: Returned if the child storage or block hash is invalid.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "childstate_getKeys",
    "params": [
      "0x1a2b3c4d5e6f",     // child storage key
      "0x",                // key prefix (empty to get all keys)
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"  // block hash
    ]
  }'

Request example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "0x1a2b3c4d5e6f0011",
    "0x1a2b3c4d5e6f0022",
    "0x1a2b3c4d5e6f0033"
  ]
}

childstate_getKeysPaged​

Returns paged keys from child storage.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    1. <string>: Child storage key (hex-encoded) identifying the child storage.
    2. <string>: Key prefix (hex-encoded) to filter keys. Use "0x" for all keys.
    3. <number>: Count — the maximum number of keys to return.
    4. <string>: Start key (hex-encoded) for pagination. Use "0x" or omit to start from the beginning.
    5. <string>: Block hash at which to query state. If omitted, defaults to the latest block.

Returns​

  • <array<string>>: A list of child storage keys (hex-encoded) matching the given prefix and pagination parameters.
  • []: Returned if no keys match the given prefix or pagination window.
  • null: Returned if the child storage key or block hash is invalid.

Request example​

curl -X POST https://rpc.ankr.com/midnight_testnet/YOUR_ANKR_API_KEY/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "childstate_getKeysPaged",
    "params": [
      "0x1a2b3c4d5e6f",      // child storage key
      "0x",                  // key prefix (empty = all keys)
      10,                    // number of keys to return
      "0x",                  // start key for pagination (empty = start from first key)
      "0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"  // block hash
    ]
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "0x1a2b3c4d5e6f0011",
    "0x1a2b3c4d5e6f0022",
    "0x1a2b3c4d5e6f0033",
    "0x1a2b3c4d5e6f0044"
  ]
}