JSON-RPC API Reference

The JSON-RPC API is the primary interface for interacting with the IOST Layer 2 network. It follows the Ethereum JSON-RPC specification, making it compatible with existing Ethereum tools and libraries.

Endpoint

The JSON-RPC API endpoint for IOST Layer 2 is: https://l2-mainnet.iost.io

Request Format

All JSON-RPC requests follow this format:

{
  "jsonrpc": "2.0",
  "method": "METHOD_NAME",
  "params": [PARAM1, PARAM2, ...],
  "id": REQUEST_ID
}

API Methods by Category

Chain Information

Method	Description
eth_chainId	Returns the chain ID
eth_blockNumber	Returns the number of the most recent block
eth_syncing	Returns sync status or false
eth_gasPrice	Returns the current gas price in wei
eth_feeHistory	Returns fee history for blocks in specified range

Account Methods

Method	Description
eth_getBalance	Returns account balance at specified block
eth_getCode	Returns code at a given address
eth_getStorageAt	Returns value from storage position
eth_getTransactionCount	Returns number of transactions sent from address
eth_accounts	Returns list of addresses owned by client

Block Methods

Method	Description
eth_getBlockByHash	Returns block information by hash
eth_getBlockByNumber	Returns block information by number
eth_getBlockTransactionCountByHash	Returns number of transactions in block by hash
eth_getBlockTransactionCountByNumber	Returns number of transactions in block by number
eth_getBlockReceipts	Returns all transaction receipts for a block

Transaction Methods

Method	Description
eth_sendRawTransaction	Submits a signed transaction for broadcast
eth_getTransactionByHash	Returns transaction information by hash
eth_getTransactionByBlockHashAndIndex	Returns transaction by block hash and index
eth_getTransactionByBlockNumberAndIndex	Returns transaction by block number and index
eth_getTransactionReceipt	Returns transaction receipt by transaction hash
eth_estimateGas	Estimates gas needed for transaction execution
eth_maxPriorityFeePerGas	Returns suggestion for max priority fee per gas

Contract Methods

Method	Description
eth_call	Executes a contract call without creating a transaction
eth_createAccessList	Creates an access list for a transaction
eth_getLogs	Returns logs matching given filter criteria

Filter Methods

Method	Description
eth_newFilter	Creates filter for state changes
eth_newBlockFilter	Creates filter for new blocks
eth_newPendingTransactionFilter	Creates filter for pending transactions
eth_getFilterChanges	Returns filter changes since last poll
eth_getFilterLogs	Returns all logs matching filter
eth_uninstallFilter	Uninstalls a filter

Network Methods

Method	Description
net_version	Returns network ID
net_listening	Returns true if client is actively listening
net_peerCount	Returns number of peers connected

Common Parameters

Block Parameters

Many methods accept a block parameter that can be:

• Block number in hexadecimal format (e.g. "0x1b4")
• Block hash
• Tag string: "earliest", "latest", "pending"

Address Format

Ethereum-compatible 20-byte hex string with 0x prefix, e.g., "0x71c7656ec7ab88b098defb751b7401b5f6d8976f"

Gas Price/Limit

Gas values are in wei and represented as hex strings, e.g., "0x5d21dba00" for 25 Gwei

Response Format

All successful JSON-RPC responses have this format:

{
  "jsonrpc": "2.0",
  "id": REQUEST_ID,
  "result": RESPONSE_DATA
}

Error responses:

{
  "jsonrpc": "2.0",
  "id": REQUEST_ID,
  "error": {
    "code": ERROR_CODE,
    "message": ERROR_MESSAGE
  }
}

Example Usage

// Using fetch API
async function getBalance(address) {
  const response = await fetch("https://l2-mainnet.iost.io", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "eth_getBalance",
      params: [address, "latest"],
      id: 1
    })
  });
  
  const data = await response.json();
  return data.result;
}

Using with Web3.js

const Web3 = require('web3');
const web3 = new Web3('https://l2-mainnet.iost.io');

// Get latest block
web3.eth.getBlockNumber()
  .then(blockNumber => console.log(`Latest block: ${blockNumber}`));

Using with ethers.js

const { ethers } = require('ethers');
const provider = new ethers.providers.JsonRpcProvider('https://l2-mainnet.iost.io');

// Get account balance
provider.getBalance('0xYourAccountAddress')
  .then(balance => console.log(`Balance: ${ethers.utils.formatEther(balance)} ETH`));

Additional Resources

For complete details on all available methods and parameters, refer to the Ethereum JSON-RPC Specification.