IoTeX JSON-RPC API Reference

BlockEden.xyz provides comprehensive support for the IoTeX JSON-RPC specification, including all standard methods plus debug and trace APIs for advanced use cases. This reference covers all available methods with detailed parameters, return values, and code examples.

Standard RPC Methods

Account & Balance Methods

eth_getBalance

Get the balance of an account at a given block.

Parameters:

address (string) - 20-byte address to check for balance
blockNumber (string) - Block number in hex, or "latest", "earliest", "pending"

Returns: Balance in wei as a hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4", "latest"],
    "id": 1
  }'

// Using Web3.js
const balance = await web3.eth.getBalance('0x742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4');

// Using Ethers.js
const balance = await provider.getBalance('0x742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4');

eth_getTransactionCount

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

Parameters:

address (string) - 20-byte address
blockNumber (string) - Block number in hex, or "latest", "earliest", "pending"

Returns: Transaction count as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionCount",
    "params": ["0x742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4", "latest"],
    "id": 1
  }'

eth_getCode

Get the code at a given address.

Parameters:

address (string) - 20-byte address
blockNumber (string) - Block number in hex, or "latest", "earliest", "pending"

Returns: Code as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getCode",
    "params": ["0xA0b86a33E6c0e4A2a2a5FB1C6A6D6a30BF8b6B3a", "latest"],
    "id": 1
  }'

Block Methods

eth_blockNumber

Get the current block number.

Parameters: None

Returns: Current block number as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

eth_getBlockByNumber

Get block information by block number.

Parameters:

blockNumber (string) - Block number in hex, or "latest", "earliest", "pending"
fullTransactions (boolean) - If true, returns full transaction objects; if false, only hashes

Returns: Block object or null

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": ["latest", true],
    "id": 1
  }'

eth_getBlockByHash

Get block information by block hash.

Parameters:

blockHash (string) - 32-byte block hash
fullTransactions (boolean) - If true, returns full transaction objects; if false, only hashes

Returns: Block object or null

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByHash",
    "params": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", false],
    "id": 1
  }'

Transaction Methods

eth_getTransactionByHash

Get transaction information by transaction hash.

Parameters:

transactionHash (string) - 32-byte transaction hash

Returns: Transaction object or null

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByHash",
    "params": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"],
    "id": 1
  }'

eth_getTransactionReceipt

Get transaction receipt by transaction hash.

Parameters:

transactionHash (string) - 32-byte transaction hash

Returns: Transaction receipt object or null

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"],
    "id": 1
  }'

eth_sendRawTransaction

Submit a signed transaction to the network.

Parameters:

signedTransaction (string) - Signed transaction data as hex string

Returns: Transaction hash

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0xf86c808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a04f4c17305743700648bc4f6cd3038ec6f6af0df73e31757d8a17c7e9e1f3c7fd2a053a8ffdc8ab1f4b5a1e4d9b4a2c3a6b4a6e1e8c4b4d6c6d6e1b4a6e1e8c4b4"],
    "id": 1
  }'

Smart Contract Interaction

eth_call

Execute a smart contract function call without creating a transaction.

Parameters:

callObject (object) - Call parameters
- to (string) - Contract address
- data (string) - Encoded function call data
- from (string, optional) - Sender address
- gas (string, optional) - Gas limit
- gasPrice (string, optional) - Gas price
- value (string, optional) - Value to send
blockNumber (string) - Block number in hex, or "latest", "earliest", "pending"

Returns: Return value of the call

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [
      {
        "to": "0xA0b86a33E6c0e4A2a2a5FB1C6A6D6a30BF8b6B3a",
        "data": "0x70a08231000000000000000000000000742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4"
      },
      "latest"
    ],
    "id": 1
  }'

eth_estimateGas

Estimate gas needed for a transaction.

Parameters:

transactionObject (object) - Transaction parameters
- to (string, optional) - Recipient address
- from (string, optional) - Sender address
- data (string, optional) - Transaction data
- value (string, optional) - Value to send
- gas (string, optional) - Gas limit
- gasPrice (string, optional) - Gas price

Returns: Estimated gas amount as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_estimateGas",
    "params": [
      {
        "to": "0x742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4",
        "value": "0xde0b6b3a7640000"
      }
    ],
    "id": 1
  }'

