Build

Somnia 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 WebSocket Only
debug_traceBlockByHash Geth debug Yes
debug_traceBlockByNumber Geth debug Yes
debug_traceCall Geth debug Yes
debug_traceTransaction Geth debug Yes
eth_accounts Ethereum standard
eth_blockNumber Ethereum standard
eth_call Ethereum standard Yes
eth_chainId Ethereum standard
eth_createAccessList Execution APIs Yes
eth_estimateGas Ethereum standard Yes
eth_feeHistory Execution APIs
eth_gasPrice Ethereum standard
eth_getBalance Ethereum standard
eth_getBlockByHash Ethereum standard
eth_getBlockByNumber Ethereum standard
eth_getBlockReceipts Execution APIs
eth_getBlockTransactionCountByHash Ethereum standard
eth_getBlockTransactionCountByNumber Ethereum standard
eth_getCode Ethereum standard Yes
eth_getFilterChanges Ethereum standard
eth_getFilterLogs Ethereum standard
eth_getHeaderByHash Geth
eth_getHeaderByNumber Geth
eth_getLogs Ethereum standard
eth_getStorageAt Ethereum standard Yes
eth_getTransactionByBlockHashAndIndex Ethereum standard
eth_getTransactionByBlockNumberAndIndex Ethereum standard
eth_getTransactionByHash Ethereum standard
eth_getTransactionCount Ethereum standard Yes
eth_getTransactionReceipt Ethereum standard
eth_maxPriorityFeePerGas Execution APIs
eth_newBlockFilter Ethereum standard
eth_newFilter Ethereum standard
eth_newPendingTransactionFilter Ethereum standard
eth_sendRawTransaction Ethereum standard Yes
eth_subscribe Geth Yes
eth_syncing Ethereum standard
eth_uninstallFilter Ethereum standard
eth_unsubscribe Geth
net_listening Ethereum standard
net_version Ethereum standard
realtime_sendRawTransaction Somnia-specific Yes
somnia_getBlockByHash Somnia-specific
somnia_getBlockByNumber Somnia-specific
somnia_getPrivilegedTransactionReceiptsForBlockByHash Somnia-specific
somnia_getPrivilegedTransactionReceiptsForBlockByNumber Somnia-specific
somnia_getSessionAddress Somnia-specific
somnia_getStatistics Somnia-specific
somnia_isReady Somnia-specific
somnia_isReadyWithErrorCode Somnia-specific
somnia_nodePublicKeys Somnia-specific
somnia_reactivityGetSubscriptionInfo Somnia-specific, testnet only
somnia_reactivityGetSubscriptions Somnia-specific, testnet only
somnia_sendSessionTransaction Somnia-specific
web3_clientVersion Ethereum standard
web3_sha3 Ethereum standard

Methods by Category

Network / Web3

net_version

Returns the network ID.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_version","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"0x13a7"}

Note: This is currently non-conformant with the Ethereum JSON-RPC spec, 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.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":true}

web3_clientVersion

Returns the Somnia client version string.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"somnia-92fe2faf8cbcd24-release"}

web3_sha3

Returns the Keccak-256 hash of the given data.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f"],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8"}

Chain State

eth_chainId

Returns the chain ID.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

{"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.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":false}

eth_blockNumber

Returns the latest block number.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"0xff7809e"}

eth_accounts

Returns the list of accounts owned by the node (empty for public RPC endpoints).

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}'

{"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, ethereum.org
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBalance",
    "params":["0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6", "0xfebbe5e"],
    "id":1
  }'

{"jsonrpc":"2.0","id":1,"result":"0x5a957142cf2e47706c"}

eth_getTransactionCount

Returns the nonce (number of transactions sent) for an account.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionCount",
    "params":["0xc04ea345ac1aded81ea4b3bd7ada1f7638e63e66", "latest"],
    "id":1
  }'

{"jsonrpc":"2.0","id":1,"result":"0x12"}

eth_getCode

Returns the bytecode at an address ("0x" for addresses without code).

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getCode",
    "params":["0x4e59b44847b379578588920cA78FbF26c0B4956C", "0xfebbe5e"],
    "id":1
  }'

{"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, ethereum.org
  • Requires node to be ready
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getStorageAt",
    "params":["0x28bec7e30e6faee657a03e19bf1128aad7632a00", "0x0", "0x107c14af"],
    "id":1
  }'

{"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, ethereum.org
  • Requires node to be ready
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
  }'

{"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, but the response is a full transaction receipt instead of just the hash.

  • Parameters: signedTransactionData (hex-encoded signed tx bytes)
  • Returns: TransactionReceipt
  • Compatibility: Somnia-specific -- no Ethereum equivalent
  • Requires node to be ready
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
  }'

