Links

JSON-RPC

Convenience Libraries

While some developers may opt to interact directly with the JSON-RPC API detailed below, there are also a number of Javascript based convenience libraries designed to make data interaction much easier. Convenience libraries abstract much of the complexity of direct API calls out into simple one-line methods. These methods are also easily portable into decentralized applications and help make backend logic more concise and readable. The primary convenience library used to interact with Quai Network is quais.js.
A postman library containing templates for all of the RPC methods detailed below is also available at the Quai API workspace.

Conventions

Hexadecimal Encoding

When making calls to a node, data can be passed or returned in two types via JSON. These types are quantities and unformatted byte arrays. Both utilize hex encoding for compact representation but have slightly different formatting requirements.

Quantities

When encoding quantities like numbers and integers, use the following format:
  • Encode as a hexadecimal
  • Prefix all data with "0x"
  • Example: 21000 in decimal is "0x5208"

Unformatted Data

To encode unformatted data such as addresses, byte arrays, hashes, etc. - use the folllowing format:
  • Encode as a hexadecimal
  • Prefix with "0x"
  • Two hex digits per byte of data, with an even number of digits only
  • Example: hello is encoded as "0x48656C6C6F"

Default Block Parameter

The default block parameter is an extra parameter that can be passed when querying the state of Quai Network. This parameter allows you to specify a specific block or state of Quai that you would like to receive data from. When not passed in a call, this parameter defaults to the height of the most recent block.
Available options for this parameter are:
  • "earliest" - genesis block
  • "latest" - most recently mined block
  • "pending" - pending state changes
  • integer block number
The default block parameter can be passed to the following methods:

Curl Examples

The below section details using the JSON-RPC API to make curl requests to a Quai Network node. Each example includes a description of the endpoint, parameters, return type, and an illustration of its usage.
You might encounter an error message related to the content type, as the --data option sets it to application/x-www-form-urlencoded. To fix this, include -H "Content-Type: application/json" at the start of the call. Note that the examples do not include the full request headers, flags, and URL/IP & port combination, but only the data for simplicity.
A complete curl request including these additional data would look like:
curl -X POST \
http://127.0.0.1:8512 \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"method": "quai_syncing",
"params": [],
"id": 1
}'
Depending on the chain you're requesting data from, the port (in the example 8512) the request is being routed to will change.

JSON-RPC API Methods

quai_gasPrice

Returns the gas price.

Input Parameters

No input params are required for this method.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_gasPrice",
"params": [],
"id": 1
}

Returns

gasPrice: Quantity - Current gas price
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x3b9aca01" // 1000000001
}

quai_maxPriorityFeePerGas

Returns the max priority fee per unit of gas.

Input Parameters

No input params are required for this method.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_maxPriorityFeePerGas",
"params": [],
"id": 1
}

Returns

priorityFeePerGas: Quantity - Current max priority fee per gas
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x3b9aca01" // 1000000001
}

quai_feeHistory

Returns the fee history for a specific range of blocks.

Input Parameters

  • blockCount: Quantity - Integer block count to be queried. Can range from 1 to 1024.
  • blockNumber: Quantity - Latest integer block number to be queried.
  • rewardPercentiles: Array - Array of integer reward percentiles. A monotonically increasing list of percentile values to sample from each block's effective priority fees per gas in ascending order, weighted by gas used.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_feeHistory",
"params": ["0x2", "0x8", [2, 4, 6]],
"id": 1
}

Returns

  • oldestBlock: Quantity - Integer block number of the most recent block queried.
  • reward: Array - The requested percentiles of effective priority fees per gas of transactions in each block, sorted in ascending order and weighted by gas used.
  • baseFeePerGas: Array - Base fee per gas in the given block
  • gasUsedRatio: Array - gasUsed/gasLimit ratio in the given block
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"oldestBlock": "0x15d",
"reward": [
["0x3b9aca00", "0x3b9aca00", "0x3b9aca00"],
["0x3b9aca00", "0x3b9aca00", "0x3b9aca00"]
],
"baseFeePerGas": ["0x12", "0x10", "0x1e"],
"gasUsedRatio": [0.0441, 0.0023625]
}
}

quai_syncing

Returns an indicator of whether the client is actively syncing.

Input Parameters

No input params are required for this method.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_syncing",
"params": [],
"id": 1
}

Returns

  • syncing: Boolean - true if the client is actively syncing, false otherwise.
{
"jsonrpc":"2.0",
"id":"1",
"result":"false"
}

quai_chainId

Returns the current chain ID.

Input Parameters

No input params are required for this method.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_chainId",
"params": [],
"id": 1
}

