JSON-RPC API

CelesChain exposes a JSON-RPC 2.0 interface that is fully EVM compatible. Any tooling that works with Ethereum JSON-RPC (for example, ethers.js, web3.js, Hardhat, Foundry) can be used to interact with CelesChain with little or no change.

Base RPC endpoints for examples in this page:

• HTTPS RPC testnet: https://rpc-testnet.celeschain.xyz

• WebSocket RPC testnet: wss://rpc-testnet.celeschain.xyz

This section documents common RPC methods, Celes specific behaviors, examples, and best practices for production use.

---

General notes

• All numeric values follow Ethereum conventions: hex string with 0x prefix.

• Block identifiers: latest, earliest, pending, or a hex block number.

• Gas price semantics: Celes uses a bridged native gas token model. eth_gasPrice, eth_feeHistory and eth_maxPriorityFeePerGas return estimates denominated in the chain native gas unit. When calculating gas for a cross-environment flow, account for Base settlement costs separately.

• EVM compatibility: full support for standard eth_* methods plus a small set of extended methods useful for rollup and debugging scenarios.

• Subscriptions: supported over WebSocket with eth_subscribe and eth_unsubscribe. Use WS for streaming new heads, logs and pending transactions.

---

Common ETH methods

eth_chainId

Returns the chain ID.

Request

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

Response

{ "jsonrpc":"2.0", "id":1, "result":"0x56f1" }  // example hex chain id

---

eth_blockNumber

Returns the latest block number.

Request

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

Response

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

---

eth_getBlockByNumber

Get block by number. fullTransactionObjects true returns transaction objects, false returns tx hashes.

Request

{ "jsonrpc":"2.0", "method":"eth_getBlockByNumber", "params":["latest", true], "id":1 }

Response

{
  "jsonrpc":"2.0",
  "id":1,
  "result": {
    "number":"0x10d4f",
    "hash":"0xabc...",
    "parentHash":"0xdef...",
    "transactions": [ { "hash":"0x...", "from":"0x...", ... } ]
  }
}

---

eth_getTransactionByHash

Get transaction by hash.

Request

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

Response

{ "jsonrpc":"2.0", "id":1, "result": { "hash":"0xabc...", "from":"0x...", "to":"0x...", "blockNumber":"0x..." } }

---

eth_getTransactionReceipt

Get transaction receipt.

Request

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

Response

{
  "jsonrpc":"2.0",
  "id":1,
  "result": {
    "transactionHash":"0xabc...",
    "blockNumber":"0x10d4f",
    "status":"0x1",
    "logs": [ ... ]
  }
}

---

eth_call

Execute a read only call without broadcasting a transaction.

Request

{
  "jsonrpc":"2.0",
  "method":"eth_call",
  "params":[ { "to":"0xContract", "data":"0x06fdde03" }, "latest" ],
  "id":1
}

Response

{ "jsonrpc":"2.0", "id":1, "result":"0x000000000..." }

---

eth_sendRawTransaction

Submit a signed raw transaction to the network.

Request

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

Response

{ "jsonrpc":"2.0", "id":1, "result":"0x1234...txhash" }

---

eth_estimateGas

Estimate gas for a transaction. Always run before preparing gas settings.

Request

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

Response

{ "jsonrpc":"2.0", "id":1, "result":"0x5208" }  // example gas estimate

---

eth_gasPrice and eth_maxPriorityFeePerGas

Return gas price and priority fee estimates. On CelesChain these reflect the bridged gas token economics.

Request

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

Response

{ "jsonrpc":"2.0", "id":1, "result":"0x2540be400" } // wei

Note

• If your transaction must be posted to Base as part of settlement flows, estimate additional settlement cost separately.

---

Extended and rollup specific methods

CelesChain exposes a small set of extra methods useful for rollup operations and debugging. These are implemented where applicable; behavior follows the semantics used by many modular rollup stacks.

eth_getBlockReceipts

Return transaction receipts for all transactions in a block.

Request

{ "jsonrpc":"2.0", "method":"eth_getBlockReceipts", "params":["0x10d4f"], "id":1 }

