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://eth-rpc-testnet.polkadot.io

Available Methods

eth_accounts

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

Parameters:

None.

Example:

eth_accounts

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_blockNumber

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

Basic

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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
}'

Ensure to replace INSERT_RECIPIENT_ADDRESS, INSERT_ENCODED_CALL, and INSERT_BLOCK_VALUE with the appropriate values.

With state overrides

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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
}'

In this example, the account at INSERT_ADDRESS is temporarily assigned a balance of 1 native token (10^18 in its smallest denomination) for the duration of the call. Ensure to replace INSERT_RECIPIENT_ADDRESS, INSERT_ENCODED_CALL, and INSERT_ADDRESS with the appropriate values.

Differences from Ethereum

Polkadot Hub's eth_call state overrides are fully compatible with the Geth state override specification. One Polkadot-specific extension is that the code field accepts both EVM bytecode and PolkaVM (PVM) bytecode, detected automatically via magic bytes at the start of the blob.

---

eth_chainId

Returns the chain ID used for signing transactions. Reference.

Parameters:

None.

Example:

eth_chainId

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_estimateGas

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_gasPrice

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getBalance

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getBlockByHash

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getBlockByNumber

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getBlockTransactionCountByNumber

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getBlockTransactionCountByHash

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getCode

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getLogs

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getStorageAt

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getTransactionCount

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getTransactionByHash

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getTransactionByBlockNumberAndIndex

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getTransactionByBlockHashAndIndex

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_getTransactionReceipt

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_maxPriorityFeePerGas

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_sendRawTransaction

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_sendTransaction

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

eth_syncing

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

net_listening

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

net_peerCount

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

net_version

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

system_health

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

web3_clientVersion

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

debug_traceBlockByNumber

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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:

debug_traceTransaction

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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.

Differences from Ethereum (Geth)

When using the default struct logger (opcode tracer), there is a difference in how gasCost is calculated for CALL-like opcodes (CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2):

• Geth behavior: The gasCost includes the opcode's intrinsic cost plus all gas forwarded to child calls.
• Polkadot Hub behavior: The gasCost includes only the opcode's intrinsic cost, excluding forwarded gas. The intrinsic cost covers:
  • Base cost of the CALL opcode.
  • Post-call costs (for example, copying return data back to the caller's memory).

---

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:

debug_traceCall

curl -X POST https://eth-rpc-testnet.polkadot.io \
-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"
    }
}