{"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.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionByHash",
    "params":["0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53"],
    "id":1
  }'

{
  "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.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionByBlockHashAndIndex",
    "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98", "0x0"],
    "id":1
  }'

{
  "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.

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 above.

eth_getTransactionReceipt

Returns the receipt for a mined transaction.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getTransactionReceipt",
    "params":["0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53"],
    "id":1
  }'

{
  "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.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockReceipts",
    "params":["0xfebbe5e"],
    "id":1
  }'

{
  "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 | null
  • Compatibility: EIP-1474, ethereum.org
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockByNumber",
    "params":["0xfebbe5e", false],
    "id":1
  }'

{
  "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.

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 above.

eth_getHeaderByNumber

Returns only the block header (no transactions). Same response shape as eth_getBlockByNumber but with the transactions field omitted entirely.

  • Parameters: blockLabel (hex or label)
  • Returns: Block | null (header only)
  • Compatibility: Geth
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 but looks up by block hash.

  • Parameters: blockHash
  • Returns: Block | null (header only)
  • Compatibility: Geth
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, ethereum.org
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockTransactionCountByNumber",
    "params":["0xfebbe5e"],
    "id":1
  }'

{"jsonrpc":"2.0","id":1,"result":"0x1"}

eth_getBlockTransactionCountByHash

Returns the number of transactions in a block by hash.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getBlockTransactionCountByHash",
    "params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98"],
    "id":1
  }'

{"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[]
  • Compatibility: EIP-1474, ethereum.org
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 
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
  }'

{
  "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, ethereum.org
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 
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
  }'

{"jsonrpc":"2.0","id":1,"result":"0x1517573b"}

eth_newBlockFilter

Creates a filter that returns new block hashes.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"0x151730d4"}

eth_newPendingTransactionFilter

Creates a filter that returns new pending transaction hashes.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}'

{"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, ethereum.org
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x151730d4"],"id":1}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "0x96fe2ad8067123d10ab4e618fd18316b95990e98c3cf914e835878d9d998167a",
    "0x27b347f204beeb9d06d9ae96483070f609cd863b37a34b3bc7b6e5589b4e93bc",
    "0xfafb5f1ecf15e169878fe83adb56bcf6041dc41fa186396e3f5a9f332c0956ea"
  ]
}

eth_getFilterLogs

Returns all logs matching the filter criteria (for log filters only).

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x1517573b"],"id":1}'

{"jsonrpc":"2.0","id":1,"result":[]}

eth_uninstallFilter

Removes a filter. Returns true if the filter was found and removed.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x1517573b"],"id":1}'

{"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)
  • Returns: quantity (subscription id)
  • Compatibility: Geth
  • WebSocket only
    • This method emits events, so requires a WebSocket connection. Over HTTP it returns events_not_supported. 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:

{"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
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_unsubscribe","params":["0x1"],"id":1}'

{"jsonrpc":"2.0","id":1,"result":false}

Gas & Fees

eth_gasPrice

Returns the current gas price in wei.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"0x165a0bc00"}

eth_maxPriorityFeePerGas

Returns the current max priority fee per gas (tip) in wei.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_maxPriorityFeePerGas","params":[],"id":1}'

{"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, execution-apis
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
  }'

{
  "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).

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
  }'

{"jsonrpc":"2.0","id":1,"result":"0x000000000000000000000000000000000000000000000000000000c11b9b1648"}

eth_estimateGas

Estimates the gas required for a transaction.

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
  }'

{"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.)

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
  }'

{"jsonrpc":"2.0","id":1,"result":[[],"0x7b0c"]}

Debug / Tracing

debug_traceCall

Traces a call execution with a specified tracer.

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
  }'

{
  "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
  • Requires node to be ready
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"debug_traceTransaction",
    "params":[
      "0xe37a5053ed983747d65a782a4924e2a894729a0cbcbbf012ea6267870a99df53",
      {"tracer": "callTracer"}
    ],
    "id":1
  }'

{
  "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
  • Requires node to be ready

Supported tracers: "callTracer" (with optional {"onlyTopCall": true}), "prestateTracer" (with optional {"diffMode": true})

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"debug_traceBlockByNumber",
    "params":["0xfebbe5e", {"tracer": "callTracer"}],
    "id":1
  }'

{
  "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
  • Requires node to be ready

Supported tracers: "callTracer" (with optional {"onlyTopCall": true}), "prestateTracer" (with optional {"diffMode": true})

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 above.


Somnia-Specific

somnia_isReady

Returns true if the node is synced and ready to process requests.

  • Parameters: (none)
  • Returns: bool
  • Compatibility: Somnia-specific
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"somnia_isReady","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":true}

