JSON-RPC
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.
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.
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"
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"
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:
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.
Returns the gas price.
No input
params
are required for this method.{
"jsonrpc": "2.0",
"method": "quai_gasPrice",
"params": [],
"id": 1
}
gasPrice: Quantity
- Current gas price{
"jsonrpc":"2.0",
"id":"1",
"result":"0x3b9aca01" // 1000000001
}
Returns the max priority fee per unit of gas.
No input
params
are required for this method.{
"jsonrpc": "2.0",
"method": "quai_maxPriorityFeePerGas",
"params": [],
"id": 1
}
priorityFeePerGas: Quantity
- Current max priority fee per gas{
"jsonrpc":"2.0",
"id":"1",
"result":"0x3b9aca01" // 1000000001
}
Returns the fee history for a specific range of blocks.
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.
{
"jsonrpc": "2.0",
"method": "quai_feeHistory",
"params": ["0x2", "0x8", [2, 4, 6]],
"id": 1
}
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 blockgasUsedRatio: 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]
}
}
Returns an indicator of whether the client is actively syncing.
No input
params
are required for this method.{
"jsonrpc": "2.0",
"method": "quai_syncing",
"params": [],
"id": 1
}
syncing: Boolean
-true
if the client is actively syncing,false
otherwise.
{
"jsonrpc":"2.0",
"id":"1",
"result":"false"
}
Returns the current chain ID.
No input
params
are required for this method.{
"jsonrpc": "2.0",
"method": "quai_chainId",
"params": [],
"id": 1
}
chainId: Quantity
- Current integer chain ID.
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x1" // 1
}
Returns the current node location or context.
No input
params
are required for this method.{
"jsonrpc": "2.0",
"method": "quai_nodeLocation",
"params": [],
"id": 1
}
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
}
Returns the latest block number.
No input
params
are required for this method.{
"jsonrpc": "2.0",
"method": "quai_blockNumber",
"params": [],
"id": 1
}
blockNumber: Quantity
- Integer number of the most recent block.
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x2b7"
}
Returns the balance of the specified address.
address: Data
- 20 bytes, the address being queried.
{
"jsonrpc": "2.0",
"method": "quai_getBalance",
"params": ["0x421bc7323295c6b7f2f75fc4c854d4fb600e69e8","latest"],
"id": 1
}
balance: Quantity
- Integer balance of the address in wei.
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x3f28cb71571c7" // 1111111111111111
}
Returns the Merkle-Proof for a given account and optional storage keys.
address: Data
- 20 bytes, the address for which the Merkle-Proof is being returned.storageKeys: Array
- String array of storage keys.
{
"jsonrpc": "2.0",
"method": "quai_getProof",
"params": [
"0x7F0d15C7FAae65896648C8273B6d7E43f58Fa842",
["0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"],
"latest"
],
"id": 1
}
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 thestorageRoot
.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": []
}
]
}
}
Returns the hash of the block header for a specific block number.
blockNumber: Quantity
- the integer block number.
// Request Body
{
"jsonrpc": "2.0",
"method": "quai_getHeaderHashByNumber",
"params": ["0x15d"],
"id": 1
}
blockHash: Data
- 32 bytes, the hash of the block header.
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x0000024ccfb37a6e7ba09a3541c6c1e614e64809cc1b742acad2451e22764d6c"
}
Returns the block header given the header hash.
blockHash: Data
- 32 bytes, the hash of the block header.
{
"jsonrpc": "2.0",
"method": "quai_getHeaderByHash",
"params": ["0x0000024ccfb37a6e7ba09a3541c6c1e614e64809cc1b742acad2451e22764d6c"],
"id": 1
}
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"
}
}
Returns the block header given the block number.
blockNumber: Quantity
- Integer block number
{
"jsonrpc": "2.0",
"method": "quai_getHeaderByNumber",
"params": ["0x15d"],
"id": 1
}
Returns the block data for a specific block number.
blockNumber: Quantity
- Integer block numberfull: Boolean
- If true, returns the full transaction objects. If false, returns only hashes of the transactions
{
"jsonrpc": "2.0",
"method": "quai_getBlockByNumber",
"params": ["0x15d", true],
"id": 1
}
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": []
}
}
Returns the block data for a specific block header hash.
blockHash: Data
- 32 bytes, the hash of the block headerfull: Boolean
- Iftrue
, returns the full transaction objects, iffalse
returns the transaction hashes. Defaults tofalse
.
{
"jsonrpc": "2.0",
"method": "quai_getHeaderByHash",
"params": ["0x0000023ee6f37ecaa871f52068e6c020b899d6bafc6efa7a6ce11a062bd2db2e", true],
"id": 1
}
Returns the uncle block data for a specific block number and uncle index.
blockNumber: Quantity
- Integer block numberuncleIndex: Quantity
- Integer uncle index.
{
"jsonrpc": "2.0",
"method": "quai_getUncleByBlockNumberAndIndex",
"params": ["0x15d","0x0"],
"id": 1
}
Returns the uncle block data for a specific block hash and uncle index.
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 the uncle count for a specific block.
blockNumber: Quantity
- Integer block number.
{
"jsonrpc": "2.0",
"method": "quai_getUncleCountByBlockNumber",
"params": ["0x15d"],
"id": 1
}
uncleCount: Quantity
- Integer number of uncles in this block.
{
"jsonrpc":"2.0",
"id":1,
"result":"0x2"
}
Returns the uncle count for a specific block hash.
blockHash: Data
- 32 bytes, hash of the block header.
{
"jsonrpc": "2.0",
"method": "quai_getUncleCountByBlockHash",
"params": ["0x00000040ba9145742407a455bf07aa33cdd014fd4cd630970906e9f40064d033"],
"id": 1
}
uncleCount: Quantity
- Integer number of uncles in this block.
{
"jsonrpc":"2.0",
"id":1,
"result":"0x2"
}
Returns the code stored at the given address.
address: Data
- 20 bytes, the address at which the code is stored.
{
"jsonrpc": "2.0",
"method": "quai_getCode",
"params": ["0x421bc7323295c6b7f2f75fc4c854d4fb600e69e8","0x1"],
"id": 1
}
bytecode: Data
- Bytecode stored at the address
{
"jsonrpc":"2.0",
"id":1,
"result":"0x6080604052348015600f57600080fd5b50607e8061001e6000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c8063037a417c14602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000600190509056fea165627a7a72305820e710d7394e9965c17ead6bb53757a23caee28d75a0a02b483638015a49dac6070029"
}
Returns the value from a storage position at an address.
address: Data
- 20 bytes, address of the storageposition: Quantity
- Value corresponding to the storage position.
{
"jsonrpc": "2.0",
"method": "quai_getStorageAt",
"params": [
"0x421bc7323295c6b7f2f75fc4c854d4fb600e69e8",
"0x0000000000000000000000000000000000000000000000000000000000000003",
"latest"
],
"id": 1
}
storageValue: Data
- Storage value at the provided position
{
"jsonrpc":"2.0",
"id":1,
"result":"0x00000000000000000000000000000000000000000000000000000000000004d2"
}
Executes a new message call without creating a transaction on chain.
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)
{
"jsonrpc": "2.0",
"method": "quai_call",
"params": [
{
"from": "0x02E4dD4F66E018fD2bddf57467D4bB359D72b705",
"to": "0x0864B3aab87584b337a92aB1fCfCcf6dad2463Db",
"gas": "0x5208",
"value": "0x10F2C",
"data": "0x"
},
"latest"
],
"id": 1
}
callData: Data
- Return value of the executed contract.
{
"jsonrpc":"2.0",
"id":1,
"result":"0x"
}
Creates new message call transaction or a contract creation for signed transactions.
transaction: Data
- Raw bytecode of the signed and serialized transaction
{
"jsonrpc": "2.0",
"method": "quai_sendRawTransaction",
"params": [