Returns

  • chainId: Quantity - Current integer chain ID.
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x1" // 1
}

quai_nodeLocation

Returns the current node location or context.

Input Parameters

No input params are required for this method.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_nodeLocation",
"params": [],
"id": 1
}

Returns

  • location: Quantity - Array of integers corresponding indicating node location. The first entry indicates the node's region, the second indicates the zone.
{
"jsonrpc":"2.0",
"id":"1",
"result":["0x1","0x0"] // [1, 0] or Paxos-1
}

quai_blockNumber

Returns the latest block number.

Input Parameters

No input params are required for this method.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_blockNumber",
"params": [],
"id": 1
}

Returns

  • blockNumber: Quantity - Integer number of the most recent block.
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x2b7"
}

quai_getBalance

Returns the balance of the specified address.

Input Parameters

  • address: Data - 20 bytes, the address being queried.
  • Quantity | Tag - Integer block number or default block parameter.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_getBalance",
"params": ["0x421bc7323295c6b7f2f75fc4c854d4fb600e69e8","latest"],
"id": 1
}

Returns

  • balance: Quantity - Integer balance of the address in wei.
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x3f28cb71571c7" // 1111111111111111
}

quai_getProof

Returns the Merkle-Proof for a given account and optional storage keys.

Input Parameters

  • address: Data - 20 bytes, the address for which the Merkle-Proof is being returned.
  • storageKeys: Array - String array of storage keys.
  • Quantity | Tag - Integer block number or default block parameter.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_getProof",
"params": [
"0x7F0d15C7FAae65896648C8273B6d7E43f58Fa842",
["0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"],
"latest"
],
"id": 1
}

Returns

  • address: Data - 20 bytes, the address for the proof.
  • accountProof: Array - RLP-serialized MerkleTree-Nodes, starting with the stateRoot-Node, following the path of the SHA3(address) as key.
  • balance: Quantity - Balance in wei.
  • codeHash: Data - 32 bytes, codeHash of the account.
  • nonce: Quantity - Nonce of the account.
  • storageHash: Data - 32 bytes, the SHA3 hash of the storageRoot.
  • storageProof: Array
    • key: Data - 32 bytes, the requested storage key.
    • value: Quantity - Value(s) of the storage key(s).
    • proof: Array - Array of rlp-serialized MerkleTree-Nodes, starting with the storageHash-Node, following the path of the SHA3 (key) as the path.
{
"jsonrpc":"2.0",
"id":"1",
"result": {
"address": "0x7f0d15c7faae65896648c8273b6d7e43f58fa842",
"accountProof": [
"0xf8518080808080a0c330e7e9f2c4d26b65d6a75253887c5aaf97e0f8d4fca55b9c1b4d258acf69b78080808080808080a0eaa68ff161bff8212a577807d9d5031f7298825a42777c9837dad04d377595d68080",
"0xf870a03380c7b7ae81a58eb98d9c78de4a1fd7fd9535fc953ed2be602daaa41767312ab84df84b808706943fdbce684ba056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a0c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
],
"balance": "0x0",
"codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
"nonce": "0x0",
"storageHash": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
"storageProof": [
{
"key": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
"value": "0x0",
"proof": []
}
]
}
}

quai_getHeaderHashByNumber

Returns the hash of the block header for a specific block number.

Input Parameters

  • blockNumber: Quantity - the integer block number.

Example Request

// Request Body
{
"jsonrpc": "2.0",
"method": "quai_getHeaderHashByNumber",
"params": ["0x15d"],
"id": 1
}

Returns

  • blockHash: Data - 32 bytes, the hash of the block header.
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x0000024ccfb37a6e7ba09a3541c6c1e614e64809cc1b742acad2451e22764d6c"
}

quai_getHeaderByHash

Returns the block header given the header hash.

Input Parameters

  • blockHash: Data - 32 bytes, the hash of the block header.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_getHeaderByHash",
"params": ["0x0000024ccfb37a6e7ba09a3541c6c1e614e64809cc1b742acad2451e22764d6c"],
"id": 1
}

Returns

