Ethereum Interface (eth )

Ethereum Interface (eth_) provides an Ethereum-compatible JSON-RPC layer that allows existing wallets, tools, and libraries to interact with Pod using familiar methods and conventions. It is designed to be drop-in compatible with standard Ethereum client workflows, allowing developers to use common tooling such as ethers.js, alloy.rs, and cast without modification.

The interface covers the transaction submission and receipt lifecycle, including balance and nonce discovery, read-only contract calls, log queries, and real-time subscriptions.

📝 This is a JSON-RPC 2.0 API. The request path is not important; the method to execute is defined by the method field in the request body. You can send all requests to /, and any path after / is optional and used only for documentation clarity.

Get Native Token Balance

post

Returns the native token balance for the specified address in the wallet.

Note: This returns the wallet balance, which is distinct from the orderbook contract balance. To query the balance deposited in the orderbook contract, call the getBalance function on the orderbook contract.

The block_number parameter is accepted for Ethereum compatibility but is ignored.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_getBalance

idintegerRequiredDefault: 1

Responses

200

Balance in wei (hex-encoded uint256)

application/json

jsonrpcstringOptional

resultstringOptional

Unsigned 256-bit integer (hex-encoded with 0x prefix)

Example: 0x6f05b59d3b200000Pattern: ^0x[a-fA-F0-9]+$

idintegerOptional

post/eth_getBalance

POST /eth_getBalance HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "latest"
  ]
}

200

Balance in wei (hex-encoded uint256)

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

Get Chain ID

post

Returns the chain ID used for signing transactions (EIP-155).

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_chainId

idintegerRequiredDefault: 1

paramsarrayOptionalDefault: []

Responses

200

Chain ID (hex-encoded)

application/json

jsonrpcstringOptional

resultstringOptionalExample: 0x50d

idintegerOptional

post/eth_chainId

POST /eth_chainId HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "jsonrpc": "2.0",
  "method": "eth_chainId",
  "id": 1,
  "params": []
}

200

Chain ID (hex-encoded)

{
  "jsonrpc": "text",
  "result": "0x50d",
  "id": 1
}

Get Transaction by Hash

post

Returns the transaction that matches the given hash, or null if not found.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_getTransactionByHash

idintegerRequiredDefault: 1

paramsstring[]Required

Parameters:

transaction_hash (bytes32): The transaction hash to look up

Example: ["0xf74e07ff80dc54c7e894396954326fe13f07d176746a6a29d0ea34922b856402"]

Responses

200

Transaction object, or null if not found.

application/json

jsonrpcstringOptional

idintegerOptional

post/eth_getTransactionByHash

POST /eth_getTransactionByHash HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByHash",
  "id": 1,
  "params": [
    "0xf74e07ff80dc54c7e894396954326fe13f07d176746a6a29d0ea34922b856402"
  ]
}

200

Transaction object, or null if not found.

{
  "jsonrpc": "text",
  "result": {
    "hash": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "nonce": "text",
    "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "blockNumber": "text",
    "transactionIndex": "text",
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "value": "0x6f05b59d3b200000",
    "gas": "text",
    "gasPrice": "text",
    "input": "text",
    "v": "text",
    "r": "text",
    "s": "text"
  },
  "id": 1
}

Get Transaction Count (Nonce)

post

Returns the transaction count (nonce) for the specified address. Required for transaction signing to prevent replay attacks. The nonce is the current transaction count for the address.

Pod-specific: The block_tag parameter is accepted for Ethereum compatibility but is ignored.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_getTransactionCount

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

address (address): The address to get nonce for
block_tag (string): Block tag (accepted but ignored)

Example: ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28","latest"]

Responses

200

Nonce (hex-encoded uint256)

application/json

jsonrpcstringOptional

resultstringOptional

Unsigned 256-bit integer (hex-encoded with 0x prefix)

Example: 0x6f05b59d3b200000Pattern: ^0x[a-fA-F0-9]+$

idintegerOptional

post/eth_getTransactionCount

POST /eth_getTransactionCount HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 124

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionCount",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "latest"
  ]
}

200

Nonce (hex-encoded uint256)

{
  "jsonrpc": "text",
  "result": "0x6f05b59d3b200000",
  "id": 1
}

Send Raw Transaction (Fire-and-Forget)

post

Submits a signed EIP-1559 transaction to the network. Returns the transaction hash on success.

The transaction must be RLP-encoded and signed. Use this method to submit orderbook operations (deposits, withdrawals, order submissions, cancellations) to the orderbook contract.