Response

{
  "jsonrpc":"2.0",
  "id":1,
  "result":[ { "transactionHash":"0x...", "status":"0x1" }, ... ]
}

Use case

• Useful for services that need all receipts for a block for indexing or faster reorg handling.

---

eth_getAccount

Return enriched account information for rollup scenarios.

Request

{ "jsonrpc":"2.0", "method":"eth_getAccount", "params":["0xabc...", "latest"], "id":1 }

Response

{
  "jsonrpc":"2.0",
  "id":1,
  "result": {
    "balance":"0xde0b6b3a7640000",
    "nonce":"0xa",
    "codeHash":"0x...",
    "storageRoot":"0x..."
  }
}

Use case

• Quick account snapshot for explorers and indexing services.

---

Debug trace methods

CelesChain supports debug tracing endpoints for deep inspection.

• debug_traceTransaction replay a single transaction with a tracer.

• debug_traceBlockByNumber and debug_traceBlockByHash trace all transactions in a block.

• trace_filter supports trace filtering over a block range.

These methods require elevated node privileges on some providers. Use them for detailed diagnostics, MEV research, and analytics.

Example

{
  "jsonrpc":"2.0",
  "method":"debug_traceTransaction",
  "params":["0xabc...", {"tracer":"callTracer"}],
  "id":1
}

---

Subscription methods (WebSocket)

Use WebSocket endpoint for real time streaming.

eth_subscribe

Request

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

Response

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

When a new head arrives, you will receive push messages with the block header.

eth_unsubscribe

Request

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

Response

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

---

Example integrations

cURL: get latest block number

curl -X POST https://rpc-testnet.celeschain.xyz \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

ethers.js: connect and get chain id

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://rpc-testnet.celeschain.xyz");
const chainId = await provider.send("eth_chainId", []);
console.log("chainId", chainId);

ethers.js: subscribe to new heads (via WebSocket)

import { ethers } from "ethers";

const ws = new ethers.WebSocketProvider("wss://rpc-testnet.celeschain.xyz");
ws.on("block", (n) => {
  console.log("new block", n);
});

Send raw tx with curl

curl -X POST https://rpc-testnet.celeschain.xyz\
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_sendRawTransaction","params":["0xf86b..."]}'

---

Error handling and response codes

• JSON-RPC error object will follow the 2.0 spec. Inspect error.code and error.message.

• Common error causes:

  • Invalid parameters.

  • Insufficient gas or funds.

  • Node not synced.

  • Rate limit exceeded.

• When you receive a transient error, implement exponential backoff and retry for idempotent operations. For non idempotent operations such as eth_sendRawTransaction, do not retry blindly without checking the transaction hash first.

---

Best practices and recommendations

• Use WebSocket subscriptions for real time monitoring and notifications.

• Batch calls using eth_batch semantics in your client where supported. If your provider does not support batching natively, run parallel RPC requests carefully.

• Use eth_estimateGas before sending transactions. Then add a safety buffer to the gas limit.

• For front end applications, prefer eth_call for read only queries to avoid paying gas and keep UI responsive.

• When indexing blocks, prefer eth_getBlockReceipts and eth_getLogs for efficient retrieval of receipts and logs.

• Account for settlement cost to Base when designing user flows that require posting checkpoints or cross-chain settlement.

• Use idempotent nonce management for programmatic transaction submission. When possible, use the account nonce from eth_getTransactionCount with pending to handle pending transactions.

---

Rate limits and usage

• Providers may enforce rate limits on public RPC endpoints. If you operate production workloads, host a dedicated node or request an enterprise endpoint.

• For heavy indexing or analytics work, use archived node endpoints or a specialized indexing service rather than the public RPC.

---

Appendix: common parameters and formats

• Hex integers: 0x prefixed, no leading zeros unless zero.

• Addresses: 0x prefixed, 20 bytes lowercase checksum optional.

• Bytes data: 0x prefixed hex.

• Block numbers: "latest", "earliest", "pending" or hex number string.