Object - the block header. All arrays within the object are organized by descending context.
  • baseFeePerGas: Quantity - The base fee per gas for the block.
  • difficulty: Quantity - Integer of the difficulty for this block.
  • extRollupRoot: Data - 32 bytes, hash of all external transactions emitted since the previous coincident block.
  • extTransactionsRoot: Data - 32 bytes, root of the external transaction trie of each block since the previous coincident block.
  • extraData: Data - The "extra data" field of this block, contains a byte string.
  • gasLimit: Quantity - The maximum gas allowed in this block.
  • gasUsed: Quantity - The total used gas by all transactions in this block.
  • hash: Data - 32 bytes, the hash of the block header.
  • location: Quantity - RLP encoded location of the block.
  • manifestHash: []<Data> - 32 bytes, the hashes of the block manifest for each block.
  • miner: Data - 20 bytes, the address to whom the mining rewards were paid to.
  • nonce: Data - 8 bytes, hash of the generated proof-of-work, null when the block is pending.
  • number: []<Quantity> - Integer block numbers with the format [Prime, Region, Zone].
  • parentDeltaS: []<Quantity> - Change in parent block entropy with the format [Prime, Region, Zone].
  • parentEntropy: []<Quantity> - Parent block entropy with the format [Prime, Region, Zone].
  • parentHash: Data - 32 bytes, the hash of the parent block with the format [Prime, Region, Zone].
  • receiptsRoot: Data - 32 bytes, receipt trie root hash of the block.
  • sha3Uncles: Data - 32 bytes, SHA3 of the uncles data in the block.
  • stateRoot: Data - 32 bytes, the root of the final state trie of the block.
  • timestamp: Quantity - Integer of the unix timestamp for when the block was collated.
  • transactionsRoot: Data - 32 bytes, the root of the transaction trie of the block.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"baseFeePerGas": "0x1",
"difficulty": "0x16d317",
"extRollupRoot": "0xaa43773538ebb8494ee7d895d87c114304bc69306c888da2fb40d45d639b2d79",
"extTransactionsRoot": "0xcde1249dcffdb0ecca318d39cf08a4384767c4956f1b0f323d4ed8dbf50a7b53",
"extraData": "0xdf8776302e31312e3087676f2d7175616988676f312e32302e36856c696e7578",
"gasLimit": "0x4c4b400",
"gasUsed": "0x252ba0",
"hash": "0x0000085526a97d1b4e1613e3aa7dd01f9cef01525d242a42f203355e8c7dfcb6",
"location": "0x0000",
"manifestHash": [
"0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
"0x4b4e182d76c7a56ca896e8021bb9e1d339498cef5e0f36c0b78efd49406357b1",
"0x6bdf6d340cce48815db7c19c4d1ea2dcddb235ab09b05a8914748c98af7432cf"
],
"miner": "0x05795ed14cdb744781b50d8061a00f42c2124f93",
"nonce": "0x29c868751a5ec0fc",
"number": ["0x11", "0x7f", "0x2b5"],
"parentDeltaS": ["0x0", "0x7582f1cd923e1b7e34d", "0x5980ead1726f9d7639"],
"parentEntropy": ["0x1c8a963601e57daef58dd", "0x1b12cce80621f70c0af16", "0x1b1864f6b3391e05e254f"],
"parentHash": [
"0x0000022550f6aeb9f4db37d54b159bc0812916f246a74909e1b9ce7616d5dd7f",
"0x000007c122e2cf197cf507062ad9ce285de7273a853226116d38f47466f4c3ad",
"0x000006a97da5e1cf29f92dbb83df5568132dc9e962106c1fc343d313fc250f46"
],
"receiptsRoot": "0x2db04a8f2dcb99b453f3941bdc522d0fcc6cc1e0dd76a8f21d55e97bd1c3804a",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size": "0x20d",
"stateRoot": "0x0082f4c0ff72f767dedc1da8033c756ed72c3a8baa0f9b4d7f7bfe9d587d82d4",
"timestamp": "0x64c7fb18",
"transactionsRoot": "0x50806865e11d4eb8deecba6cd8b926b7d9c9b85497d78476687ca5577d93d4a2"
}
}

quai_getHeaderByNumber

Returns the block header given the block number.

Input Parameters

  • blockNumber: Quantity - Integer block number

Example Request

{
"jsonrpc": "2.0",
"method": "quai_getHeaderByNumber",
"params": ["0x15d"],
"id": 1
}

Returns

quai_getBlockByNumber

Returns the block data for a specific block number.

Input Parameters

  • blockNumber: Quantity - Integer block number
  • full: Boolean - If true, returns the full transaction objects. If false, returns only hashes of the transactions

Example Request

{
"jsonrpc": "2.0",
"method": "quai_getBlockByNumber",
"params": ["0x15d", true],
"id": 1
}

Returns

The response for getBlockByNumber is largely the same as the response for getHeaderByHash, with the addition of the following fields:
  • extTransactions: []<Data> - Array of 32 byte external transaction hashes.
  • subManifest: []<Data> - Array of all 32 byte subordinate block hashes since the last coincident block.
  • transactions: []<Data> - Array of 32 byte internal transaction hashes.
  • uncles: []<Data> - Array of uncle blocks.