For synchronous attestation feedback (successes/errors from validators), use pod_sendRawTransaction.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_sendRawTransaction

idintegerRequiredDefault: 1

paramsstring[]Required

Parameters:

signed_tx (string): Signed RLP-encoded transaction data

Example: ["0x02f8..."]

Responses

200

Transaction hash

application/json

jsonrpcstringOptional

resultstringOptional

32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc.

Example: 0x0000000000000000000000000000000000000000000000000000000000000001Pattern: ^0x[a-fA-F0-9]{64}$

idintegerOptional

post/eth_sendRawTransaction

POST /eth_sendRawTransaction HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "jsonrpc": "2.0",
  "method": "eth_sendRawTransaction",
  "id": 1,
  "params": [
    "0x02f8..."
  ]
}

200

Transaction hash

{
  "jsonrpc": "text",
  "result": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "id": 1
}

Execute Read-Only Call

post

Executes a new message call immediately without creating a transaction on the blockchain.

Use this method for read-only operations on the orderbook contract, such as:

getBalance(address token) - Get deposited balance for a token
getOrders(bytes32 orderbookId, bytes32[] txHashes) - Get order details by transaction hashes

Orderbook Contract Address: 0x50d0000000000000000000000000000000000002

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_call

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

transaction (object): Call object with to, data, and optionally from
block_tag (string): Block tag (e.g., "latest")

Example: [{"to":"0x50d0000000000000000000000000000000000002","data":"0x..."},"latest"]

Responses

200

Return data (hex-encoded)

application/json

jsonrpcstringOptional

resultstringOptionalExample: 0x000...

idintegerOptional

post/eth_call

POST /eth_call HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 131

{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "id": 1,
  "params": [
    {
      "to": "0x50d0000000000000000000000000000000000002",
      "data": "0x..."
    },
    "latest"
  ]
}

200

Return data (hex-encoded)

{
  "jsonrpc": "text",
  "result": "0x000...",
  "id": 1
}

Get Transaction Receipt

post

Retrieves the transaction receipt including execution status and event logs.

Pod-specific: The receipt includes pod_metadata containing validator attestations for transaction finality verification.

Returns null if the transaction is not found or not yet processed.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_getTransactionReceipt

idintegerRequiredDefault: 1

paramsstring[]Required

Parameters:

transaction_hash (bytes32): The transaction hash to look up

Example: ["0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"]

Responses

200

Transaction receipt with Pod-specific attestation data, or null if not found.

application/json

jsonrpcstringOptional

idintegerOptional

post/eth_getTransactionReceipt

POST /eth_getTransactionReceipt HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 141

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionReceipt",
  "id": 1,
  "params": [
    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  ]
}

200

Transaction receipt with Pod-specific attestation data, or null if not found.

{
  "jsonrpc": "2.0",
  "result": {
    "type": "0x2",
    "status": "0x1",
    "cumulativeGasUsed": "0xf4240",
    "logs": [],
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "transactionHash": "0x63dfbb7b3294d3d9aedb9bd1a306ec40156d0da1c374b2348f60c57186704fcd",
    "transactionIndex": "0x0",
    "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "blockNumber": "0x1",
    "gasUsed": "0xf4240",
    "effectiveGasPrice": "0x1",
    "from": "0xe51e549231219c35040efcf784f58776d5065d26",
    "to": "0x000000000000000000000000000000000000c10b",
    "contractAddress": null,
    "pod_metadata": {
      "attestations": [
        {
          "validator_address": "0x3ab7e9c61dece769dc872322ad1e83a5012aa480",
          "sequence_number": 14661,
          "batch_index": 0,
          "timestamp": 1770737135051543,
          "signature": "30450221008bd92c1b51d5f38b2938dab90aa6c401e5695092930885a12a1e42ae445bbbde0220068e6160d83d763079ff0861b21a71af625670dc40361075da7d1b13c92a50c4"
        }
      ],
      "committee_epoch": 0
    }
  },
  "id": 1
}

Estimate Gas

post

Estimates the gas required for a transaction.

Pod-specific behavior: If the transaction already specifies a gas value, returns that value. Otherwise, returns 21000 (standard transaction gas).

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_estimateGas

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

transaction (object): Transaction object with to, data, value, from, etc.

Example: [{"to":"0x50d0000000000000000000000000000000000002","value":"0x0"}]

Responses

200

Estimated gas (hex-encoded)

application/json