Gas and Fee Methods

eth_gasPrice

Get current gas price.

Parameters: None

Returns: Current gas price in wei as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_gasPrice",
    "params": [],
    "id": 1
  }'

eth_feeHistory

Get fee history for a range of blocks (EIP-1559).

Parameters:

blockCount (string) - Number of blocks to return fee history for
newestBlock (string) - Block number in hex, or "latest", "earliest", "pending"
rewardPercentiles (array) - Array of percentiles to return (0-100)

Returns: Fee history object

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_feeHistory",
    "params": ["10", "latest", [25, 50, 75]],
    "id": 1
  }'

eth_maxPriorityFeePerGas

Get suggested max priority fee per gas for EIP-1559 transactions.

Parameters: None

Returns: Suggested max priority fee per gas as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_maxPriorityFeePerGas",
    "params": [],
    "id": 1
  }'

Log and Event Methods

eth_getLogs

Get logs matching a filter.

Parameters:

filterObject (object) - Filter parameters
- fromBlock (string, optional) - Starting block
- toBlock (string, optional) - Ending block
- address (string|array, optional) - Contract address(es)
- topics (array, optional) - Array of topic filters
- blockHash (string, optional) - Block hash (cannot be used with fromBlock/toBlock)

Returns: Array of log objects

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [
      {
        "fromBlock": "0x1",
        "toBlock": "latest",
        "address": "0xA0b86a33E6c0e4A2a2a5FB1C6A6D6a30BF8b6B3a",
        "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
      }
    ],
    "id": 1
  }'

Network Information

eth_chainId

Get the chain ID of the current network.

Parameters: None

Returns: Chain ID as hex string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'

net_version

Get the network ID.

Parameters: None

Returns: Network ID as string

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "net_version",
    "params": [],
    "id": 1
  }'

Debug & Trace Methods

Debug Methods

debug_traceTransaction

Trace a transaction and return detailed execution information.

Parameters:

transactionHash (string) - Transaction hash to trace
options (object, optional) - Trace options
- tracer (string) - Type of tracer ("callTracer", "prestateTracer", etc.)
- timeout (string) - Timeout for trace execution

Returns: Trace result object

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      {"tracer": "callTracer"}
    ],
    "id": 1
  }'

debug_traceBlock

Trace all transactions in a block.

Parameters:

blockNumber (string) - Block number in hex, or "latest"
options (object, optional) - Trace options

Returns: Array of trace results for each transaction

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "debug_traceBlock",
    "params": ["latest", {"tracer": "callTracer"}],
    "id": 1
  }'

Trace Methods

trace_transaction

Get trace information for a transaction.

Parameters:

transactionHash (string) - Transaction hash to trace

Returns: Array of trace objects

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "trace_transaction",
    "params": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"],
    "id": 1
  }'

trace_block

Get traces for all transactions in a block.

Parameters:

blockNumber (string) - Block number in hex, or "latest"

Returns: Array of trace objects for all transactions in the block

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "trace_block",
    "params": ["latest"],
    "id": 1
  }'

Batch Requests

You can send multiple RPC calls in a single HTTP request using JSON-RPC batch format:

curl -X POST https://api.blockeden.xyz/iotex/${accessKey} \
  -H "Content-Type: application/json" \
  -d '[
    {
      "jsonrpc": "2.0",
      "method": "eth_blockNumber",
      "params": [],
      "id": 1
    },
    {
      "jsonrpc": "2.0",
      "method": "eth_gasPrice",
      "params": [],
      "id": 2
    },
    {
      "jsonrpc": "2.0",
      "method": "eth_getBalance",
      "params": ["0x742D5Cc6bF2442E8C7c74c7b4Be6AB9d6f10f5B4", "latest"],
      "id": 3
    }
  ]'

Error Handling

Common Error Codes

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid Request	JSON-RPC request is invalid
-32601	Method not found	Method does not exist
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Internal JSON-RPC error
-32000	Server error	IoTeX execution error

Example Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Invalid address format"
  },
  "id": 1
}

Error Handling in Code

