# JSON-RPC API Somnia exposes an RPC API compatible with the Ethereum JSON-RPC specification. The mainnet public RPC endpoint is `https://api.infra.mainnet.somnia.network` (chain ID `0x13a7` / 5031). ## Methods by Name | Method | Compatibility | [Requires Node Ready](#requires-node-ready) | WebSocket Only | | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -------------- | | [debug\_traceBlockByHash](#debug_traceblockbyhash) | [Geth debug](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtraceblockbyhash) | Yes | | | [debug\_traceBlockByNumber](#debug_traceblockbynumber) | [Geth debug](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtraceblockbynumber) | Yes | | | [debug\_traceCall](#debug_tracecall) | [Geth debug](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtracecall) | Yes | | | [debug\_traceTransaction](#debug_tracetransaction) | [Geth debug](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtracetransaction) | Yes | | | [eth\_accounts](#eth_accounts) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_accounts) | | | | [eth\_blockNumber](#eth_blocknumber) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_blocknumber) | | | | [eth\_call](#eth_call) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_call) | Yes | | | [eth\_chainId](#eth_chainid) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_chainid) | | | | [eth\_createAccessList](#eth_createaccesslist) | [Execution APIs](https://ethereum.github.io/execution-apis/api/methods/eth_createAccessList) | Yes | | | [eth\_estimateGas](#eth_estimategas) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_estimategas) | Yes | | | [eth\_feeHistory](#eth_feehistory) | [Execution APIs](https://ethereum.github.io/execution-apis/api/methods/eth_feeHistory) | | | | [eth\_gasPrice](#eth_gasprice) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gasprice) | | | | [eth\_getBalance](#eth_getbalance) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getbalance) | | | | [eth\_getBlockByHash](#eth_getblockbyhash) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblockbyhash) | | | | [eth\_getBlockByNumber](#eth_getblockbynumber) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblockbynumber) | | | | [eth\_getBlockReceipts](#eth_getblockreceipts) | [Execution APIs](https://ethereum.github.io/execution-apis/api/methods/eth_getBlockReceipts) | | | | [eth\_getBlockTransactionCountByHash](#eth_getblocktransactioncountbyhash) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) | | | | [eth\_getBlockTransactionCountByNumber](#eth_getblocktransactioncountbynumber) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) | | | | [eth\_getCode](#eth_getcode) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getcode) | Yes | | | [eth\_getFilterChanges](#eth_getfilterchanges) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getfilterchanges) | | | | [eth\_getFilterLogs](#eth_getfilterlogs) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getfilterlogs) | | | | [eth\_getHeaderByHash](#eth_getheaderbyhash) | [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#ethgetheaderbyhash) | | | | [eth\_getHeaderByNumber](#eth_getheaderbynumber) | [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#ethgetheaderbynumber) | | | | [eth\_getLogs](#eth_getlogs) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getlogs) | | | | [eth\_getStorageAt](#eth_getstorageat) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getstorageat) | Yes | | | [eth\_getTransactionByBlockHashAndIndex](#eth_gettransactionbyblockhashandindex) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionbyblockhashandindex) | | | | [eth\_getTransactionByBlockNumberAndIndex](#eth_gettransactionbyblocknumberandindex) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionbyblocknumberandindex) | | | | [eth\_getTransactionByHash](#eth_gettransactionbyhash) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionbyhash) | | | | [eth\_getTransactionCount](#eth_gettransactioncount) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactioncount) | Yes | | | [eth\_getTransactionReceipt](#eth_gettransactionreceipt) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) | | | | [eth\_maxPriorityFeePerGas](#eth_maxpriorityfeepergas) | [Execution APIs](https://ethereum.github.io/execution-apis/api/methods/eth_maxPriorityFeePerGas) | | | | [eth\_newBlockFilter](#eth_newblockfilter) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_newblockfilter) | | | | [eth\_newFilter](#eth_newfilter) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_newfilter) | | | | [eth\_newPendingTransactionFilter](#eth_newpendingtransactionfilter) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) | | | | [eth\_sendRawTransaction](#eth_sendrawtransaction) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_sendrawtransaction) | Yes | | | [eth\_subscribe](#eth_subscribe) | [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-subscribe-unsubscribe) | | Yes | | [eth\_syncing](#eth_syncing) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_syncing) | | | | [eth\_uninstallFilter](#eth_uninstallfilter) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#eth_uninstallfilter) | | | | [eth\_unsubscribe](#eth_unsubscribe) | [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-subscribe-unsubscribe) | | | | [net\_listening](#net_listening) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#net_listening) | | | | [net\_version](#net_version) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#net_version) | | | | [realtime\_sendRawTransaction](#realtime_sendrawtransaction) | Somnia-specific | Yes | | | [somnia\_getBlockByHash](#somnia_getblockbyhash) | Somnia-specific | | | | [somnia\_getBlockByNumber](#somnia_getblockbynumber) | Somnia-specific | | | | [somnia\_getPrivilegedTransactionReceiptsForBlockByHash](#somnia_getprivilegedtransactionreceiptsforblockbyhash) | Somnia-specific | | | | [somnia\_getPrivilegedTransactionReceiptsForBlockByNumber](#somnia_getprivilegedtransactionreceiptsforblockbynumber) | Somnia-specific | | | | [somnia\_getSessionAddress](#somnia_getsessionaddress) | Somnia-specific | | | | [somnia\_getStatistics](#somnia_getstatistics) | Somnia-specific | | | | [somnia\_isReady](#somnia_isready) | Somnia-specific | | | | [somnia\_isReadyWithErrorCode](#somnia_isreadywitherrorcode) | Somnia-specific | | | | [somnia\_nodePublicKeys](#somnia_nodepublickeys) | Somnia-specific | | | | [somnia\_reactivityGetSubscriptionInfo](#somnia_reactivitygetsubscriptioninfo) | Somnia-specific, testnet only | | | | [somnia\_reactivityGetSubscriptions](#somnia_reactivitygetsubscriptions) | Somnia-specific, testnet only | | | | [somnia\_sendSessionTransaction](#somnia_sendsessiontransaction) | Somnia-specific | | | | [web3\_clientVersion](#web3_clientversion) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#web3_clientversion) | | | | [web3\_sha3](#web3_sha3) | [Ethereum standard](https://ethereum.org/developers/docs/apis/json-rpc/#web3_sha3) | | | ## Methods by Category ### Network / Web3 #### `net_version` Returns the network ID. * **Parameters:** *(none)* * **Returns:** `quantity` (uint256) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#net_version) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"net_version","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x13a7"} ``` > **Note:** This is currently non-conformant with the [Ethereum JSON-RPC spec](https://ethereum.github.io/execution-apis/api/methods/net_version/), which specifies that the return value is a decimal string. In future Somnia will switch to this form:
> > ``` > {"jsonrpc":"2.0","id":1,"result":"5031"} > ``` *** #### `net_listening` Returns `true` if the node is listening for connections. * **Parameters:** *(none)* * **Returns:** `bool` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#net_listening) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":true} ``` *** #### `web3_clientVersion` Returns the Somnia client version string. * **Parameters:** *(none)* * **Returns:** `string` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#web3_clientversion) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"somnia-92fe2faf8cbcd24-release"} ``` *** #### `web3_sha3` Returns the Keccak-256 hash of the given data. * **Parameters:** `data` (hex) * **Returns:** `hash` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#web3_sha3) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f"],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8"} ``` ***
### Chain State #### `eth_chainId` Returns the chain ID. * **Parameters:** *(none)* * **Returns:** `quantity` (uint256) * **Compatibility:** [EIP-695](https://eips.ethereum.org/EIPS/eip-695), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_chainid) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x13a7"} ``` *** #### `eth_syncing` Returns `true` while the node is still syncing, `false` once ready. Unlike standard Ethereum clients, Somnia returns bool only -- it does not return a sync-status object. * **Parameters:** *(none)* * **Returns:** `bool` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_syncing) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":false} ``` *** #### `eth_blockNumber` Returns the latest block number. * **Parameters:** *(none)* * **Returns:** `quantity` (block number) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_blocknumber) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0xff7809e"} ``` *** #### `eth_accounts` Returns the list of accounts owned by the node (empty for public RPC endpoints). * **Parameters:** *(none)* * **Returns:** `address[]` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_accounts) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":[]} ``` ***
### Account State #### `eth_getBalance` Returns the balance of an account in wei. * **Parameters:** `address`, `blockLabel` (`"latest"`, `"earliest"`, `"pending"`, or hex block number) * **Returns:** `quantity` (uint256) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getbalance) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getBalance", "params":["0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "0xfebbe5e"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x5a957142cf2e47706c"} ``` *** #### `eth_getTransactionCount` Returns the nonce (number of transactions sent) for an account. * **Parameters:** `address`, `blockLabel` * **Returns:** `quantity` (uint64) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactioncount) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getTransactionCount", "params":["0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "latest"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x12"} ``` *** #### `eth_getCode` Returns the bytecode at an address (`"0x"` for addresses without code). * **Parameters:** `address`, `blockLabel` * **Returns:** `bytes` (hex) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getcode) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getCode", "params":["0x4e59b44847b379578588920cA78FbF26c0B4956C", "0xfebbe5e"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3"} ``` *** #### `eth_getStorageAt` Returns the value in a contract's storage slot. * **Parameters:** `address`, `slot` (hex uint256), `blockLabel` * **Returns:** `bytes` (hex) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getstorageat) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getStorageAt", "params":["0x28bec7e30e6faee657a03e19bf1128aad7632a00", "0x0", "0x107c14af"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x000000000000000000000000d6b03d71e401479cc976fc94a41a37576404e7bd"} ``` ***
### Transaction Submission #### `eth_sendRawTransaction` Submits a signed transaction. Returns the transaction hash. * **Parameters:** `signedTransactionData` (hex-encoded signed tx bytes) * **Returns:** `hash` (tx id) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_sendrawtransaction) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_sendRawTransaction", "params":["0x02f8...signed_tx_bytes..."], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x...transaction_hash..."} ``` > **Note:** The example above is a template. You must provide a valid signed transaction. An invalid transaction returns: `{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"invalid transaction","data":null}}` *** #### `realtime_sendRawTransaction` Submits a signed transaction and **waits for the receipt** before returning. Same parameters as [`eth_sendRawTransaction`](#eth_sendrawtransaction), but the response is a full transaction receipt instead of just the hash. * **Parameters:** `signedTransactionData` (hex-encoded signed tx bytes) * **Returns:** [`TransactionReceipt`](#transactionreceipt) * **Compatibility:** **Somnia-specific** -- no Ethereum equivalent * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"realtime_sendRawTransaction", "params":["0x02f8...signed_tx_bytes..."], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":{"transactionHash":"0x...","blockNumber":"0x...","status":"0x1",...}} ``` ***
### Transaction Retrieval #### `eth_getTransactionByHash` Returns transaction details by hash, or `null` if not found. * **Parameters:** `txHash` * **Returns:** [`Transaction`](#transaction) `| null` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionbyhash) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getTransactionByHash", "params":["0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "blockHash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "blockNumber": "0xfebbe5e", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "gas": "0x5208", "gasPrice": "0x165a0bc00", "hash": "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53", "input": "0x", "nonce": "0x11", "transactionIndex": "0x0", "value": "0x29a0cc50fa726000", "type": "0x2", "chainId": "0x13a7", "v": "0x0", "r": "0xf2d4bdc57a1bab8df77f9fd311390f3ec9dacb5bd61fdb56b32bd0c3003136bf", "s": "0x10283bed1b67d23c87f8d64f309f401b802e5596788b3ce10dc47ee0e4c21fa4", "maxPriorityFeePerGas": "0x165a0bc00", "maxFeePerGas": "0x165a0bc00" } } ``` *** #### `eth_getTransactionByBlockHashAndIndex` Returns a transaction by block hash and index within the block. * **Parameters:** `blockHash`, `index` (hex) * **Returns:** [`Transaction`](#transaction) `| null` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionbyblockhashandindex) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getTransactionByBlockHashAndIndex", "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "0x0"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "blockHash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "blockNumber": "0xfebbe5e", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "gas": "0x5208", "gasPrice": "0x165a0bc00", "hash": "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53", "input": "0x", "nonce": "0x11", "transactionIndex": "0x0", "value": "0x29a0cc50fa726000", "type": "0x2", "chainId": "0x13a7", "v": "0x0", "r": "0xf2d4bdc57a1bab8df77f9fd311390f3ec9dacb5bd61fdb56b32bd0c3003136bf", "s": "0x10283bed1b67d23c87f8d64f309f401b802e5596788b3ce10dc47ee0e4c21fa4", "maxPriorityFeePerGas": "0x165a0bc00", "maxFeePerGas": "0x165a0bc00" } } ``` *** #### `eth_getTransactionByBlockNumberAndIndex` Returns a transaction by block number and index within the block. * **Parameters:** `blockNumber` (hex or label), `index` (hex) * **Returns:** [`Transaction`](#transaction) `| null` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionbyblocknumberandindex) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getTransactionByBlockNumberAndIndex", "params":["0xfebbe5e", "0x0"], "id":1 }' ``` Response format is identical to [`eth_getTransactionByBlockHashAndIndex`](#eth_gettransactionbyblockhashandindex) above. *** #### `eth_getTransactionReceipt` Returns the receipt for a mined transaction. * **Parameters:** `txHash` * **Returns:** [`TransactionReceipt`](#transactionreceipt) `| null` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getTransactionReceipt", "params":["0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "transactionHash": "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53", "transactionIndex": "0x0", "blockHash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "blockNumber": "0xfebbe5e", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "cumulativeGasUsed": "0x0", "gasUsed": "0x5208", "contractAddress": null, "type": "0x2", "status": "0x1", "logsBloom": "0x00000000...00000000", "logs": [], "effectiveGasPrice": "0x165a0bc00" } } ``` *** #### `eth_getBlockReceipts` Returns all transaction receipts for a block. * **Parameters:** `blockNumberOrHash` (hex block number, block hash, or label like `"latest"`) * **Returns:** [`TransactionReceipt`](#transactionreceipt)`[]` * **Compatibility:** [execution-apis](https://ethereum.github.io/execution-apis/api/methods/eth_getBlockReceipts) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getBlockReceipts", "params":["0xfebbe5e"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "transactionHash": "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53", "transactionIndex": "0x0", "blockHash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "blockNumber": "0xfebbe5e", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "cumulativeGasUsed": "0x0", "gasUsed": "0x5208", "contractAddress": null, "type": "0x2", "status": "0x1", "logsBloom": "0x00000000...00000000", "logs": [], "effectiveGasPrice": "0x165a0bc00" } ] } ``` ***
### Block Retrieval #### `eth_getBlockByNumber` Returns block data by number. * **Parameters:** `blockNumber` (hex or `"latest"`, `"earliest"`, `"pending"`), `fullTransactions` (bool -- if true, returns full tx objects; if false, returns tx hashes only) * **Returns:** [`Block`](#block) `| null` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblockbynumber) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getBlockByNumber", "params":["0xfebbe5e", false], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "hash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "parentHash": "0x73af1211b4b3ccc9c35db241d9aaf360375a10e2c85bd967c301411208404b45", "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", "miner": "0x0000000000000000000000000000000000000000", "stateRoot": "0xc076805ead803fdd1626309ade65a9da117e8dd0292c3b83a3f83b2c275e324c", "transactionsRoot": "0xb3704a7f49e846d089b574444a520315c852300c0e8a0b475d2614d71c14e031", "receiptsRoot": "0x38cb8db2babffab04de59d22a5ce68fb8cc5fcb00e71df0f9f03e3ce4d93a798", "logsBloom": "0x00000000...00000000", "difficulty": "0x0", "number": "0xfebbe5e", "gasLimit": "0x5208", "gasUsed": "0x5208", "baseFeePerGas": "0x165a0bc00", "timestamp": "0x69c925c6", "size": "0x222", "extraData": "0x0c73c07da3a7bbb6124544f41657d75a6a5ee033adce9d8eff74bfad616567a2", "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0000000000000000", "transactions": [ "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53" ] } } ``` *** #### `eth_getBlockByHash` Returns block data by hash. Same response format as [`eth_getBlockByNumber`](#eth_getblockbynumber). * **Parameters:** `blockHash`, `fullTransactions` (bool) * **Returns:** [`Block`](#block) `| null` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblockbyhash) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getBlockByHash", "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", false], "id":1 }' ``` Response format is identical to [`eth_getBlockByNumber`](#eth_getblockbynumber) above. *** #### `eth_getHeaderByNumber` Returns only the block header (no transactions). Same response shape as [`eth_getBlockByNumber`](#eth_getblockbynumber) but with the `transactions` field omitted entirely. * **Parameters:** `blockLabel` (hex or label) * **Returns:** [`Block`](#block) `| null` (header only) * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#ethgetheaderbynumber) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getHeaderByNumber", "params":["0xfebbe5e"], "id":1 }' ``` > **Note:** The `transactions` field is omitted from the response (not present as an empty array). *** #### `eth_getHeaderByHash` Returns only the block header by hash. Same as [`eth_getHeaderByNumber`](#eth_getheaderbynumber) but looks up by block hash. * **Parameters:** `blockHash` * **Returns:** [`Block`](#block) `| null` (header only) * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#ethgetheaderbyhash) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getHeaderByHash", "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98"], "id":1 }' ``` > **Note:** The `transactions` field is omitted from the response (not present as an empty array). *** #### `eth_getBlockTransactionCountByNumber` Returns the number of transactions in a block. * **Parameters:** `blockLabel` (hex or label) * **Returns:** `quantity` (uint64) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getBlockTransactionCountByNumber", "params":["0xfebbe5e"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x1"} ``` *** #### `eth_getBlockTransactionCountByHash` Returns the number of transactions in a block by hash. * **Parameters:** `blockHash` * **Returns:** `quantity` (uint64) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getBlockTransactionCountByHash", "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x1"} ``` ***
### Logs & Filters #### `eth_getLogs` Returns logs matching a filter. The block range must not exceed 1000 blocks. * **Parameters:** filter object with optional fields `fromBlock`, `toBlock`, `address`, `topics`, `blockHash` * **Returns:** [`Log`](#log)`[]` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getlogs) | Field | Type | Notes | | ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------- | | `fromBlock` | `blockLabel` or `null` | Start of block range | | `toBlock` | `blockLabel` or `null` | End of block range | | `blockHash` | `hash` or `null` | Specific block hash | | `address` | `address` or `address[]` | Match logs from one or more contracts | | `topics` | `array` or `null` | Topic-position filters; each position may be a single hash, an OR-list of hashes, or `null` as a wildcard | ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_getLogs", "params":[{ "fromBlock": "0xfebbe5e", "toBlock": "0xfebbe5e" }], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "address": "0x2a48aa2986e4bdabfae1c7366c72168cf4772f56", "topics": [ "0xb33ea778dc37bc968fc39ed9c7bb9d2d265850bfb8dcaaaea7987640fe0fa956", "0x000000000000000000000000000000000000000000000000000000000000002e", "0x000000000000000000000000db1b9390cfae98af059d6c38c987dedc86081da1" ], "data": "0x0000000000000000000000000000000000000000000000000000000000008477", "blockNumber": "0x147df45d", "transactionHash": "0x659acd064a5f391d779dd8d778f4eae10cf6d9caa8948e17f8065c12ef6f7b5d", "transactionIndex": "0x0", "blockHash": "0xdbcabc2fc754288ec00dcd5b69c65033142f202c8cad21b563f778f88c9f7526", "logIndex": "0x0" } ] } ``` *** #### `eth_newFilter` Creates a log filter. Returns a filter ID. The block range must not exceed 1000 blocks. * **Parameters:** filter object with optional fields `fromBlock`, `toBlock`, `address`, `topics` * **Returns:** `quantity` (filter id) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_newfilter) | Field | Type | Notes | | ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------- | | `fromBlock` | `blockLabel` or `null` | Start of block range | | `toBlock` | `blockLabel` or `null` | End of block range | | `address` | `address` or `address[]` | Match logs from one or more contracts | | `topics` | `array` or `null` | Topic-position filters; each position may be a single hash, an OR-list of hashes, or `null` as a wildcard | ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_newFilter", "params":[{"fromBlock":"latest","toBlock":"latest"}], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x1517573b"} ``` *** #### `eth_newBlockFilter` Creates a filter that returns new block hashes. * **Parameters:** *(none)* * **Returns:** `quantity` (filter id) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_newblockfilter) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x151730d4"} ``` *** #### `eth_newPendingTransactionFilter` Creates a filter that returns new pending transaction hashes. * **Parameters:** *(none)* * **Returns:** `quantity` (filter id) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x151730f3"} ``` *** #### `eth_getFilterChanges` Polls a filter for new results since the last poll. Response format depends on filter type: block hashes for block filters, tx hashes for pending tx filters, log objects for log filters. * **Parameters:** `filterId` (hex) * **Returns:** `json` (varies by filter type) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getfilterchanges) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x151730d4"],"id":1}' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": [ "0x96fe2ad8067123d10ab4e618fd18316b95990e98c3cf914e835878d9d998167a", "0x27b347f204beeb9d06d9ae96483070f609cd863b37a34b3bc7b6e5589b4e93bc", "0xfafb5f1ecf15e169878fe83adb56bcf6041dc41fa186396e3f5a9f332c0956ea" ] } ``` *** #### `eth_getFilterLogs` Returns all logs matching the filter criteria (for log filters only). * **Parameters:** `filterId` (hex) * **Returns:** [`Log`](#log)`[]` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_getfilterlogs) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x1517573b"],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":[]} ``` *** #### `eth_uninstallFilter` Removes a filter. Returns `true` if the filter was found and removed. * **Parameters:** `filterId` (hex) * **Returns:** `bool` * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_uninstallfilter) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x1517573b"],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":true} ``` > **Note:** Filter IDs are connection-scoped. On load-balanced public endpoints, the filter may be on a different backend than the uninstall request, causing `false` returns. For reliable filter usage, use a persistent WebSocket connection or a dedicated RPC endpoint. ***
### Subscriptions #### `eth_subscribe` Creates a subscription. Supported subscription types: * `"newHeads"` -- new block headers * `"logs"` -- log events matching a filter * `"somnia_finishedTransactions"` -- completed transaction receipts (Somnia-specific) * `"somnia_finishedBlocks"` -- completed blocks (Somnia-specific) * `"somnia_watch"` -- log events with watch semantics (Somnia-specific) **Properties:** * **Parameters:** `subscriptionType`, optional params object (see [Subscription Schemas](#subscription-schemas)) * **Returns:** `quantity` (subscription id) * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-subscribe-unsubscribe) * WebSocket only * This method emits events, so requires a **WebSocket** connection. Over HTTP it returns `events_not_supported`. [`eth_unsubscribe`](#eth_unsubscribe) works over both HTTP and WebSocket. ``` wscat -c wss://api.infra.testnet.somnia.network/ws > {"jsonrpc":"2.0","method":"eth_subscribe","params":["newHeads"],"id":1} < {"jsonrpc":"2.0","id":1,"result":"0x1"} < {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{...block header...}}} ``` Over HTTP, this returns: ```json {"jsonrpc":"2.0","id":1,"error":{"code":-1,"message":"events_not_supported","data":null}} ``` *** #### `eth_unsubscribe` Cancels a subscription. Returns `true` if the subscription was found and removed, `false` otherwise. Subscription IDs are connection-scoped, so this must be called from the same connection that created the subscription. * **Parameters:** `subscriptionId` (hex) * **Returns:** `bool` * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-subscribe-unsubscribe) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_unsubscribe","params":["0x1"],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":false} ``` ***
### Gas & Fees #### `eth_gasPrice` Returns the current gas price in wei. * **Parameters:** *(none)* * **Returns:** `quantity` (uint256) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gasprice), [execution-apis](https://ethereum.github.io/execution-apis/api/methods/eth_gasPrice) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x165a0bc00"} ``` *** #### `eth_maxPriorityFeePerGas` Returns the current max priority fee per gas (tip) in wei. * **Parameters:** *(none)* * **Returns:** `quantity` (uint256) * **Compatibility:** [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), [execution-apis](https://ethereum.github.io/execution-apis/api/methods/eth_maxPriorityFeePerGas) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_maxPriorityFeePerGas","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x0"} ``` *** #### `eth_feeHistory` Returns historical gas fee data. * **Parameters:** `blockCount` (hex), `newestBlock` (hex or label), `rewardPercentiles` (array of floats) * **Returns:** json object * **Compatibility:** [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), [execution-apis](https://ethereum.github.io/execution-apis/api/methods/eth_feeHistory) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_feeHistory", "params":["0x4", "latest", [25, 75]], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "oldestBlock": "0xff78371", "baseFeePerGas": ["0x165a0bc00", "0x165a0bc00", "0x165a0bc00", "0x165a0bc00"], "baseFeePerBlobGas": ["0x0", "0x0", "0x0", "0x0"], "gasUsedRatio": [0, 0, 0, 0], "blobGasUsedRatio": [0, 0, 0, 0], "reward": [["0x0", "0x0"], ["0x0", "0x0"], ["0x0", "0x0"], ["0x0", "0x0"]] } } ``` *** #### `eth_call` Executes a call without creating a transaction (read-only simulation). * **Parameters:** [`TransactionRequest`](#transactionrequest), `blockLabelOrHash`, optional [`StateOverrideSet`](#stateoverrideset) (see [Request Schemas](#request-schemas)) * **Returns:** `bytes` (hex) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_call) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_call", "params":[{ "to": "0x28bec7e30e6faee657a03e19bf1128aad7632a00", "data": "0x18160ddd" }, "0x107c14af"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x000000000000000000000000000000000000000000000000000000c11b9b1648"} ``` *** #### `eth_estimateGas` Estimates the gas required for a transaction. * **Parameters:** [`TransactionRequest`](#transactionrequest), optional `blockLabel`, optional [`StateOverrideSet`](#stateoverrideset) (see [Request Schemas](#request-schemas)) * **Returns:** `quantity` (uint64) * **Compatibility:** [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474), [ethereum.org](https://ethereum.org/developers/docs/apis/json-rpc/#eth_estimategas) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_estimateGas", "params":[{ "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "value": "0x0" }], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0x5208"} ``` *** #### `eth_createAccessList` Returns an empty EIP-2930 access list plus the estimated gas for a transaction. (Somnia doesn't support access lists.) * **Parameters:** [`TransactionRequest`](#transactionrequest), optional `blockLabel` (see [Request Schemas](#request-schemas)) * **Returns:** `[accessList, gasUsed]` (JSON array) * **Compatibility:** [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930), [execution-APIs](https://ethereum.github.io/execution-apis/api/methods/eth_createAccessList) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"eth_createAccessList", "params":[{ "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "value": "0x0" }], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":[[],"0x7b0c"]} ``` ***
### Debug / Tracing #### `debug_traceCall` Traces a call execution with a specified tracer. * **Parameters:** [`TransactionRequest`](#transactionrequest), `blockLabelOrHash`, trace config (`tracer`, `tracerConfig`, `stateOverrides`) (see [Request Schemas](#request-schemas)) * **Returns:** trace output * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtracecall) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"debug_traceCall", "params":[{ "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "value": "0x1" }, "latest", {"tracer": "callTracer"}], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "type": "CALL", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "gas": "0x3b9a77f8", "gasUsed": "0x5208", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "input": "0x", "output": "0x", "error": "INSUFFICIENT_BALANCE", "revertReason": null, "value": "0x1", "logs": [], "calls": [] } } ``` *** #### `debug_traceTransaction` Traces an already-mined transaction. * **Parameters:** `txHash`, tracer config (`tracer`, `tracerConfig`) * **Returns:** trace output * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtracetransaction) * Requires node to be [ready](#requires-node-ready) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"debug_traceTransaction", "params":[ "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53", {"tracer": "callTracer"} ], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "type": "CALL", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "gas": "0x0", "gasUsed": "0x5208", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "input": "0x", "output": "0x", "error": null, "revertReason": null, "value": "0x29a0cc50fa726000", "logs": [], "calls": [] } } ``` *** #### `debug_traceBlockByNumber` Traces all transactions in a block by block number. * **Parameters:** `blockLabel` (hex or label), tracer config * **Returns:** `{txHash, result | null, error | null}[]` * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtraceblockbynumber) * Requires node to be [ready](#requires-node-ready) > **Supported tracers:** `"callTracer"` (with optional `{"onlyTopCall": true}`), `"prestateTracer"` (with optional `{"diffMode": true}`) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"debug_traceBlockByNumber", "params":["0xfebbe5e", {"tracer": "callTracer"}], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "txHash": "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53", "result": { "type": "CALL", "from": "0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "gas": "0x0", "gasUsed": "0x5208", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "input": "0x", "output": "0x", "error": null, "revertReason": null, "value": "0x29a0cc50fa726000", "logs": [], "calls": [] }, "error": null } ] } ``` *** #### `debug_traceBlockByHash` Traces all transactions in a block by block hash. * **Parameters:** `blockHash`, tracer config * **Returns:** `{txHash, result | null, error | null}[]` * **Compatibility:** [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debugtraceblockbyhash) * Requires node to be [ready](#requires-node-ready) > **Supported tracers:** `"callTracer"` (with optional `{"onlyTopCall": true}`), `"prestateTracer"` (with optional `{"diffMode": true}`) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"debug_traceBlockByHash", "params":[ "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", {"tracer": "callTracer"} ], "id":1 }' ``` Response format is identical to [`debug_traceBlockByHash`](#debug_traceblockbyhash) above. ***
### Somnia-Specific #### `somnia_isReady` Returns `true` if the node is synced and ready to process requests. * **Parameters:** *(none)* * **Returns:** `bool` * **Compatibility:** **Somnia-specific** ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"somnia_isReady","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":true} ``` *** #### `somnia_isReadyWithErrorCode` Like [`somnia_isReady`](#somnia_isready), but returns an RPC error (code -32603) instead of `false` when the node is not ready. * **Parameters:** *(none)* * **Returns:** `bool` (error code on failure) * **Compatibility:** **Somnia-specific** ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"somnia_isReadyWithErrorCode","params":[],"id":1}' ``` ```json {"jsonrpc":"2.0","id":1,"result":true} ``` *** #### `somnia_nodePublicKeys` Returns the node's public keys for the current epoch. * **Parameters:** *(none)* * **Returns:** json object * **Compatibility:** **Somnia-specific** ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"somnia_nodePublicKeys","params":[],"id":1}' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "address": "0x53ee336e74e41250b1420d102fa35d3ac49c8928", "ecdsa_public_key": "0x024683678905b871ce02faf8af763033fea59dfc70f52df8ecb979b4e373abb638", "bls_public_key": "0x135dc21ad1326f464b458078408574a7adf3a570697715cbf68b28e817d69380...", "bls_proof_of_possession": "0xa14f7c8b...", "proof_of_address": "0x91c4c5be..." } } ``` *** #### `somnia_getBlockByNumber` Returns Somnia's native block representation (consensus + execution blocks), which contains more detail than the Ethereum-compatible [`eth_getBlockByNumber`](#eth_getblockbynumber). * **Parameters:** `blockLabel` (hex or label) * **Returns:** [`SomniaLedgerBlock`](#somnialedgerblock) `| null` * **Compatibility:** **Somnia-specific** -- native block format (cf. [`eth_getBlockByNumber`](#eth_getblockbynumber)) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_getBlockByNumber", "params":["0xfebbe5e"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "consensus_block": { "block_number": "0xfebbe5e", "timestamp": "0x19d39bb90f5", "data_chain_blocks": ["0x0798136c..."], "delayed_ledger_block_number": "0xfebbe4e", "delayed_ledger_block_hash": "0x03b01a71...", "parent_consensus_block_hash": "0xf9f64c1d...", "proposer_address": "0x012f6f8ded4e1f977953cd8dbfff31ebb902549c", "block_resources": { "validation_gas": "0x9c40", "compressed_bytes": "0x7c", "uncompressed_bytes": "0x7d" }, "consensus_block_hash": "0xb83203e7..." }, "execution_block": { "transaction_ids_hash": "0xb3704a7f...", "receipts_hash": "0x38cb8db2...", "execution_gas_limit": "0x5208", "execution_gas_used": "0x5208", "execution_state_snapshot": "0xc076805e...", "state_snapshot_block_number": "0xfebb2e7", "operation_sequence_hash": "0xb4e658ec67dbe4de" }, "parent_ledger_block_hash": "0x2fe94d90...", "ledger_block_hash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98" } } ``` *** #### `somnia_getBlockByHash` Same as [`somnia_getBlockByNumber`](#somnia_getblockbynumber) but looks up by block hash. * **Parameters:** `blockHash` * **Returns:** [`SomniaLedgerBlock`](#somnialedgerblock) `| null` * **Compatibility:** **Somnia-specific** -- native block format (cf. [`eth_getBlockByHash`](#eth_getblockbyhash)) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_getBlockByHash", "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98"], "id":1 }' ``` Response format is identical to [`somnia_getBlockByNumber`](#somnia_getblockbynumber) above. *** #### `somnia_getStatistics` Returns chain statistics over a block range. * **Parameters:** `fromBlock` (hex or label), `toBlock` (hex or label) * **Returns:** json object * **Compatibility:** **Somnia-specific** ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_getStatistics", "params":["0xfebbe5e", "0xfebbe60"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "numSuccessfulTransactions": "0x1", "numRevertedTransactions": "0x0", "numContractsAdded": "0x0", "numAccountsAdded": "0x0", "numNewUsedEoaAccounts": "0x0", "numNativeTransferTransactions": "0x1", "numGasUnitsSpent": "0x5208", "gasFeeSpent": "0x7298a93de000" } } ``` *** #### `somnia_getPrivilegedTransactionReceiptsForBlockByNumber` Returns receipts for privileged (system) transactions in a block. * **Parameters:** `blockNumber` (hex or label) * **Returns:** [`TransactionReceipt`](#transactionreceipt)`[]` * **Compatibility:** **Somnia-specific** -- system/privileged tx receipts ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_getPrivilegedTransactionReceiptsForBlockByNumber", "params":["0xfef96ff"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "transactionHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "transactionIndex": "0x0", "blockHash": "0xf3ef3de9a584326c0252b44f111aa7d342d6698678d310a5b1233622aab94a5e", "blockNumber": "0xfef96ff", "from": "0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7", "to": "0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7", "cumulativeGasUsed": "0x0", "gasUsed": "0x42a5ca", "contractAddress": null, "type": "0x18", "status": "0x1", "logsBloom": "0x00000000...00000000", "logs": [ { "address": "0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7", "topics": ["0x6debf9c0b8bd7ecda40db89a2641f61251d80a576b5c5e5f06de7f1c2a65850a"], "data": "0x00000000000000000000000000000000000000000000000000000000000000330000000000000000000000000000000000000000000000000000000069c988e4", "blockNumber": "0xfef96ff", "transactionHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "transactionIndex": "0x0", "blockHash": "0xf3ef3de9a584326c0252b44f111aa7d342d6698678d310a5b1233622aab94a5e", "logIndex": "0x0" } ], "effectiveGasPrice": "0x0" }, ... ] } ``` *** #### `somnia_getPrivilegedTransactionReceiptsForBlockByHash` Returns receipts for privileged (system) transactions in a block. Same as [`somnia_getPrivilegedTransactionReceiptsForBlockByNumber`](#somnia_getprivilegedtransactionreceiptsforblockbynumber) but looks up by block hash. * **Parameters:** `blockHash` * **Returns:** [`TransactionReceipt`](#transactionreceipt)`[]` * **Compatibility:** **Somnia-specific** -- system/privileged tx receipts ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_getPrivilegedTransactionReceiptsForBlockByHash", "params":["0xf3ef3de9a584326c0252b44f111aa7d342d6698678d310a5b1233622aab94a5e"], "id":1 }' ``` Response format is identical to [`somnia_getPrivilegedTransactionReceiptsForBlockByNumber`](#somnia_getprivilegedtransactionreceiptsforblockbynumber) above. *** #### `somnia_getSessionAddress` Derives a session key address from a seed. * **Parameters:** `seed` (32-byte hash) * **Returns:** `address` * **Compatibility:** **Somnia-specific** -- session key derivation ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_getSessionAddress", "params":["0x0000000000000000000000000000000000000000000000000000000000000001"], "id":1 }' ``` ```json {"jsonrpc":"2.0","id":1,"result":"0xf2d469b1fb798a5e9ced20e22daa7a911f35d697"} ``` *** #### `somnia_sendSessionTransaction` Sends a transaction using a session key (derived from a seed). The session account must have sufficient funds. * **Parameters:** object with `seed` (hash), `gas` (hex), `to` (address, optional), `value` (hex, optional), `data` (hex, optional) * **Returns:** [`TransactionReceipt`](#transactionreceipt) `| null` * **Compatibility:** **Somnia-specific** -- session key transactions ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_sendSessionTransaction", "params":[{ "seed": "0x0000000000000000000000000000000000000000000000000000000000000001", "gas": "0x5208", "to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "value": "0x0" }], "id":1 }' ``` Response format is identical to [`eth_getTransactionReceipt`](#eth_gettransactionreceipt) above. *** #### `somnia_reactivityGetSubscriptionInfo` Returns details of a [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity) subscription by ID. * **Parameters:** `subscriptionId` (hex-encoded subscription ID) * **Returns:** [`ReactivitySubscription`](#reactivitysubscription) * **Compatibility:** **Somnia-specific** -- [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_reactivityGetSubscriptionInfo", "params":["0x1"], "id":1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "0x1", "topics": [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0x0000000000000000000000000000000000000000000000000000000000000000", "0x0000000000000000000000000000000000000000000000000000000000000000", "0x0000000000000000000000000000000000000000000000000000000000000000" ], "origin": "0x0000000000000000000000000000000000000000", "caller": "0x0000000000000000000000000000000000000000", "emitter": "0x107256636b98e705fade330bbcb903580b8b227d", "owner": "0x12a76e09bae1934265a1aea2812e0c772f372f8d", "handler_contract_address": "0xf84f7633bd403967999b06911f978a74326f547e", "handler_function_selector": "0x53edf33d", "gas_limit": "0x4c4b40", "priority_fee_per_gas": "0x77359400", "max_fee_per_gas": "0x2540be400" } } ``` *** #### `somnia_reactivityGetSubscriptions` Returns all [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity) subscriptions owned by an address. * **Parameters:** `address` (owner address) * **Returns:** [`ReactivitySubscription[]`](#reactivitysubscription) * **Compatibility:** **Somnia-specific** -- [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity) ```bash curl -s -X POST $RPC_URL \ -H "Content-Type: application/json" \ -d '{ "jsonrpc":"2.0", "method":"somnia_reactivityGetSubscriptions", "params":["0x12a76e09bae1934265a1aea2812e0c772f372f8d"], "id":1 }' ``` Response is a JSON array of [`ReactivitySubscription`](#reactivitysubscription) objects. ***
## Notes ### General Usage #### Endpoints | Network | HTTP | WebSocket | | ------------------------------------------- | ------------------------------------------ | ------------------------------------------- | | Mainnet (chain ID `0x13a7` / 5031) | `https://api.infra.mainnet.somnia.network` | `wss://api.infra.mainnet.somnia.network/ws` | | Testnet Shannon (chain ID `0xc488` / 50312) | `https://api.infra.testnet.somnia.network` | `wss://api.infra.testnet.somnia.network/ws` | #### Request Format All requests use the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol over HTTP POST or WebSocket. The request body is: ```json {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1} ``` **Batch requests** are supported: send a JSON array of request objects and receive a JSON array of responses in the same order. ```json [ {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}, {"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":2} ] ``` #### Hex Encoding All numeric values in requests and responses are hex-encoded with a `0x` prefix, following the [Ethereum JSON-RPC convention](https://ethereum.org/developers/docs/apis/json-rpc/#conventions): * **Quantities** (block numbers, gas, balances, nonces): hex without leading zeros — `"0x1"`, `"0x5208"`, `"0x165a0bc00"` * **Data** (hashes, addresses, bytecode, input data): hex with even-length zero-padding — `"0x0000...0000"`, `"0x"` #### Block Labels Many methods accept a **block label** parameter. This can be: * A hex-encoded block number (e.g. `"0xfebbe5e"`) * `"latest"` — the most recent confirmed block * `"earliest"` — the genesis block (block 0) * `"finalized"`, `"pending"`, `"safe"` — currently treated the same as `"latest"` #### Transaction Types Somnia supports the following Ethereum transaction types via [`eth_sendRawTransaction`](#eth_sendrawtransaction): | Type | Name | EIP | Notes | | ----- | ----------- | --------------------------------------------------- | ------------------------------------------- | | `0x0` | Legacy | pre-EIP-2718 | `gasPrice` field | | `0x1` | Access list | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) | `gasPrice` + `accessList` | | `0x2` | Dynamic fee | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) | `maxFeePerGas` + `maxPriorityFeePerGas` | | `0x3` | Blob | [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) | **Not supported** | | `0x4` | Set code | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) | `authorizationList` for EOA code delegation | #### Error Codes Error responses follow the JSON-RPC 2.0 format: ```json {"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"insufficient balance","data":null}} ``` | Code | Meaning | Common causes | | -------- | -------------------- | ----------------------------------------------------------- | | `-32700` | Parse error | Malformed JSON | | `-32600` | Invalid request | Missing `jsonrpc`, `method`, or `id` fields | | `-32601` | Method not found | Typo in method name, or method not available on this node | | `-32602` | Invalid parameters | Wrong number or types of params | | `-32603` | Internal error | Node not ready, or unexpected server error | | `-32604` | Too many requests | Rate limit exceeded | | `-32004` | Method not supported | Method exists but is disabled on this node | | `-32000` | Invalid input | Transaction-specific errors (see below) | | `-1` | Application error | Handler-specific errors (e.g. `"block range exceeds 1000"`) | Common `-32000` transaction errors from [`eth_sendRawTransaction`](#eth_sendrawtransaction): | Message | Meaning | | ---------------------------- | ---------------------------------------------------------- | | `"invalid transaction"` | RLP decoding failed or transaction is malformed | | `"invalid signature"` | ECDSA signature verification failed | | `"nonce too low"` | Transaction nonce is behind the account's current nonce | | `"nonce too high"` | Transaction nonce is too far ahead | | `"insufficient balance"` | Account cannot cover value + gas | | `"gas price below base fee"` | `gasPrice` or `maxFeePerGas` is below the current base fee | | `"mempool full"` | Node's transaction pool is at capacity | ### Special Cases #### Requires Node Ready Some methods are marked **Requires Node Ready** in the index table. These methods will return an error if the node has not finished syncing and is not yet ready to serve requests. You can check whether a node is ready before making calls by using [`somnia_isReady`](#somnia_isready). #### Log Query Limits [`eth_getLogs`](#eth_getlogs), [`eth_newFilter`](#eth_newfilter), and [`eth_getFilterLogs`](#eth_getfilterlogs) enforce a maximum block range (currently 1000 blocks). Queries exceeding this range will return an error. To scan larger ranges, issue multiple queries with non-overlapping block ranges. #### Filter and Subscription Statefulness Filters created with [`eth_newFilter`](#eth_newfilter), [`eth_newBlockFilter`](#eth_newblockfilter), and [`eth_newPendingTransactionFilter`](#eth_newpendingtransactionfilter) are scoped to the connection that created them. On load-balanced public RPC endpoints, subsequent requests may be routed to a different backend, causing [`eth_getFilterChanges`](#eth_getfilterchanges) to return empty results or [`eth_uninstallFilter`](#eth_uninstallfilter) to return `false`. For reliable filter-based polling, use a dedicated RPC endpoint or switch to [`eth_subscribe`](#eth_subscribe) over WebSocket. Subscriptions created with [`eth_subscribe`](#eth_subscribe) are also connection-scoped. [`eth_unsubscribe`](#eth_unsubscribe) returns `false` if the subscription id is unknown or belongs to a different connection. #### Missing Resource Semantics Somnia does not use a single convention for "not found". The main cases are: | Method(s) | Missing resource behaviour | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | [`eth_getTransactionByHash`](#eth_gettransactionbyhash), [`eth_getTransactionReceipt`](#eth_gettransactionreceipt), [`eth_getTransactionByBlockHashAndIndex`](#eth_gettransactionbyblockhashandindex), [`eth_getTransactionByBlockNumberAndIndex`](#eth_gettransactionbyblocknumberandindex) | Returns `null` | | [`eth_getBlockByHash`](#eth_getblockbyhash), [`eth_getBlockByNumber`](#eth_getblockbynumber), [`eth_getHeaderByHash`](#eth_getheaderbyhash), [`eth_getHeaderByNumber`](#eth_getheaderbynumber), [`somnia_getBlockByHash`](#somnia_getblockbyhash), [`somnia_getBlockByNumber`](#somnia_getblockbynumber) | Returns `null` | | [`eth_getBlockTransactionCountByHash`](#eth_getblocktransactioncountbyhash), [`eth_getBlockTransactionCountByNumber`](#eth_getblocktransactioncountbynumber) | Returns `"0x0"` | | [`eth_getBlockReceipts`](#eth_getblockreceipts) | RPC error: `"unknown block"` | | [`somnia_getPrivilegedTransactionReceiptsForBlockByHash`](#somnia_getprivilegedtransactionreceiptsforblockbyhash), [`somnia_getPrivilegedTransactionReceiptsForBlockByNumber`](#somnia_getprivilegedtransactionreceiptsforblockbynumber) | RPC error: `"Block does not exist"` | | [`eth_uninstallFilter`](#eth_uninstallfilter), [`eth_unsubscribe`](#eth_unsubscribe) | Returns `false` if the id is unknown or belongs to another connection | #### Somnia vs Ethereum Differences While Somnia is EVM-compatible and supports the standard Ethereum JSON-RPC, there are a few behavioural differences to be aware of: * [**`eth_syncing`**](#eth_syncing) returns only a `bool` (`true` while syncing, `false` when ready). It does not return a sync-status object with `startingBlock`/`currentBlock`/`highestBlock` fields as Ethereum clients do. * [**`eth_getHeaderByHash`**](#eth_getheaderbyhash) **/** [**`eth_getHeaderByNumber`**](#eth_getheaderbynumber) omit the `transactions` field entirely rather than returning an empty array. * [**`eth_subscribe`**](#eth_subscribe) supports the standard `"newHeads"` and `"logs"` types, plus three Somnia-specific types: `"somnia_finishedTransactions"`, `"somnia_finishedBlocks"`, and `"somnia_watch"`. It does **not** support `"newPendingTransactions"`. * [**`realtime_sendRawTransaction`**](#realtime_sendrawtransaction) is a Somnia extension that submits a transaction and blocks until the receipt is available, combining [`eth_sendRawTransaction`](#eth_sendrawtransaction) + polling [`eth_getTransactionReceipt`](#eth_gettransactionreceipt) into a single call. * **Block structure**: Somnia blocks have a fixed `difficulty` of `0x0`, `miner` of `0x0...0`, and no uncle blocks. The `gasLimit` reflects per-block execution gas rather than a global gas target. * **EIP-4844 blob transactions** (type `0x3`) are not supported. For more detail on gas behaviour, see [Somnia Gas Differences to Ethereum](/developer/deployment-and-production/somnia-gas-differences-to-ethereum.md). ## Appendix ### Request Schemas **TransactionRequest** (used by [`eth_call`](#eth_call), [`eth_estimateGas`](#eth_estimategas), [`eth_createAccessList`](#eth_createaccesslist), [`debug_traceCall`](#debug_tracecall), and `somnia_watch.eth_calls`): | Field | Type | Notes | | ------------------- | ----------------------------------------------------------------- | --------------------------------------------- | | `from` | `address` or `null` | Sender address for simulation | | `to` | `address` or `null` | Omit or set `null` for contract creation | | `gas` | `quantity` or `null` | Gas limit for the simulated transaction | | `value` | `quantity` or `null` | Wei transferred | | `input` | `bytes` or `null` | Calldata alias accepted by Geth-style clients | | `data` | `bytes` or `null` | Calldata alias | | `authorizationList` | [`AuthorizationListEntry`](#authorizationlistentry)`[]` or `null` | EIP-7702 authorization list | > `input` and `data` are interchangeable aliases. If both are provided, Somnia uses `input`. **AuthorizationListEntry** (entries within `authorizationList`): | Field | Type | Notes | | --------- | ---------- | -------------------------------------- | | `chainId` | `quantity` | Chain id covered by the authorization | | `address` | `address` | Contract address to delegate code from | | `nonce` | `quantity` | Authorization nonce | | `yParity` | `quantity` | Signature recovery parity | | `r` | `quantity` | Signature component | | `s` | `quantity` | Signature component | **StateOverrideSet** (used by [`eth_call`](#eth_call), [`eth_estimateGas`](#eth_estimategas), and [`debug_traceCall`](#debug_tracecall)): A JSON object keyed by account address, where each value is a [`StateOverride`](#stateoverride) object. **StateOverride**: | Field | Type | Notes | | ----------- | -------------------- | ----------------------------------------------------------- | | `balance` | `quantity` or `null` | Override account balance | | `nonce` | `quantity` or `null` | Override account nonce | | `code` | `bytes` or `null` | Override deployed bytecode | | `state` | `object` or `null` | Replace the entire storage map with `slot -> value` entries | | `stateDiff` | `object` or `null` | Patch individual storage slots with `slot -> value` entries | > `state` and `stateDiff` are mutually exclusive. Providing both returns an error. Several methods take similar log-filter-shaped inputs, but they are not one shared request type in source. ### Response Schemas **Transaction** (returned by [`eth_getTransactionByHash`](#eth_gettransactionbyhash) and similar): | Field | Type | Notes | | ---------------------- | -------------------- | --------------------------------------------------------------- | | `blockHash` | `hash` | | | `blockNumber` | `quantity` | | | `from` | `address` | | | `to` | `address` or `null` | `null` for contract creation | | `gas` | `quantity` | Gas limit | | `gasPrice` | `quantity` | Effective gas price | | `hash` | `hash` | Transaction hash | | `input` | `bytes` | Calldata (`"0x"` for simple transfers) | | `nonce` | `quantity` | | | `transactionIndex` | `quantity` | Position within the block | | `value` | `quantity` | Wei transferred | | `type` | `quantity` | `0x0` legacy, `0x1` access list, `0x2` EIP-1559, `0x4` EIP-7702 | | `chainId` | `quantity` | | | `v`, `r`, `s` | `quantity` | ECDSA signature components | | `maxPriorityFeePerGas` | `quantity` or `null` | Present for type `0x2` and `0x4` only | | `maxFeePerGas` | `quantity` or `null` | Present for type `0x2` and `0x4` only | | `authorizationList` | `array` or `null` | Present for type `0x4` only | **TransactionReceipt** (returned by [`eth_getTransactionReceipt`](#eth_gettransactionreceipt) and similar): | Field | Type | Notes | | ------------------- | ------------------- | -------------------------------------- | | `transactionHash` | `hash` | | | `transactionIndex` | `quantity` | | | `blockHash` | `hash` | | | `blockNumber` | `quantity` | | | `from` | `address` | | | `to` | `address` or `null` | `null` for contract creation | | `cumulativeGasUsed` | `quantity` | | | `gasUsed` | `quantity` | Gas consumed by this transaction | | `contractAddress` | `address` or `null` | Address of created contract, or `null` | | `type` | `quantity` | Transaction type | | `status` | `quantity` | `0x1` success, `0x0` revert | | `logsBloom` | `bytes` | 256-byte bloom filter | | `logs` | [`Log`](#log)`[]` | Array of log entries (see below) | | `effectiveGasPrice` | `quantity` | Actual gas price paid | **Log** (entries within `logs` arrays): | Field | Type | Notes | | ------------------ | ---------- | ------------------------------------------------------------------------- | | `address` | `address` | Contract that emitted the event | | `topics` | `hash[]` | Up to 4 indexed event parameters; `topics[0]` is the event signature hash | | `data` | `bytes` | ABI-encoded non-indexed parameters | | `blockNumber` | `quantity` | | | `transactionHash` | `hash` | | | `transactionIndex` | `quantity` | | | `blockHash` | `hash` | | | `logIndex` | `quantity` | Position within the block's logs | **Block** (returned by [`eth_getBlockByNumber`](#eth_getblockbynumber) and similar): | Field | Type | Notes | | ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `hash` | `hash` | | | `parentHash` | `hash` | | | `sha3Uncles` | `hash` | Always the empty uncles hash (no uncle blocks) | | `miner` | `address` | Always `0x0000...0000` | | `stateRoot` | `hash` | | | `transactionsRoot` | `hash` | | | `receiptsRoot` | `hash` | | | `logsBloom` | `bytes` | 256-byte bloom filter | | `difficulty` | `quantity` | Always `0x0` | | `number` | `quantity` | Block number | | `gasLimit` | `quantity` | Per-block execution gas | | `gasUsed` | `quantity` | | | `baseFeePerGas` | `quantity` | EIP-1559 base fee | | `timestamp` | `quantity` | Unix timestamp | | `size` | `quantity` | RLP-encoded block size in bytes | | `extraData` | `bytes` | | | `mixHash` | `hash` | Always zero | | `nonce` | `bytes` | Always zero (8 bytes) | | `transactions` | `hash[]` or [`Transaction`](#transaction)`[]` | Tx hashes if `fullTxObjects=false`, full objects if `true`. Omitted entirely for `eth_getHeaderBy*`. | **SomniaLedgerBlock** (returned by [`somnia_getBlockByNumber`](#somnia_getblockbynumber) / [`somnia_getBlockByHash`](#somnia_getblockbyhash)): | Field | Type | Notes | | -------------------------- | ----------------------------------------------- | -------------------------- | | `consensus_block` | [`SomniaConsensusBlock`](#somniaconsensusblock) | Consensus-layer block data | | `execution_block` | [`SomniaExecutionBlock`](#somniaexecutionblock) | Execution-layer block data | | `parent_ledger_block_hash` | `hash` | Parent ledger-block hash | | `ledger_block_hash` | `hash` | Ledger-block hash | **SomniaConsensusBlock**: | Field | Type | Notes | | ----------------------------- | ----------------------------------------------------- | ------------------------------ | | `block_number` | `quantity` | Ledger block number | | `timestamp` | `quantity` | Unix timestamp in milliseconds | | `data_chain_blocks` | `hash[]` | Referenced data-chain blocks | | `delayed_ledger_block_number` | `quantity` | Delayed ledger block number | | `delayed_ledger_block_hash` | `hash` | Delayed ledger block hash | | `parent_consensus_block_hash` | `hash` | Parent consensus-block hash | | `proposer_address` | `address` | Block proposer | | `block_resources` | [`SomniaFrontendResources`](#somniafrontendresources) | Frontend resource accounting | | `consensus_block_hash` | `hash` | Consensus-block hash | **SomniaExecutionBlock**: | Field | Type | Notes | | ----------------------------- | ---------- | --------------------------------------------- | | `transaction_ids_hash` | `hash` | Hash of transaction ids | | `receipts_hash` | `hash` | Hash of receipts | | `execution_gas_limit` | `quantity` | Execution gas limit | | `execution_gas_used` | `quantity` | Execution gas used | | `execution_state_snapshot` | `hash` | State snapshot hash | | `state_snapshot_block_number` | `quantity` | Block number of the state snapshot | | `operation_sequence_hash` | `quantity` | Operation sequence hash encoded as a quantity | **SomniaFrontendResources**: | Field | Type | Notes | | -------------------- | ---------- | ------------------------------------------ | | `validation_gas` | `quantity` | Validation gas used by the consensus block | | `compressed_bytes` | `quantity` | Compressed frontend payload size | | `uncompressed_bytes` | `quantity` | Uncompressed frontend payload size | **ReactivitySubscription** (returned by [`somnia_reactivityGetSubscriptionInfo`](#somnia_reactivitygetsubscriptioninfo) / [`somnia_reactivityGetSubscriptions`](#somnia_reactivitygetsubscriptions)): | Field | Type | Notes | | --------------------------- | ---------- | ------------------------------------------------ | | `id` | `quantity` | Subscription ID | | `topics` | `data[4]` | Log topics to match (up to 4) | | `origin` | `address` | Origin filter | | `caller` | `address` | Caller filter (reserved, currently unused) | | `emitter` | `address` | Contract address that emits the matched log | | `owner` | `address` | Subscription owner address | | `handler_contract_address` | `address` | Contract called when the subscription triggers | | `handler_function_selector` | `data` | 4-byte function selector on the handler contract | | `gas_limit` | `quantity` | Gas limit for the reactive callback | | `priority_fee_per_gas` | `quantity` | Priority fee per gas for the callback | | `max_fee_per_gas` | `quantity` | Max fee per gas for the callback | ### Subscription Schemas All [`eth_subscribe`](#eth_subscribe) notifications use this envelope: ```json {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":...}} ``` **`newHeads`** * **Params:** none * **Event result:** [`NewHead`](#newhead) **`logs`** **Params:** | Field | Type | Notes | | --------- | ------------------------ | -------------------------------------------------------------------------------------------------- | | `address` | `address` or `address[]` | Match logs from one or more contracts | | `topics` | `array` or `null` | Same topic-position semantics as [`eth_getLogs`](#eth_getlogs) / [`eth_newFilter`](#eth_newfilter) | * **Event result:** [`Log`](#log) **`somnia_finishedTransactions`** **Params:** | Field | Type | Notes | | ------------------------------- | --------------------- | ---------------------------------------------------- | | `transaction_senders` | `address[]` or `null` | Only emit events for transactions from these senders | | `subscribe_to_all_transactions` | `bool` or `null` | Emit events for all finished transactions | **Event result:** | Field | Type | Notes | | -------------------- | -------------- | ------------------------------------ | | `transaction_id` | `hash` | Transaction hash | | `transaction_status` | `integer enum` | Internal `TransactionStatus` value | | `sender_address` | `address` | Transaction sender | | `transaction_nonce` | `integer` | Sender nonce used by the transaction | **`somnia_finishedBlocks`** * **Params:** none **Event result:** | Field | Type | Notes | | ------------------- | ---------- | ----------------------------------- | | `blockNumber` | `quantity` | Finished block number | | `totalTransactions` | `quantity` | Number of transactions in the block | **`somnia_watch`** **Params:** | Field | Type | Notes | | ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | `address` or `address[]` | Log emitter filter | | `topics` | `array` or `null` | Same topic-position semantics as [`eth_getLogs`](#eth_getlogs) / [`eth_newFilter`](#eth_newfilter) | | `eth_calls` | `array` | Each item is either a [`TransactionRequest`](#transactionrequest), or \[[`TransactionRequest`](#transactionrequest), [`StateOverrideSet`](#stateoverrideset)] | | `context` | `string` or `string[]` | Extra values appended to each simulated call's calldata. Supported selectors: `address`, `data`, `topic1`, `topic2`, `topic3`, `topic4` | | `push_changes_only` | `bool` or `null` | Only emit when `simulationResults` change from the previous event for that subscription | **Event result:** | Field | Type | Notes | | ------------------- | --------- | ----------------------------------------------- | | `address` | `address` | Log emitter | | `topics` | `hash[]` | Emitted topics | | `data` | `bytes` | Raw log data | | `simulationResults` | `bytes[]` | Return data from each configured simulated call | **NewHead** (event payload for `eth_subscribe("newHeads")`): | Field | Type | Notes | | ------------------ | ---------- | ---------------------------- | | `hash` | `hash` | | | `parentHash` | `hash` | | | `sha3Uncles` | `hash` | Always the empty uncles hash | | `miner` | `address` | Always `0x0000...0000` | | `stateRoot` | `hash` | | | `transactionsRoot` | `hash` | | | `receiptsRoot` | `hash` | | | `logsBloom` | `bytes` | 256-byte bloom filter | | `difficulty` | `quantity` | Always `0x0` | | `number` | `quantity` | Block number | | `gasLimit` | `quantity` | | | `gasUsed` | `quantity` | | | `baseFeePerGas` | `quantity` | | | `timestamp` | `quantity` | Unix timestamp | | `extraData` | `bytes` | | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.somnia.network/developer/json-rpc-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.