JSON-RPC APIs¶

Introduction¶

Polkadot Hub provides Ethereum compatibility through its JSON-RPC interface, allowing developers to interact with the chain using familiar Ethereum tooling and methods. This document outlines the supported Ethereum JSON-RPC methods and provides examples of how to use them.

This guide uses the Polkadot Hub TestNet endpoint:

https://services.polkadothub-rpc.com/testnet

Available Methods¶

eth_accounts¶

Returns a list of addresses owned by the client. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_accounts",
    "params":[],
    "id":1
}'

eth_blockNumber¶

Returns the number of the most recent block. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_blockNumber",
    "params":[],
    "id":1
}'

eth_call¶

Executes a new message call immediately without creating a transaction. Reference.

Parameters:

• transaction object: The transaction call object.
  • to string: Recipient address of the call. Must be a 20-byte data string.
  • data string: Hash of the method signature and encoded parameters. Must be a data string.
  • from string: (Optional) Sender's address for the call. Must be a 20-byte data string.
  • gas string: (Optional) Gas limit to execute the call. Must be a quantity string.
  • gasPrice string: (Optional) Gas price per unit of gas. Must be a quantity string.
  • value string: (Optional) Value in wei to send with the call. Must be a quantity string.
• blockValue string: (Optional) Block tag or block number to execute the call at. Must be a quantity string or a default block parameter.
• stateOverrides object: (Optional) A mapping of addresses to state overrides. Allows temporary modification of account state for the duration of the call without persisting changes on-chain. Conforms to the Geth state override specification.
  • Key: Account address as a hex string (e.g., "0x1234...")
  • Value: An object with the following optional fields:
    • balance string: (Optional) Fake balance to set for the account. Must be a quantity string.
    • nonce string: (Optional) Fake nonce to set for the account. Must be a quantity string.
    • code string: (Optional) Fake bytecode to inject at the account address. On Polkadot Hub, this field accepts both EVM bytecode and PolkaVM (PVM) bytecode, which is detected automatically via magic bytes.
    • state object: (Optional) Completely replaces all storage slots for the account. A mapping of storage keys to storage values (both as 32-byte hex strings). Unspecified slots are zeroed. Mutually exclusive with stateDiff.
    • stateDiff object: (Optional) Patches only the specified storage slots, leaving all other slots unchanged. A mapping of storage keys to storage values (both as 32-byte hex strings). Mutually exclusive with state.
    • movePrecompileToAddress string: (Optional) Accepted for Geth compatibility but has no effect, as Polkadot Hub does not use relocatable precompile addresses.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_call",
    "params":[{
        "to": "INSERT_RECIPIENT_ADDRESS",
        "data": "INSERT_ENCODED_CALL"
    }, "INSERT_BLOCK_VALUE"],
    "id":1
}'

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_call",
    "params":[{
        "to": "INSERT_RECIPIENT_ADDRESS",
        "data": "INSERT_ENCODED_CALL"
    }, "latest", {
        "INSERT_ADDRESS": {
            "balance": "0xDE0B6B3A7640000"
        }
    }],
    "id":1
}'

eth_chainId¶

Returns the chain ID used for signing transactions. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_chainId",
    "params":[],
    "id":1
}'

eth_estimateGas¶

Estimates gas required for a transaction. Reference.

Parameters:

• transaction object: The transaction call object.
  • to string: Recipient address of the call. Must be a 20-byte data string.
  • data string: Hash of the method signature and encoded parameters. Must be a data string.
  • from string: (Optional) Sender's address for the call. Must be a 20-byte data string.
  • gas string: (Optional) Gas limit to execute the call. Must be a quantity string.
  • gasPrice string: (Optional) Gas price per unit of gas. Must be a quantity string.
  • value string: (Optional) Value in wei to send with the call. Must be a quantity string.
• blockValue string: (Optional) Block tag or block number to execute the call at. Must be a quantity string or a default block parameter.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_estimateGas",
    "params":[{
        "to": "INSERT_RECIPIENT_ADDRESS",
        "data": "INSERT_ENCODED_FUNCTION_CALL"
    }],
    "id":1
}'