subManifest will always be empty in zone blocks. Both transactions and extTransactions will be empty in region and prime blocks.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"baseFeePerGas": "0x1",
"difficulty": "0x195a93",
"extRollupRoot": "0x246f5df00f42ea6c6b3ce50709c1a5ed01effd053be9fd55c8e7a01a5fdd0e75",
"extTransactions": ["0xf65280bd108ec7aabb32e68b48ad129a6abfff2cdb28d4187c2229dabc7dd9c6"],
"extTransactionsRoot": "0xc9b954a741c868ee033c7a769470f71779326a46bd654c8248a9a684b03f60f7",
"extraData": "0xdf8776302e31312e3087676f2d7175616988676f312e32302e36856c696e7578",
"gasLimit": "0x4c4b400",
"gasUsed": "0x2e248",
"hash": "0x0000023ee6f37ecaa871f52068e6c020b899d6bafc6efa7a6ce11a062bd2db2e",
"location": "0x0000",
"manifestHash": [
"0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
"0x89850f64186b9da266bc7675ffc919b348f05e0fde66039d8edcaaa33b527024",
"0xfcedd8bed59b82a4d43507d15f1e36661644784369c7543d76216fe501222b5c"
],
"miner": "0x05795ed14cdb744781b50d8061a00f42c2124f93",
"nonce": "0x77bbf39f5610b167",
"number": ["0x9", "0x43", "0x15e"],
"order": 2,
"parentDeltaS": ["0x0", "0x5f74cf155fd3b35cae7", "0x45b983cac85b6d849a"],
"parentEntropy": ["0xdbafb89c01f36e7178f9", "0xc570126e27f3a630caa3", "0xc5b5cbf1f2bc019e4f3d"],
"parentHash": [
"0x000004c76cbf7feb9a14344238c3a32010695100130cc699f44eec051999b2d0",
"0x000002e68ba4766a7fd55f233c676e35b330f168b657a0895264535ac30d652e",
"0x0000024ccfb37a6e7ba09a3541c6c1e614e64809cc1b742acad2451e22764d6c"
],
"receiptsRoot": "0x943ec93fea96d218dbba1f5efb16af09488339c75ee733412c74375972bd9694",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size": "0x62e",
"stateRoot": "0x4dcd52b88572709f4f07cfcd80c14b19a26e42d30fdacfb8da74b587a1248114",
"subManifest": [],
"timestamp": "0x64c7df3b",
"totalEntropy": "0xc5cca1261d7817679ecd",
"transactions": [
"0x197c7e5ec7bee1a11fd3f45faf55fe2072b5948fe3d8d4bf8bb493458194be50",
"0x786177297ab60b4da659dafb170f29cde1b7d7173fa6a637895faaba4b5dd379",
"0x37c915d0321d2cbdbcdd7c337845a1313fa0c57b7935b8b8070745c9328c3468",
"0xf9a562a193c6b931ee15fce582fa7783bf27d5c45c62d418a329cf106ee4c07f",
"0x1148714f16086177fc5d08ab00f67b20cf7aadb1eaace0e04b55b2571779c46a",
"0x7651be3900e0a5c4e35d3af2da38ce2faa0d4ea45f1a75c27ea1d641067f722e",
"0xbddfe2598d376008adf60c92d1078ef7bffd3eba5170ee5df4509f16f4396d0b",
"0x83362686984a0d66a656205482ed2fdaa5ea85c4082abd10914ea841731615ca"
],
"transactionsRoot": "0xbeb22d0d3169d16dfae20eba72d013a5f21566328298cd5e9a53177197b66f3d",
"uncles": []
}
}

quai_getBlockByHash

Returns the block data for a specific block header hash.

Input Parameters

  • blockHash: Data - 32 bytes, the hash of the block header
  • full: Boolean - If true, returns the full transaction objects, if false returns the transaction hashes. Defaults to false.

Example Request

{
"jsonrpc": "2.0",
"method": "quai_getHeaderByHash",
"params": ["0x0000023ee6f37ecaa871f52068e6c020b899d6bafc6efa7a6ce11a062bd2db2e", true],
"id": 1
}

Returns

quai_getUncleByBlockNumberAndIndex

Returns the uncle block data for a specific block number and uncle index.

Input Parameters

  • blockNumber: Quantity - Integer block number
  • uncleIndex: Quantity - Integer uncle index.
{
"jsonrpc": "2.0",
"method": "quai_getUncleByBlockNumberAndIndex",
"params": ["0x15d","0x0"],
"id": 1
}

