Endpoints

For RPC URLs, chain IDs, wallet setup, and developer tooling configuration, see Developer Environment Setup.

RPC

Request Format

All requests use the standard JSON-RPC 2.0 envelope:

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

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

curl -s -X POST https://mainnet.rpc.nexus.xyz \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'

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

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

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

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

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

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

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

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)

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)

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

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

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":["<tx_hash>"],"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