Ensure to replace the INSERT_RECIPIENT_ADDRESS and INSERT_ENCODED_CALL with the proper values.

eth_gasPrice¶

Returns the current gas price in Wei. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_gasPrice",
    "params":[],
    "id":1
}'

eth_getBalance¶

Returns the balance of a given address. Reference.

Parameters:

• address string: Address to query balance. Must be a 20-byte data string.
• blockValue string: (Optional) The block value to be fetched. Must be a quantity string or a default block parameter.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getBalance",
    "params":["INSERT_ADDRESS", "INSERT_BLOCK_VALUE"],
    "id":1
}'

Ensure to replace the INSERT_ADDRESS and INSERT_BLOCK_VALUE with the proper values.

eth_getBlockByHash¶

Returns information about a block by its hash. Reference.

Parameters:

• blockHash string: The hash of the block to retrieve. Must be a 32 byte data string.
• fullTransactions boolean: If true, returns full transaction details; if false, returns only transaction hashes.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockByHash",
    "params":["INSERT_BLOCK_HASH", INSERT_BOOLEAN],
    "id":1
}'

Ensure to replace the INSERT_BLOCK_HASH and INSERT_BOOLEAN with the proper values.

eth_getBlockByNumber¶

Returns information about a block by its number. Reference.

Parameters:

• blockValue string: (Optional) The block value to be fetched. Must be a quantity string or a default block parameter.
• fullTransactions boolean: If true, returns full transaction details; if false, returns only transaction hashes.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockByNumber",
    "params":["INSERT_BLOCK_VALUE", INSERT_BOOLEAN],
    "id":1
}'

Ensure to replace the INSERT_BLOCK_VALUE and INSERT_BOOLEAN with the proper values.

eth_getBlockTransactionCountByNumber¶

Returns the number of transactions in a block from a block number. Reference.

Parameters:

• blockValue string: The block value to be fetched. Must be a quantity string or a default block parameter.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockTransactionCountByNumber",
    "params":["INSERT_BLOCK_VALUE"],
    "id":1
}'

Ensure to replace the INSERT_BLOCK_VALUE with the proper values.

eth_getBlockTransactionCountByHash¶

Returns the number of transactions in a block from a block hash. Reference.

Parameters:

• blockHash string: The hash of the block to retrieve. Must be a 32 byte data string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockTransactionCountByHash",
    "params":["INSERT_BLOCK_HASH"],
    "id":1
}'

Ensure to replace the INSERT_BLOCK_HASH with the proper values.

eth_getCode¶

Returns the code at a given address. Reference.

Parameters:

• address string: Contract or account address to query code. Must be a 20-byte data string.
• blockValue string: (Optional) The block value to be fetched. Must be a quantity string or a default block parameter.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getCode",
    "params":["INSERT_ADDRESS", "INSERT_BLOCK_VALUE"],
    "id":1
}'

Ensure to replace the INSERT_ADDRESS and INSERT_BLOCK_VALUE with the proper values.

eth_getLogs¶

Returns an array of all logs matching a given filter object. Reference.

Parameters:

• filter object: The filter object.
  • fromBlock string: (Optional) Block number or tag to start from. Must be a quantity string or a default block parameter.
  • toBlock string: (Optional) Block number or tag to end at. Must be a quantity string or a default block parameter.
  • address ++"string" or "array of strings"++: (Optional) Contract address or a list of addresses from which to get logs. Must be a 20-byte data string.
  • topics array of strings: (Optional) Array of topics for filtering logs. Each topic can be a single 32 byte data string or an array of such strings (meaning OR).
  • blockhash string: (Optional) Hash of a specific block. Cannot be used with fromBlock or toBlock. Must be a 32 byte data string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getLogs",
    "params":[{
        "fromBlock": "latest",
        "toBlock": "latest"
    }],
    "id":1
}'

eth_getStorageAt¶

Returns the value from a storage position at a given address. Reference.

Parameters:

• address string: Contract or account address to query code. Must be a 20-byte data string.
• storageKey string: Position in storage to retrieve data from. Must be a quantity string.
• blockValue string: (Optional) The block value to be fetched. Must be a quantity string or a default block parameter.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getStorageAt",
    "params":["INSERT_ADDRESS", "INSERT_STORAGE_KEY", "INSERT_BLOCK_VALUE"],
    "id":1
}'