Returns

See quai_getBlockByNumber. Uncles do not contain individual transactions or external transactions.

quai_getUncleByBlockHashAndIndex

Returns the uncle block data for a specific block hash and uncle index.

Input Parameters

  • blockHash: Data - 32 bytes, the hash of the block header.
  • uncleIndex: Quantity - Integer uncle index.
{
"jsonrpc": "2.0",
"method": "quai_getUncleByBlockHashAndIndex",
"params": ["0x00000040ba9145742407a455bf07aa33cdd014fd4cd630970906e9f40064d033", "0x1"],
"id": 1
}

Returns

See quai_getBlockByNumber. Uncles do not contain individual transactions.

quai_getUncleCountByBlockNumber

Returns the uncle count for a specific block.

Input Parameters

  • blockNumber: Quantity - Integer block number.
{
"jsonrpc": "2.0",
"method": "quai_getUncleCountByBlockNumber",
"params": ["0x15d"],
"id": 1
}

Returns

  • uncleCount: Quantity - Integer number of uncles in this block.
{
"jsonrpc":"2.0",
"id":1,
"result":"0x2"
}

quai_getUncleCountByBlockHash

Returns the uncle count for a specific block hash.

Input Parameters

  • blockHash: Data - 32 bytes, hash of the block header.
{
"jsonrpc": "2.0",
"method": "quai_getUncleCountByBlockHash",
"params": ["0x00000040ba9145742407a455bf07aa33cdd014fd4cd630970906e9f40064d033"],
"id": 1
}

Returns

  • uncleCount: Quantity - Integer number of uncles in this block.
{
"jsonrpc":"2.0",
"id":1,
"result":"0x2"
}

quai_getCode

Returns the code stored at the given address.

Input Parameters

  • address: Data - 20 bytes, the address at which the code is stored.
  • Quantity | Tag - Integer block number or default block parameter
{
"jsonrpc": "2.0",
"method": "quai_getCode",
"params": ["0x421bc7323295c6b7f2f75fc4c854d4fb600e69e8","0x1"],
"id": 1
}

Returns

  • bytecode: Data - Bytecode stored at the address
{
"jsonrpc":"2.0",
"id":1,
"result":"0x6080604052348015600f57600080fd5b50607e8061001e6000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c8063037a417c14602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000600190509056fea165627a7a72305820e710d7394e9965c17ead6bb53757a23caee28d75a0a02b483638015a49dac6070029"
}

quai_getStorageAt

Returns the value from a storage position at an address.

Input Parameters

  • address: Data - 20 bytes, address of the storage
  • position: Quantity - Value corresponding to the storage position.
  • Quantity | Tag - Integer block number or default block parameter
{
"jsonrpc": "2.0",
"method": "quai_getStorageAt",
"params": [
"0x421bc7323295c6b7f2f75fc4c854d4fb600e69e8",
"0x0000000000000000000000000000000000000000000000000000000000000003",
"latest"
],
"id": 1
}

Returns

  • storageValue: Data - Storage value at the provided position
{
"jsonrpc":"2.0",
"id":1,
"result":"0x00000000000000000000000000000000000000000000000000000000000004d2"
}

quai_call

Executes a new message call without creating a transaction on chain.

Input Parameters

  • Object - The transaction call object:
    • from: Data - 20 bytes, address the transaction is being sent from. (optional)
    • to: Data - 20 bytes, address the transaction is being sent to.
    • gas: Quantity - Integer of the gas provided for the transaction execution. (optional)
    • gasPrice: Quantity - Integer of the gasPrice used for each paid gas. (optional)
    • value: Quantity - Integer of the value sent within the transaction. (optional)
    • data: Data - The compiled code of a contract OR the hash of the invoked method signature and encoded parameters. (optional)
  • Quantity | Tag - Integer block number or default block parameter
{
"jsonrpc": "2.0",
"method": "quai_call",
"params": [
{
"from": "0x02E4dD4F66E018fD2bddf57467D4bB359D72b705",
"to": "0x0864B3aab87584b337a92aB1fCfCcf6dad2463Db",
"gas": "0x5208",
"value": "0x10F2C",
"data": "0x"
},
"latest"
],
"id": 1
}

Returns

  • callData: Data - Return value of the executed contract.
{
"jsonrpc":"2.0",
"id":1,
"result":"0x"
}

quai_sendRawTransaction

Creates new message call transaction or a contract creation for signed transactions.

Input Parameters

  • transaction: Data - Raw bytecode of the signed and serialized transaction
{
"jsonrpc": "2.0",
"method": "quai_sendRawTransaction",
"params": [