async function handleRpcCall(method, params) {
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method,
        params,
        id: 1
      })
    });
    
    const data = await response.json();
    
    if (data.error) {
      throw new Error(`RPC Error ${data.error.code}: ${data.error.message}`);
    }
    
    return data.result;
  } catch (error) {
    console.error('RPC call failed:', error);
    throw error;
  }
}

Performance Tips

1. Use Batch Requests

Combine multiple calls into a single request to reduce latency:

const batchRequest = [
  { jsonrpc: '2.0', method: 'eth_blockNumber', params: [], id: 1 },
  { jsonrpc: '2.0', method: 'eth_gasPrice', params: [], id: 2 }
];

2. Cache Results

Cache responses for data that doesn't change frequently:

const cache = new Map();

async function getCachedBalance(address) {
  const cacheKey = `balance:${address}`;
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const balance = await getBalance(address);
  cache.set(cacheKey, balance);
  setTimeout(() => cache.delete(cacheKey), 60000); // 1 minute cache
  
  return balance;
}

3. Use WebSockets for Real-time Data

For continuous monitoring, WebSockets are more efficient than polling:

const ws = new WebSocket('wss://api.blockeden.xyz/iotex/${accessKey}');

ws.send(JSON.stringify({
  jsonrpc: '2.0',
  method: 'eth_subscribe',
  params: ['newHeads'],
  id: 1
}));

Chain-Specific Features

Mainnet Features

Full archive node access
Debug and trace APIs
MEV protection
Flashbot integration

Testnet Features

Faucet integration
Development tools
Fast sync options
Reset capabilities

Layer 2 Features

Optimistic rollup support
Arbitrum-specific methods
Polygon gas station
Cross-chain messaging

Next Steps

Learn about [WebSocket Connections]./iotex-websockets.md for real-time data streaming
Explore [Web3.js Integration]./iotex-web3-integration.md for JavaScript development
Check out [Ethers.js Integration]./iotex-ethers-integration.md for modern web development
Follow smart contract interaction patterns for advanced use cases

Resources

Cost: 100 CUs / req

Share on Twitter

API Marketplace Featured

Standard RPC Methods​

Account & Balance Methods​

eth_getBalance​

eth_getTransactionCount​

eth_getCode​

Block Methods​

eth_blockNumber​

eth_getBlockByNumber​

eth_getBlockByHash​

Transaction Methods​

eth_getTransactionByHash​

eth_getTransactionReceipt​

eth_sendRawTransaction​

Smart Contract Interaction​

eth_call​

eth_estimateGas​

Gas and Fee Methods​

eth_gasPrice​

eth_feeHistory​

eth_maxPriorityFeePerGas​

Log and Event Methods​

eth_getLogs​

Network Information​

eth_chainId​

net_version​

Debug & Trace Methods​

Debug Methods​

debug_traceTransaction​

debug_traceBlock​

Trace Methods​

trace_transaction​

trace_block​

Batch Requests​

Error Handling​

Common Error Codes​

Example Error Response​

Error Handling in Code​

Performance Tips​

1. Use Batch Requests​

2. Cache Results​

3. Use WebSockets for Real-time Data​

Chain-Specific Features​

Mainnet Features​

Testnet Features​

Layer 2 Features​

Next Steps​

Resources​

Standard RPC Methods

Account & Balance Methods

eth_getBalance

eth_getTransactionCount

eth_getCode

Block Methods

eth_blockNumber

eth_getBlockByNumber

eth_getBlockByHash

Transaction Methods

eth_getTransactionByHash

eth_getTransactionReceipt

eth_sendRawTransaction

Smart Contract Interaction

eth_call

eth_estimateGas

Gas and Fee Methods

eth_gasPrice

eth_feeHistory

eth_maxPriorityFeePerGas

Log and Event Methods

eth_getLogs

Network Information

eth_chainId

net_version

Debug & Trace Methods

Debug Methods

debug_traceTransaction

debug_traceBlock

Trace Methods

trace_transaction

trace_block

Batch Requests

Error Handling

Common Error Codes

Example Error Response

Error Handling in Code

Performance Tips

1. Use Batch Requests

2. Cache Results

3. Use WebSockets for Real-time Data

Chain-Specific Features

Mainnet Features

Testnet Features

Layer 2 Features

Next Steps

Resources