jsonrpcstringOptional

resultstringOptional

Unsigned 256-bit integer (hex-encoded with 0x prefix)

Example: 0x6f05b59d3b200000Pattern: ^0x[a-fA-F0-9]+$

idintegerOptional

post/eth_estimateGas

POST /eth_estimateGas HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 128

{
  "jsonrpc": "2.0",
  "method": "eth_estimateGas",
  "id": 1,
  "params": [
    {
      "to": "0x50d0000000000000000000000000000000000002",
      "value": "0x0"
    }
  ]
}

200

Estimated gas (hex-encoded)

{
  "jsonrpc": "text",
  "result": "0x6f05b59d3b200000",
  "id": 1
}

Get Logs

post

Returns an array of log objects matching the given filter criteria.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_getLogs

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

filter (object): Filter object with address, topics, fromBlock, toBlock

Example: [{"address":"0x50d0000000000000000000000000000000000002","topics":[]}]

Responses

200

Array of log objects

application/json

jsonrpcstringOptional

idintegerOptional

post/eth_getLogs

POST /eth_getLogs HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "jsonrpc": "2.0",
  "method": "eth_getLogs",
  "id": 1,
  "params": [
    {
      "address": "0x50d0000000000000000000000000000000000002",
      "topics": []
    }
  ]
}

200

Array of log objects

{
  "jsonrpc": "text",
  "result": [
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
      "topics": [
        "0x0000000000000000000000000000000000000000000000000000000000000001"
      ],
      "data": "text"
    }
  ],
  "id": 1
}

Subscribe to Events (WebSocket)

post

Creates a subscription to receive real-time updates over WebSocket. Updates are pushed after each auction settlement for the subscribed orderbook(s).

Subscription types:

pod_orderbook — each notification is a single OrderbookSnapshot for the orderbook (the same shape ob_getOrderbook returns).
pod_orders — each notification is an array of OrderUpdate describing what changed to orders this settlement: new/invalid orders, expirations, cancellations, modifications, and fills.

Subscriptions follow the standard Ethereum eth_subscribe pattern:

Subscribe with eth_subscribe → receive a subscription ID.
Receive updates as eth_subscription notifications (see the notification shape below).
Cancel with eth_unsubscribe, passing the subscription ID.

Notification format. Updates arrive as JSON-RPC notifications, not responses:

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": { "subscription": "0x<id>", "result": <payload> }
}

For pod_orderbook, result is an OrderbookSnapshot; for pod_orders, result is an array of OrderUpdate.

Filtering. Both subscription types accept clob_ids to restrict the stream to specific orderbooks (empty/omitted = all). pod_orders additionally accepts bidder: when set, the server delivers only the updates owned by that account — new/invalid orders, fills, expirations, and cancellations are all filtered — so a wallet tracking a single account no longer needs to filter the stream client-side. depth applies to pod_orderbook snapshots only. Which option applies to which subscription type is summarised in SubscriptionParams.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_subscribe

idintegerRequiredDefault: 1

Responses

200

Messages received on the subscription. The immediate reply to eth_subscribe is the subscription ID; every subsequent message is an eth_subscription notification whose params.result carries the streamed payload — an OrderbookSnapshot for pod_orderbook, or an array of OrderUpdate for pod_orders.

application/json

post/eth_subscribe

POST /eth_subscribe HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 171

{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "id": 1,
  "params": [
    "pod_orderbook",
    {
      "clob_ids": [
        "0x0000000000000000000000000000000000000000000000000000000000000001"
      ],
      "depth": 50
    }
  ]
}

200

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

Cancel a Subscription (WebSocket)

post

Cancels an active subscription created with eth_subscribe. Pass the subscription ID returned by the original eth_subscribe call. Returns true if a matching subscription was found and removed.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: eth_unsubscribe

idintegerRequiredDefault: 1

paramsstring[]Required

Parameters:

subscription_id (string): The ID returned by eth_subscribe

Example: ["0x9ce59a13059e417087c02d3236a0b1cc"]

Responses

200

Whether the subscription was found and cancelled

application/json

jsonrpcstringOptional

resultbooleanOptional

idintegerOptional

post/eth_unsubscribe

POST /eth_unsubscribe HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "id": 1,
  "params": [
    "0x9ce59a13059e417087c02d3236a0b1cc"
  ]
}

200

Whether the subscription was found and cancelled

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

PreviousOrderbook Data (ob )NextNetwork & Consensus (pod )

Last updated 27 days ago