somnia_isReadyWithErrorCode

Like 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
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"somnia_isReadyWithErrorCode","params":[],"id":1}'

{"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
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"somnia_nodePublicKeys","params":[],"id":1}'

{
  "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.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"somnia_getBlockByNumber",
    "params":["0xfebbe5e"],
    "id":1
  }'

{
  "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 but looks up by block hash.

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 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
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"somnia_getStatistics",
    "params":["0xfebbe5e", "0xfebbe60"],
    "id":1
  }'

{
  "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[]
  • Compatibility: Somnia-specific -- system/privileged tx receipts
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"somnia_getPrivilegedTransactionReceiptsForBlockByNumber",
    "params":["0xfef96ff"],
    "id":1
  }'

{
  "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 but looks up by block hash.

  • Parameters: blockHash
  • Returns: TransactionReceipt[]
  • Compatibility: Somnia-specific -- system/privileged tx receipts
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 above.

somnia_getSessionAddress

Derives a session key address from a seed.

  • Parameters: seed (32-byte hash)
  • Returns: address
  • Compatibility: Somnia-specific -- session key derivation
curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"somnia_getSessionAddress",
    "params":["0x0000000000000000000000000000000000000000000000000000000000000001"],
    "id":1
  }'

{"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 | null
  • Compatibility: Somnia-specific -- session key transactions
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 above.

somnia_reactivityGetSubscriptionInfo

Returns details of a Somnia Reactivity Protocol subscription by ID.

curl -s -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"somnia_reactivityGetSubscriptionInfo",
    "params":["0x1"],
    "id":1
  }'

{
  "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 subscriptions owned by an address.

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 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 protocol over HTTP POST or WebSocket. The request body is:

{"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.

[
  {"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:

  • 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:

Type Name EIP Notes
0x0 Legacy pre-EIP-2718 gasPrice field
0x1 Access list EIP-2930 gasPrice + accessList
0x2 Dynamic fee EIP-1559 maxFeePerGas + maxPriorityFeePerGas
0x3 Blob EIP-4844 Not supported
0x4 Set code EIP-7702 authorizationList for EOA code delegation

Error Codes

Error responses follow the JSON-RPC 2.0 format:

{"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:

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.

Log Query Limits

eth_getLogs, eth_newFilter, and 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_newBlockFilter, and 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 to return empty results or eth_uninstallFilter to return false. For reliable filter-based polling, use a dedicated RPC endpoint or switch to eth_subscribe over WebSocket.

Subscriptions created with eth_subscribe are also connection-scoped. 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_getTransactionReceipt, eth_getTransactionByBlockHashAndIndex, eth_getTransactionByBlockNumberAndIndex Returns null
eth_getBlockByHash, eth_getBlockByNumber, eth_getHeaderByHash, eth_getHeaderByNumber, somnia_getBlockByHash, somnia_getBlockByNumber Returns null
eth_getBlockTransactionCountByHash, eth_getBlockTransactionCountByNumber Returns "0x0"
eth_getBlockReceipts RPC error: "unknown block"
somnia_getPrivilegedTransactionReceiptsForBlockByHash, somnia_getPrivilegedTransactionReceiptsForBlockByNumber RPC error: "Block does not exist"
eth_uninstallFilter, 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 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_getHeaderByNumber omit the transactions field entirely rather than returning an empty array.
  • 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 is a Somnia extension that submits a transaction and blocks until the receipt is available, combining eth_sendRawTransaction + polling 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.

Appendix

Request Schemas

TransactionRequest (used by eth_call, eth_estimateGas, eth_createAccessList, 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[] 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_estimateGas, and debug_traceCall):

A JSON object keyed by account address, where each value is a 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 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 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[] 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 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[] Tx hashes if fullTxObjects=false, full objects if true. Omitted entirely for eth_getHeaderBy*.

SomniaLedgerBlock (returned by somnia_getBlockByNumber / somnia_getBlockByHash):

Field Type Notes
consensus_block SomniaConsensusBlock Consensus-layer block data
execution_block 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 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_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 notifications use this envelope:

{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":...}}

newHeads

  • Params: none
  • Event result: 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_newFilter
  • Event result: 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_newFilter
eth_calls array Each item is either a TransactionRequest, or [TransactionRequest, 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

Copied from docs.somnia.network (somnia-main-docs) by scripts/import-gitbook.mts, until it finds a home in a product's docs.Edit this page