bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_getBlockByNumber",
"params":["0xfebbe5e"],
"id":1
}'
```
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"consensus_block": {
"block_number": "0xfebbe5e",
"timestamp": "0x19d39bb90f5",
"data_chain_blocks": ["0x0798136c..."],
"delayed_ledger_block_number": "0xfebbe4e",
"delayed_ledger_block_hash": "0x03b01a71...",
"parent_consensus_block_hash": "0xf9f64c1d...",
"proposer_address": "0x012f6f8ded4e1f977953cd8dbfff31ebb902549c",
"block_resources": {
"validation_gas": "0x9c40",
"compressed_bytes": "0x7c",
"uncompressed_bytes": "0x7d"
},
"consensus_block_hash": "0xb83203e7..."
},
"execution_block": {
"transaction_ids_hash": "0xb3704a7f...",
"receipts_hash": "0x38cb8db2...",
"execution_gas_limit": "0x5208",
"execution_gas_used": "0x5208",
"execution_state_snapshot": "0xc076805e...",
"state_snapshot_block_number": "0xfebb2e7",
"operation_sequence_hash": "0xb4e658ec67dbe4de"
},
"parent_ledger_block_hash": "0x2fe94d90...",
"ledger_block_hash": "0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98"
}
}
```
***
#### `somnia_getBlockByHash`
Same as [`somnia_getBlockByNumber`](#somnia_getblockbynumber) but looks up by block hash.
* **Parameters:** `blockHash`
* **Returns:** [`SomniaLedgerBlock`](#somnialedgerblock) `| null`
* **Compatibility:** **Somnia-specific** -- native block format (cf. [`eth_getBlockByHash`](#eth_getblockbyhash))
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_getBlockByHash",
"params":["0x761fdbb98eb904196b6be98870b222fc2f06d2fdac4bae1200f177092ce6ec98"],
"id":1
}'
```
Response format is identical to [`somnia_getBlockByNumber`](#somnia_getblockbynumber) above.
***
#### `somnia_getStatistics`
Returns chain statistics over a block range.
* **Parameters:** `fromBlock` (hex or label), `toBlock` (hex or label)
* **Returns:** json object
* **Compatibility:** **Somnia-specific**
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_getStatistics",
"params":["0xfebbe5e", "0xfebbe60"],
"id":1
}'
```
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"numSuccessfulTransactions": "0x1",
"numRevertedTransactions": "0x0",
"numContractsAdded": "0x0",
"numAccountsAdded": "0x0",
"numNewUsedEoaAccounts": "0x0",
"numNativeTransferTransactions": "0x1",
"numGasUnitsSpent": "0x5208",
"gasFeeSpent": "0x7298a93de000"
}
}
```
***
#### `somnia_getPrivilegedTransactionReceiptsForBlockByNumber`
Returns receipts for privileged (system) transactions in a block.
* **Parameters:** `blockNumber` (hex or label)
* **Returns:** [`TransactionReceipt`](#transactionreceipt)`[]`
* **Compatibility:** **Somnia-specific** -- system/privileged tx receipts
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_getPrivilegedTransactionReceiptsForBlockByNumber",
"params":["0xfef96ff"],
"id":1
}'
```
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"transactionHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"transactionIndex": "0x0",
"blockHash": "0xf3ef3de9a584326c0252b44f111aa7d342d6698678d310a5b1233622aab94a5e",
"blockNumber": "0xfef96ff",
"from": "0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7",
"to": "0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7",
"cumulativeGasUsed": "0x0",
"gasUsed": "0x42a5ca",
"contractAddress": null,
"type": "0x18",
"status": "0x1",
"logsBloom": "0x00000000...00000000",
"logs": [
{
"address": "0x7b8b1bb68c6f0e29f3addcb45a6c0bb8e8e331c7",
"topics": ["0x6debf9c0b8bd7ecda40db89a2641f61251d80a576b5c5e5f06de7f1c2a65850a"],
"data": "0x00000000000000000000000000000000000000000000000000000000000000330000000000000000000000000000000000000000000000000000000069c988e4",
"blockNumber": "0xfef96ff",
"transactionHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"transactionIndex": "0x0",
"blockHash": "0xf3ef3de9a584326c0252b44f111aa7d342d6698678d310a5b1233622aab94a5e",
"logIndex": "0x0"
}
],
"effectiveGasPrice": "0x0"
},
...
]
}
```
***
#### `somnia_getPrivilegedTransactionReceiptsForBlockByHash`
Returns receipts for privileged (system) transactions in a block. Same as [`somnia_getPrivilegedTransactionReceiptsForBlockByNumber`](#somnia_getprivilegedtransactionreceiptsforblockbynumber) but looks up by block hash.
* **Parameters:** `blockHash`
* **Returns:** [`TransactionReceipt`](#transactionreceipt)`[]`
* **Compatibility:** **Somnia-specific** -- system/privileged tx receipts
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_getPrivilegedTransactionReceiptsForBlockByHash",
"params":["0xf3ef3de9a584326c0252b44f111aa7d342d6698678d310a5b1233622aab94a5e"],
"id":1
}'
```
Response format is identical to [`somnia_getPrivilegedTransactionReceiptsForBlockByNumber`](#somnia_getprivilegedtransactionreceiptsforblockbynumber) above.
***
#### `somnia_getSessionAddress`
Derives a session key address from a seed.
* **Parameters:** `seed` (32-byte hash)
* **Returns:** `address`
* **Compatibility:** **Somnia-specific** -- session key derivation
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_getSessionAddress",
"params":["0x0000000000000000000000000000000000000000000000000000000000000001"],
"id":1
}'
```
```json
{"jsonrpc":"2.0","id":1,"result":"0xf2d469b1fb798a5e9ced20e22daa7a911f35d697"}
```
***
#### `somnia_sendSessionTransaction`
Sends a transaction using a session key (derived from a seed). The session account must have sufficient funds.
* **Parameters:** object with `seed` (hash), `gas` (hex), `to` (address, optional), `value` (hex, optional), `data` (hex, optional)
* **Returns:** [`TransactionReceipt`](#transactionreceipt) `| null`
* **Compatibility:** **Somnia-specific** -- session key transactions
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_sendSessionTransaction",
"params":[{
"seed": "0x0000000000000000000000000000000000000000000000000000000000000001",
"gas": "0x5208",
"to": "0x1909cdb9524d065e5751d2fe79e2b9ad54d822e6",
"value": "0x0"
}],
"id":1
}'
```
Response format is identical to [`eth_getTransactionReceipt`](#eth_gettransactionreceipt) above.
***
#### `somnia_reactivityGetSubscriptionInfo`
Returns details of a [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity) subscription by ID.
* **Parameters:** `subscriptionId` (hex-encoded subscription ID)
* **Returns:** [`ReactivitySubscription`](#reactivitysubscription)
* **Compatibility:** **Somnia-specific** -- [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity)
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_reactivityGetSubscriptionInfo",
"params":["0x1"],
"id":1
}'
```
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"id": "0x1",
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x0000000000000000000000000000000000000000000000000000000000000000",
"0x0000000000000000000000000000000000000000000000000000000000000000",
"0x0000000000000000000000000000000000000000000000000000000000000000"
],
"origin": "0x0000000000000000000000000000000000000000",
"caller": "0x0000000000000000000000000000000000000000",
"emitter": "0x107256636b98e705fade330bbcb903580b8b227d",
"owner": "0x12a76e09bae1934265a1aea2812e0c772f372f8d",
"handler_contract_address": "0xf84f7633bd403967999b06911f978a74326f547e",
"handler_function_selector": "0x53edf33d",
"gas_limit": "0x4c4b40",
"priority_fee_per_gas": "0x77359400",
"max_fee_per_gas": "0x2540be400"
}
}
```
***
#### `somnia_reactivityGetSubscriptions`
Returns all [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity) subscriptions owned by an address.
* **Parameters:** `address` (owner address)
* **Returns:** [`ReactivitySubscription[]`](#reactivitysubscription)
* **Compatibility:** **Somnia-specific** -- [Somnia Reactivity Protocol](https://docs.somnia.network/developer/reactivity)
```bash
curl -s -X POST $RPC_URL \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"somnia_reactivityGetSubscriptions",
"params":["0x12a76e09bae1934265a1aea2812e0c772f372f8d"],
"id":1
}'
```
Response is a JSON array of [`ReactivitySubscription`](#reactivitysubscription) objects.
***
<br>
## Notes
### General Usage
#### Endpoints
| Network | HTTP | WebSocket |
| ------------------------------------------- | ------------------------------------------ | ------------------------------------------- |
| Mainnet (chain ID `0x13a7` / 5031) | `https://api.infra.mainnet.somnia.network` | `wss://api.infra.mainnet.somnia.network/ws` |
| Testnet Shannon (chain ID `0xc488` / 50312) | `https://api.infra.testnet.somnia.network` | `wss://api.infra.testnet.somnia.network/ws` |
#### Request Format
All requests use the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol over HTTP POST or WebSocket. The request body is:
```json
{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}
```
**Batch requests** are supported: send a JSON array of request objects and receive a JSON array of responses in the same order.
```json
[
{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1},
{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":2}
]
```
#### Hex Encoding
All numeric values in requests and responses are hex-encoded with a `0x` prefix, following the [Ethereum JSON-RPC convention](https://ethereum.org/developers/docs/apis/json-rpc/#conventions):
* **Quantities** (block numbers, gas, balances, nonces): hex without leading zeros — `"0x1"`, `"0x5208"`, `"0x165a0bc00"`
* **Data** (hashes, addresses, bytecode, input data): hex with even-length zero-padding — `"0x0000...0000"`, `"0x"`
#### Block Labels
Many methods accept a **block label** parameter. This can be:
* A hex-encoded block number (e.g. `"0xfebbe5e"`)
* `"latest"` — the most recent confirmed block
* `"earliest"` — the genesis block (block 0)
* `"finalized"`, `"pending"`, `"safe"` — currently treated the same as `"latest"`
#### Transaction Types
Somnia supports the following Ethereum transaction types via [`eth_sendRawTransaction`](#eth_sendrawtransaction):
| Type | Name | EIP | Notes |
| ----- | ----------- | --------------------------------------------------- | ------------------------------------------- |
| `0x0` | Legacy | pre-EIP-2718 | `gasPrice` field |
| `0x1` | Access list | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) | `gasPrice` + `accessList` |
| `0x2` | Dynamic fee | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) | `maxFeePerGas` + `maxPriorityFeePerGas` |
| `0x3` | Blob | [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) | **Not supported** |
| `0x4` | Set code | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) | `authorizationList` for EOA code delegation |
#### Error Codes
Error responses follow the JSON-RPC 2.0 format:
```json
{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"insufficient balance","data":null}}
```
| Code | Meaning | Common causes |
| -------- | -------------------- | ----------------------------------------------------------- |
| `-32700` | Parse error | Malformed JSON |
| `-32600` | Invalid request | Missing `jsonrpc`, `method`, or `id` fields |
| `-32601` | Method not found | Typo in method name, or method not available on this node |
| `-32602` | Invalid parameters | Wrong number or types of params |
| `-32603` | Internal error | Node not ready, or unexpected server error |
| `-32604` | Too many requests | Rate limit exceeded |
| `-32004` | Method not supported | Method exists but is disabled on this node |
| `-32000` | Invalid input | Transaction-specific errors (see below) |
| `-1` | Application error | Handler-specific errors (e.g. `"block range exceeds 1000"`) |
Common `-32000` transaction errors from [`eth_sendRawTransaction`](#eth_sendrawtransaction):
| Message | Meaning |
| ---------------------------- | ---------------------------------------------------------- |
| `"invalid transaction"` | RLP decoding failed or transaction is malformed |
| `"invalid signature"` | ECDSA signature verification failed |
| `"nonce too low"` | Transaction nonce is behind the account's current nonce |
| `"nonce too high"` | Transaction nonce is too far ahead |
| `"insufficient balance"` | Account cannot cover value + gas |
| `"gas price below base fee"` | `gasPrice` or `maxFeePerGas` is below the current base fee |
| `"mempool full"` | Node's transaction pool is at capacity |
### Special Cases
#### Requires Node Ready
Some methods are marked **Requires Node Ready** in the index table. These methods will return an error if the node has not finished syncing and is not yet ready to serve requests.
You can check whether a node is ready before making calls by using [`somnia_isReady`](#somnia_isready).
#### Log Query Limits
[`eth_getLogs`](#eth_getlogs), [`eth_newFilter`](#eth_newfilter), and [`eth_getFilterLogs`](#eth_getfilterlogs) enforce a maximum block range (currently 1000 blocks). Queries exceeding this range will return an error. To scan larger ranges, issue multiple queries with non-overlapping block ranges.
#### Filter and Subscription Statefulness
Filters created with [`eth_newFilter`](#eth_newfilter), [`eth_newBlockFilter`](#eth_newblockfilter), and [`eth_newPendingTransactionFilter`](#eth_newpendingtransactionfilter) are scoped to the connection that created them. On load-balanced public RPC endpoints, subsequent requests may be routed to a different backend, causing [`eth_getFilterChanges`](#eth_getfilterchanges) to return empty results or [`eth_uninstallFilter`](#eth_uninstallfilter) to return `false`. For reliable filter-based polling, use a dedicated RPC endpoint or switch to [`eth_subscribe`](#eth_subscribe) over WebSocket.
Subscriptions created with [`eth_subscribe`](#eth_subscribe) are also connection-scoped. [`eth_unsubscribe`](#eth_unsubscribe) returns `false` if the subscription id is unknown or belongs to a different connection.
#### Missing Resource Semantics
Somnia does not use a single convention for "not found". The main cases are:
| Method(s) | Missing resource behaviour |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`eth_getTransactionByHash`](#eth_gettransactionbyhash), [`eth_getTransactionReceipt`](#eth_gettransactionreceipt), [`eth_getTransactionByBlockHashAndIndex`](#eth_gettransactionbyblockhashandindex), [`eth_getTransactionByBlockNumberAndIndex`](#eth_gettransactionbyblocknumberandindex) | Returns `null` |
| [`eth_getBlockByHash`](#eth_getblockbyhash), [`eth_getBlockByNumber`](#eth_getblockbynumber), [`eth_getHeaderByHash`](#eth_getheaderbyhash), [`eth_getHeaderByNumber`](#eth_getheaderbynumber), [`somnia_getBlockByHash`](#somnia_getblockbyhash), [`somnia_getBlockByNumber`](#somnia_getblockbynumber) | Returns `null` |
| [`eth_getBlockTransactionCountByHash`](#eth_getblocktransactioncountbyhash), [`eth_getBlockTransactionCountByNumber`](#eth_getblocktransactioncountbynumber) | Returns `"0x0"` |
| [`eth_getBlockReceipts`](#eth_getblockreceipts) | RPC error: `"unknown block"` |
| [`somnia_getPrivilegedTransactionReceiptsForBlockByHash`](#somnia_getprivilegedtransactionreceiptsforblockbyhash), [`somnia_getPrivilegedTransactionReceiptsForBlockByNumber`](#somnia_getprivilegedtransactionreceiptsforblockbynumber) | RPC error: `"Block does not exist"` |
| [`eth_uninstallFilter`](#eth_uninstallfilter), [`eth_unsubscribe`](#eth_unsubscribe) | Returns `false` if the id is unknown or belongs to another connection |
#### Somnia vs Ethereum Differences
While Somnia is EVM-compatible and supports the standard Ethereum JSON-RPC, there are a few behavioural differences to be aware of:
* [**`eth_syncing`**](#eth_syncing) returns only a `bool` (`true` while syncing, `false` when ready). It does not return a sync-status object with `startingBlock`/`currentBlock`/`highestBlock` fields as Ethereum clients do.
* [**`eth_getHeaderByHash`**](#eth_getheaderbyhash) **/** [**`eth_getHeaderByNumber`**](#eth_getheaderbynumber) omit the `transactions` field entirely rather than returning an empty array.
* [**`eth_subscribe`**](#eth_subscribe) supports the standard `"newHeads"` and `"logs"` types, plus three Somnia-specific types: `"somnia_finishedTransactions"`, `"somnia_finishedBlocks"`, and `"somnia_watch"`. It does **not** support `"newPendingTransactions"`.
* [**`realtime_sendRawTransaction`**](#realtime_sendrawtransaction) is a Somnia extension that submits a transaction and blocks until the receipt is available, combining [`eth_sendRawTransaction`](#eth_sendrawtransaction) + polling [`eth_getTransactionReceipt`](#eth_gettransactionreceipt) into a single call.
* **Block structure**: Somnia blocks have a fixed `difficulty` of `0x0`, `miner` of `0x0...0`, and no uncle blocks. The `gasLimit` reflects per-block execution gas rather than a global gas target.
* **EIP-4844 blob transactions** (type `0x3`) are not supported.
For more detail on gas behaviour, see [Somnia Gas Differences to Ethereum](/developer/deployment-and-production/somnia-gas-differences-to-ethereum).
## Appendix
### Request Schemas
**TransactionRequest** (used by [`eth_call`](#eth_call), [`eth_estimateGas`](#eth_estimategas), [`eth_createAccessList`](#eth_createaccesslist), [`debug_traceCall`](#debug_tracecall), and `somnia_watch.eth_calls`):
| Field | Type | Notes |
| ------------------- | ----------------------------------------------------------------- | --------------------------------------------- |
| `from` | `address` or `null` | Sender address for simulation |
| `to` | `address` or `null` | Omit or set `null` for contract creation |
| `gas` | `quantity` or `null` | Gas limit for the simulated transaction |
| `value` | `quantity` or `null` | Wei transferred |
| `input` | `bytes` or `null` | Calldata alias accepted by Geth-style clients |
| `data` | `bytes` or `null` | Calldata alias |
| `authorizationList` | [`AuthorizationListEntry`](#authorizationlistentry)`[]` or `null` | EIP-7702 authorization list |
> `input` and `data` are interchangeable aliases. If both are provided, Somnia uses `input`.
**AuthorizationListEntry** (entries within `authorizationList`):
| Field | Type | Notes |
| --------- | ---------- | -------------------------------------- |
| `chainId` | `quantity` | Chain id covered by the authorization |
| `address` | `address` | Contract address to delegate code from |
| `nonce` | `quantity` | Authorization nonce |
| `yParity` | `quantity` | Signature recovery parity |
| `r` | `quantity` | Signature component |
| `s` | `quantity` | Signature component |
**StateOverrideSet** (used by [`eth_call`](#eth_call), [`eth_estimateGas`](#eth_estimategas), and [`debug_traceCall`](#debug_tracecall)):
A JSON object keyed by account address, where each value is a [`StateOverride`](#stateoverride) object.
**StateOverride**:
| Field | Type | Notes |
| ----------- | -------------------- | ----------------------------------------------------------- |
| `balance` | `quantity` or `null` | Override account balance |
| `nonce` | `quantity` or `null` | Override account nonce |
| `code` | `bytes` or `null` | Override deployed bytecode |
| `state` | `object` or `null` | Replace the entire storage ma프로젝트로 돌아가기 