> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/network/building-on-nexus/endpoints.md). # Endpoints For RPC URLs, chain IDs, wallet setup, and developer tooling configuration, see [Developer Environment Setup](https://docs.nexus.xyz/network/building-on-nexus/developer-environment-setup). ## RPC ### Request Format All requests use the standard JSON-RPC 2.0 envelope: ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": "0x2c620e" } ``` #### Batch Requests Send an array of request objects to execute multiple calls in a single HTTP round-trip. Maximum **10 sub-requests** per batch. ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '[ {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}, {"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":2}, {"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":3} ]' ``` ### Request limits | Limit | Value | Error | | ---------------------- | ------------ | ------------------------------------- | | Max payload size | 2 MB | JSON-RPC `-32005` | | Max batch sub-requests | 10 per batch | JSON-RPC `-32005` | | Per-IP rate limiting | Active | JSON-RPC error + `Retry-After` header | All rejections return standard JSON-RPC error responses. When rate-limited, back off and retry after the duration specified in the `Retry-After` header. ### Supported Methods #### `eth` Namespace Standard Ethereum execution API methods. All methods accept `latest`, `earliest`, `pending`, or a hex block number as the block parameter unless noted otherwise. **Reading Chain State** | Method | Description | | -------------------------- | --------------------------------------------------------------------------------------- | | `eth_blockNumber` | Returns the current block height. | | `eth_chainId` | Returns the chain ID (`0xf6a` for mainnet, `0xf69` for testnet). | | `eth_gasPrice` | Returns the current gas price in wei. | | `eth_maxPriorityFeePerGas` | Returns the suggested priority fee (tip) in wei. | | `eth_feeHistory` | Returns base fee and gas usage history for a range of blocks. | | `eth_blobBaseFee` | Returns the blob base fee. Always returns `0x1` on Nexus (EIP-4844 blobs are not used). | | `eth_syncing` | Returns `false` when synced, or sync progress object when syncing. | **Example: `eth_gasPrice`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": "0x6b" } ``` **Accounts and Balances** | Method | Parameters | Description | | ------------------------- | ----------------------------------------- | ----------------------------------------------------------------- | | `eth_getBalance` | `address`, `blockNumber` | Returns the NEX balance of an address in wei. | | `eth_getTransactionCount` | `address`, `blockNumber` | Returns the nonce (number of transactions sent from the address). | | `eth_getCode` | `address`, `blockNumber` | Returns the contract bytecode at the address, or `0x` for EOAs. | | `eth_getStorageAt` | `address`, `position`, `blockNumber` | Returns the value in a contract's storage slot. | | `eth_getProof` | `address`, `storageKeys[]`, `blockNumber` | Returns the Merkle proof for an account and its storage slots. | | `eth_accounts` | — | Returns an empty array (no managed accounts on public RPC). | **Example: `eth_getBalance`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "latest"], "id": 1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": "0x0" } ``` **Blocks** | Method | Parameters | Description | | -------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eth_getBlockByNumber` | `blockNumber`, `fullTransactions` | Returns block data by number. Set `fullTransactions` to `true` for full tx objects, `false` for tx hashes only. | | `eth_getBlockByHash` | `blockHash`, `fullTransactions` | Returns block data by hash. | | `eth_getBlockTransactionCountByNumber` | `blockNumber` | Returns the number of transactions in a block by number. | | `eth_getBlockTransactionCountByHash` | `blockHash` | Returns the number of transactions in a block by hash. | | `eth_getBlockReceipts` | `blockNumberOrTag` | Returns all transaction receipts for a block. Accepts a block number, block hash, or block tag. (reth extension — not part of the base Ethereum JSON-RPC spec.) | **Example: `eth_getBlockByNumber`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_getBlockByNumber", "params": ["latest", false], "id": 1 }' ``` Returns the full block header plus an array of transaction hashes (or full transaction objects if the second parameter is `true`). **Transactions** | Method | Parameters | Description | | ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------- | | `eth_getTransactionByHash` | `txHash` | Returns transaction data by hash, or `null` if not found. | | `eth_getTransactionReceipt` | `txHash` | Returns the receipt for a mined transaction, or `null` if pending/unknown. | | `eth_getTransactionByBlockHashAndIndex` | `blockHash`, `index` (hex) | Returns a transaction by block hash and position index (e.g., `"0x0"` for the first). | | `eth_getTransactionByBlockNumberAndIndex` | `blockNumber`, `index` (hex) | Returns a transaction by block number and position index. | | `eth_sendRawTransaction` | `signedTxData` | Submits a signed transaction to the network. Returns the transaction hash. | **Example: `eth_sendRawTransaction`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_sendRawTransaction", "params": ["0x02f870..."], "id": 1 }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": "0x..." } ``` Replace the params value with your full RLP-encoded signed transaction. The transaction must be signed with a valid chain ID (`3946` for mainnet, `3945` for testnet). EIP-1559 (type 2) transactions are supported. The transaction object accepts `maxFeePerGas` and `maxPriorityFeePerGas` fields for fee specification. **Logs and Filters** | Method | Parameters | Description | | --------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- | | `eth_getLogs` | `filterObject` | Returns logs matching the filter. Large block ranges may be routed to the archive node automatically. | | `eth_newFilter` | `filterObject` | Creates a log filter, returns a filter ID. Poll with `eth_getFilterChanges`. | | `eth_newBlockFilter` | — | Creates a filter for new blocks. Poll with `eth_getFilterChanges`. | | `eth_newPendingTransactionFilter` | — | Creates a filter for pending transactions. Poll with `eth_getFilterChanges`. | | `eth_getFilterChanges` | `filterId` | Returns new entries since the last poll for the given filter ID. | | `eth_getFilterLogs` | `filterId` | Returns all logs matching the filter (equivalent to `eth_getLogs` for the filter's parameters). | | `eth_uninstallFilter` | `filterId` | Removes a filter. Filters also expire after a period of inactivity. | The filter object accepts `fromBlock`, `toBlock`, `address`, and `topics` fields. Keep block ranges small for best performance. For real-time log streaming, prefer WebSocket subscriptions over HTTP filter polling. **Example: `eth_getLogs`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_getLogs", "params": [{ "fromBlock": "0x2c6200", "toBlock": "0x2c620e", "address": "0x69BFfB3C9cb3aa81E8ab23dad470246956D2cC7F" }], "id": 1 }' ``` **Execution** | Method | Parameters | Description | | ---------------------- | ------------------------- | -------------------------------------------------------------------------------- | | `eth_call` | `txObject`, `blockNumber` | Executes a call without creating a transaction. Used for reading contract state. | | `eth_estimateGas` | `txObject`, `blockNumber` | Estimates the gas required to execute a transaction. | | `eth_createAccessList` | `txObject`, `blockNumber` | Creates an EIP-2930 access list for a transaction. | **Example: `eth_call`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_call", "params": [{ "to": "0x69BFfB3C9cb3aa81E8ab23dad470246956D2cC7F", "data": "0x18160ddd" }, "latest"], "id": 1 }' ``` `0x18160ddd` is the function selector for `totalSupply()`. Replace `to` with any contract address and `data` with the appropriate ABI-encoded call data. #### `net` Namespace | Method | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `net_version` | Returns the network ID as a decimal string (`"3946"` for mainnet, `"3945"` for testnet). Note: this returns a decimal string, unlike `eth_chainId` which returns hex. | | `net_peerCount` | Returns the number of connected peers. | | `net_listening` | Returns `true` if the node is listening for connections. | #### `web3` Namespace | Method | Description | | -------------------- | -------------------------------------------------------------------------------- | | `web3_clientVersion` | Returns the client identifier (`reth/v1.10.2-8e3b5e6/x86_64-unknown-linux-gnu`). | | `web3_sha3` | Returns the Keccak-256 hash of the given data. | ## WebSocket WebSocket connections (`wss://mainnet.rpc.nexus.xyz`, `wss://testnet.rpc.nexus.xyz`) require an `X-Api-Key` header on the upgrade handshake. Since browsers cannot set custom headers on WebSocket connections, WSS is currently limited to server-side use (Node.js, Python, etc.). Browser dApps should use HTTP polling or a server-side relay. **Subscription Methods:** | Method | Description | | ----------------- | ------------------------------------------ | | `eth_subscribe` | Opens a subscription for real-time events. | | `eth_unsubscribe` | Closes an active subscription. | **Subscription Types:** | Type | Description | | ------------------------ | -------------------------------------------------------------------------------------------------- | | `newHeads` | Emits a header object each time a new block is produced (\~1 per second). | | `logs` | Emits log entries matching a filter in real time. Accepts the same filter object as `eth_getLogs`. | | `newPendingTransactions` | Emits transaction hashes as they enter the mempool. | **Example: Subscribe to new blocks (Node.js)** ```javascript const WebSocket = require("ws"); const ws = new WebSocket("wss://mainnet.rpc.nexus.xyz", { headers: { "X-Api-Key": "YOUR_API_KEY" }, }); ws.on("open", () => { ws.send(JSON.stringify({ jsonrpc: "2.0", method: "eth_subscribe", params: ["newHeads"], id: 1, })); }); ws.on("message", (data) => { const msg = JSON.parse(data); if (msg.params) { console.log("New block:", parseInt(msg.params.result.number, 16)); } }); ``` **Example: Subscribe to new blocks (Python)** ```python import asyncio import json import websockets async def subscribe(): async with websockets.connect( "wss://mainnet.rpc.nexus.xyz", additional_headers={"X-Api-Key": "YOUR_API_KEY"}, ) as ws: await ws.send(json.dumps({ "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"], "id": 1, })) async for message in ws: msg = json.loads(message) if "params" in msg: block_num = int(msg["params"]["result"]["number"], 16) print(f"New block: {block_num}") asyncio.run(subscribe()) ``` ## Archive & Historical Data The default RPC endpoint routes to full nodes. Debug, trace, and historical queries route through a separate archive path. #### Method Routing | Method category | Default RPC (`/`) | Archive (`/archive`) | | ------------------------------------------------------------------- | ------------------------------- | -------------------- | | Standard methods (`eth_blockNumber`, `eth_getBalance@latest`, etc.) | Yes | No | | `debug_*` | No (`-32601`) | Yes | | `trace_*` | No (`-32601`) | Yes | | `eth_getLogs` with block range | Routed to archive automatically | Yes | #### Archive and Debug Methods Debug and trace methods are not available on the default RPC endpoint. They are served from a separate archive node at the `/archive` path. | Method | Endpoint | Description | | -------------------------- | ---------- | ------------------------------------------------------------------- | | `debug_traceTransaction` | `/archive` | Returns the execution trace of a transaction. | | `debug_traceBlockByNumber` | `/archive` | Returns execution traces for all transactions in a block. | | `debug_traceBlockByHash` | `/archive` | Returns execution traces for all transactions in a block (by hash). | | `trace_block` | `/archive` | Returns Parity-style traces for all transactions in a block. | | `trace_transaction` | `/archive` | Returns Parity-style traces for a single transaction. | | `trace_replayTransaction` | `/archive` | Re-executes a transaction and returns the requested trace types. | Standard methods (`eth_blockNumber`, `eth_chainId`, etc.) are **rejected** on the `/archive` path. Use the default endpoint for those. **Example: `debug_traceTransaction`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz/archive \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "debug_traceTransaction", "params": ["0xYOUR_TX_HASH", {"tracer": "callTracer"}], "id": 1 }' ``` The `callTracer` and `prestateTracer` built-in tracers are both supported. **Example: `trace_block`** ```bash curl -s -X POST https://mainnet.rpc.nexus.xyz/archive \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "trace_block", "params": ["0x2c620e"], "id": 1 }' ``` Pass a hex-encoded block number. Block tags like `"latest"` are not accepted by `trace_block`. #### Archive endpoint Append `/archive` to the RPC URL: ``` # Testnet archive curl -s -X POST https://testnet.rpc.nexus.xyz/archive \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":[""],"id":1}' ``` ``` # Mainnet archive curl -s -X POST https://mainnet.rpc.nexus.xyz/archive \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"trace_block","params":["latest"],"id":1}' ``` Standard methods (`eth_blockNumber`, `eth_chainId`, etc.) are rejected on the `/archive` path — use the default endpoint for those. The archive node is not directly addressable. All requests route through the gateway. ### Error Codes | Code | Message | Cause | | -------- | ---------------- | ------------------------------------------------------------------------- | | `-32700` | Parse error | Malformed JSON in request body | | `-32600` | Invalid request | Missing required JSON-RPC fields | | `-32601` | Method not found | Method not supported or called on wrong endpoint (e.g., `debug_*` on `/`) | | `-32602` | Invalid params | Wrong number or type of parameters | | `-32603` | Internal error | Server-side failure | | `-32005` | Limit exceeded | Payload too large or batch size exceeded | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/network/building-on-nexus/endpoints.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.