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

Yes

Yes

Yes

Yes

eth_getBlockTransactionCountByHash

Ethereum standard

eth_getBlockTransactionCountByNumber

Yes

eth_getHeaderByNumber

Yes

eth_getTransactionByBlockHashAndIndex

Ethereum standard

eth_getTransactionByBlockNumberAndIndex

Ethereum standard

eth_getTransactionByHash

Ethereum standard

eth_getTransactionCount

Ethereum standard

Yes

eth_getTransactionReceipt

Ethereum standard

eth_maxPriorityFeePerGas

eth_newPendingTransactionFilter

Ethereum standard

eth_sendRawTransaction

Yes

Yes

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

Methods by Category

Network / Web3

`net_version`

Returns the network ID.

Parameters: (none)
Returns: quantity (uint256)
Compatibility: EIP-1474, ethereum.org

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.

Parameters: (none)
Returns: bool
Compatibility: EIP-1474, ethereum.org

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.

Parameters: (none)
Returns: string
Compatibility: EIP-1474, ethereum.org

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.

Parameters: data (hex)
Returns: hash
Compatibility: EIP-1474, ethereum.org

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.

Parameters: (none)
Returns: quantity (uint256)
Compatibility: EIP-695, ethereum.org

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.

Parameters: (none)
Returns: bool
Compatibility: EIP-1474, ethereum.org

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.

Parameters: (none)
Returns: quantity (block number)
Compatibility: EIP-1474, ethereum.org

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

Parameters: (none)
Returns: address[]
Compatibility: EIP-1474, ethereum.org

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.

Parameters: address, blockLabel
Returns: quantity (uint64)
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_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).

Parameters: address, 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_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.

Parameters: txHash
Returns: Transaction | null
Compatibility: EIP-1474, ethereum.org

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.

Parameters: blockHash, index (hex)
Returns: Transaction | null
Compatibility: EIP-1474, ethereum.org

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.

Parameters: blockNumber (hex or label), index (hex)
Returns: Transaction | null
Compatibility: EIP-1474, ethereum.org

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.

Parameters: txHash
Returns: TransactionReceipt | null
Compatibility: EIP-1474, ethereum.org

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.

Parameters: blockNumberOrHash (hex block number, block hash, or label like "latest")
Returns: TransactionReceipt[]
Compatibility: execution-apis

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.

Parameters: blockHash, fullTransactions (bool)
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_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.

Parameters: blockHash
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_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.

Parameters: (none)
Returns: quantity (filter id)
Compatibility: EIP-1474, ethereum.org

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.

Parameters: (none)
Returns: quantity (filter id)
Compatibility: EIP-1474, ethereum.org

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

Parameters: filterId (hex)
Returns: Log[]
Compatibility: EIP-1474, ethereum.org

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.

Parameters: filterId (hex)
Returns: bool
Compatibility: EIP-1474, ethereum.org

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.

Parameters: (none)
Returns: quantity (uint256)
Compatibility: EIP-1474, ethereum.org, execution-apis

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.

Parameters: (none)
Returns: quantity (uint256)
Compatibility: EIP-1559, execution-apis

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

Parameters: TransactionRequest, blockLabelOrHash, optional StateOverrideSet (see Request Schemas)
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_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.

Parameters: TransactionRequest, optional blockLabel, optional StateOverrideSet (see Request Schemas)
Returns: quantity (uint64)
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_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.)

Parameters: TransactionRequest, optional blockLabel (see Request Schemas)
Returns: [accessList, gasUsed] (JSON array)
Compatibility: EIP-2930, execution-APIs
Requires node to be ready

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.

Parameters: TransactionRequest, blockLabelOrHash, trace config (tracer, tracerConfig, stateOverrides) (see Request Schemas)
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_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.

Parameters: blockLabel (hex or label)
Returns: SomniaLedgerBlock | null
Compatibility: Somnia-specific -- native block format (cf. 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.

Parameters: blockHash
Returns: SomniaLedgerBlock | null
Compatibility: Somnia-specific -- native block format (cf. eth_getBlockByHash)

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.

Parameters: subscriptionId (hex-encoded subscription ID)
Returns: ReactivitySubscription
Compatibility: Somnia-specific -- Somnia Reactivity Protocol

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.

Parameters: address (owner address)
Returns: ReactivitySubscription[]
Compatibility: Somnia-specific -- Somnia Reactivity Protocol

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

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

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

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

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

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

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

PreviousSomnia Mainnet Releases NextSomnia Reactivity

Last updated 20 days ago