Ensure to replace the INSERT_ADDRESS, INSERT_STORAGE_KEY, and INSERT_BLOCK_VALUE with the proper values.

eth_getTransactionCount¶

Returns the number of transactions sent from an address (nonce). Reference.

Parameters:

• address string: Address to query balance. Must be a 20-byte data string.
• blockValue string: (Optional) The block value to be fetched. Must be a quantity string or a default block parameter.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionCount",
    "params":["INSERT_ADDRESS", "INSERT_BLOCK_VALUE"],
    "id":1
}'

Ensure to replace the INSERT_ADDRESS and INSERT_BLOCK_VALUE with the proper values.

eth_getTransactionByHash¶

Returns information about a transaction by its hash. Reference.

Parameters:

• transactionHash string: The hash of the transaction. Must be a 32 byte data string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionByHash",
    "params":["INSERT_TRANSACTION_HASH"],
    "id":1
}'

Ensure to replace the INSERT_TRANSACTION_HASH with the proper values.

eth_getTransactionByBlockNumberAndIndex¶

Returns information about a transaction by block number and transaction index. Reference.

Parameters:

• blockValue string: The block value to be fetched. Must be a quantity string or a default block parameter.
• transactionIndex string: The index of the transaction in the block. Must be a quantity string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionByBlockNumberAndIndex",
    "params":["INSERT_BLOCK_VALUE", "INSERT_TRANSACTION_INDEX"],
    "id":1
}'

Ensure to replace the INSERT_BLOCK_VALUE and INSERT_TRANSACTION_INDEX with the proper values.

eth_getTransactionByBlockHashAndIndex¶

Returns information about a transaction by block hash and transaction index. Reference.

Parameters:

• blockHash string: The hash of the block. Must be a 32 byte data string.
• transactionIndex string: The index of the transaction in the block. Must be a quantity string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionByBlockHashAndIndex",
    "params":["INSERT_BLOCK_HASH", "INSERT_TRANSACTION_INDEX"],
    "id":1
}'

Ensure to replace the INSERT_BLOCK_HASH and INSERT_TRANSACTION_INDEX with the proper values.

eth_getTransactionReceipt¶

Returns the receipt of a transaction by transaction hash. Reference.

Parameters:

• transactionHash string: The hash of the transaction. Must be a 32 byte data string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionReceipt",
    "params":["INSERT_TRANSACTION_HASH"],
    "id":1
}'

Ensure to replace the INSERT_TRANSACTION_HASH with the proper values.

eth_maxPriorityFeePerGas¶

Returns an estimate of the current priority fee per gas, in Wei, to be included in a block.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_maxPriorityFeePerGas",
    "params":[],
    "id":1
}'

eth_sendRawTransaction¶

Submits a raw transaction. Reference.

Parameters:

• callData string: Signed transaction data. Must be a data string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_sendRawTransaction",
    "params":["INSERT_CALL_DATA"],
    "id":1
}'

Ensure to replace the INSERT_CALL_DATA with the proper values.

eth_sendTransaction¶

Creates and sends a new transaction. Reference.

Parameters:

• transaction object: The transaction object.
  • from string: Address sending the transaction. Must be a 20-byte data string.
  • to string: (Optional) Recipient address. No need to provide this value when deploying a contract. Must be a 20-byte data string.
  • gas string: (optional, default: 90000) gas limit for execution. Must be a quantity string.
  • gasPrice string: (Optional) Gas price per unit. Must be a quantity string.
  • value string: (Optional) Amount of Ether to send. Must be a quantity string.
  • data string: (Optional) Contract bytecode or encoded method call. Must be a data string.
  • nonce string: (Optional) Transaction nonce. Must be a quantity string.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_sendTransaction",
    "params":[{
        "from": "INSERT_SENDER_ADDRESS",
        "to": "INSERT_RECIPIENT_ADDRESS",
        "gas": "INSERT_GAS_LIMIT",
        "gasPrice": "INSERT_GAS_PRICE",
        "value": "INSERT_VALUE",
        "input": "INSERT_INPUT_DATA",
        "nonce": "INSERT_NONCE"
    }],
    "id":1
}'

Ensure to replace the INSERT_SENDER_ADDRESS, INSERT_RECIPIENT_ADDRESS, INSERT_GAS_LIMIT, INSERT_GAS_PRICE, INSERT_VALUE, INSERT_INPUT_DATA, and INSERT_NONCE with the proper values.

eth_syncing¶

Returns an object with syncing data or false if not syncing. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"eth_syncing",
    "params":[],
    "id":1
}'

net_listening¶

Returns true if the client is actively listening for network connections, otherwise false. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"net_listening",
    "params":[],
    "id":1
}'

net_peerCount¶

Returns the number of peers connected to the client.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"net_peerCount",
    "params":[],
    "id":1
}'

net_version¶

Returns the current network ID as a string. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"net_version",
    "params":[],
    "id":1
}'

system_health¶

Returns information about the health of the system.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"system_health",
    "params":[],
    "id":1
}'

web3_clientVersion¶

Returns the current client version. Reference.

Parameters:

None.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"web3_clientVersion",
    "params":[],
    "id":1
}'

debug_traceBlockByNumber¶

Traces a block's execution by its number and returns a detailed execution trace for each transaction.

Parameters:

• blockValue string: The block number or tag to trace. Must be a quantity string or a default block parameter.
• options object: (Optional) An object containing tracer options.
  • tracer string: The name of the tracer to use (e.g., "callTracer", "opTracer").
  • Other tracer-specific options may be supported.

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"debug_traceBlockByNumber",
    "params":["INSERT_BLOCK_VALUE", {"tracer": "callTracer"}],
    "id":1
}'

Ensure to replace INSERT_BLOCK_VALUE with a proper block number if needed.

debug_traceTransaction¶

Traces the execution of a single transaction by its hash and returns a detailed execution trace.

Parameters:

• transactionHash string: The hash of the transaction to trace. Must be a 32 byte data string.
• options object: (Optional) An object containing tracer options (e.g., tracer: "callTracer").

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"debug_traceTransaction",
    "params":["INSERT_TRANSACTION_HASH", {"tracer": "callTracer"}],
    "id":1
}'

Ensure to replace the INSERT_TRANSACTION_HASH with the proper value.

debug_traceCall¶

Executes a new message call and returns a detailed execution trace without creating a transaction on the blockchain.

Parameters:

• transaction object: The transaction call object, similar to eth_call parameters.
  • to string: Recipient address of the call. Must be a 20-byte data string.
  • data string: Hash of the method signature and encoded parameters. Must be a data string.
  • from string: (Optional) Sender's address for the call. Must be a 20-byte data string.
  • gas string: (Optional) Gas limit to execute the call. Must be a quantity string.
  • gasPrice string: (Optional) Gas price per unit of gas. Must be a quantity string.
  • value string: (Optional) Value in wei to send with the call. Must be a quantity string.
• blockValue string: (Optional) Block tag or block number to execute the call at. Must be a quantity string or a default block parameter.
• options object: (Optional) An object containing tracer options (e.g., tracer: "callTracer").

Example:

curl -X POST https://services.polkadothub-rpc.com/testnet \
-H "Content-Type: application/json" \
--data '{
    "jsonrpc":"2.0",
    "method":"debug_traceCall",
    "params":[{
        "from": "INSERT_SENDER_ADDRESS",
        "to": "INSERT_RECIPIENT_ADDRESS",
        "data": "INSERT_ENCODED_CALL"
    }, "INSERT_BLOCK_VALUE", {"tracer": "callTracer"}],
    "id":1
}'

Ensure to replace the INSERT_SENDER_ADDRESS, INSERT_RECIPIENT_ADDRESS, INSERT_ENCODED_CALL, and INSERT_BLOCK_VALUE with the proper value.

Response Format¶

All responses follow the standard JSON-RPC 2.0 format:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": ... // The return value varies by method
}

Error Handling¶

If an error occurs, the response will include an error object:

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32000,
        "message": "Error message here"
    }
}