Sei Node and RPC API: EVM and Cosmos Dual Runtime

Sei's Dual Runtime Model: Cosmos Consensus with an Embedded EVM

Sei is not a pure EVM chain. It is a Cosmos-SDK and Tendermint (CometBFT)-based Layer 1 that includes a built-in EVM execution environment. This means a single Sei node exposes two distinct API surfaces: an Ethereum-compatible JSON-RPC surface for EVM interactions, and a Cosmos/Tendermint surface for consensus and module-level queries. The Sei documentation describes the node operation and the seid binary, while the EVM documentation details the JSON-RPC surface.

The EVM surface answers questions about smart contracts, account balances, and EVM transactions using standard eth_* methods. The Cosmos surface answers questions about staking, governance, bank balances, and consensus state using Tendermint RPC and Cosmos gRPC/REST. Understanding which surface answers which question is essential for building reliable applications on Sei.

• EVM JSON-RPC: eth_chainId, eth_blockNumber, eth_getBalance, eth_call, eth_getLogs, eth_sendRawTransaction, and Sei-specific helpers like eth_getSei... methods.
• Cosmos/Tendermint RPC: consensus status, block queries, and transaction broadcasting over the node's consensus port.
• Cosmos gRPC/REST: module-level queries for bank, staking, governance, and other SDK modules.

Data-Access Layers: Self-Hosted Node, Hosted Provider, and Indexer

There are three primary ways to access Sei data. First, a self-hosted seid node serves the JSON-RPC API directly, giving you full control over data freshness and availability. Second, hosted providers run Sei nodes and expose the same JSON-RPC API, often with additional tooling and support. Third, Cosmos REST/gRPC endpoints and indexer/explorer layers provide module-level queries and aggregated data, such as transaction history and analytics.

A plain node efficiently serves recent and consensus data, but deep historical EVM state may require an archive node. The trade-off between self-hosting and using a hosted endpoint depends on your operational capacity and latency requirements. For a comparison of protocol styles, see JSON-RPC vs gRPC vs REST.

• Self-hosted: full control, but you manage upgrades, storage, and uptime.
• Hosted provider: managed infrastructure, often with archive support and higher availability.
• Indexer/explorer: aggregated views, useful for analytics but not for real-time state.

Key JSON-RPC Methods and Their Return Values

The EVM JSON-RPC surface on Sei follows the Ethereum JSON-RPC specification for standard methods. Identity methods like eth_chainId and web3_clientVersion return the chain ID and client version. Head methods like eth_blockNumber and eth_getBlockByNumber return the latest block number and block details. Account and contract state methods like eth_getBalance, eth_getTransactionCount, and eth_getCode return balances, nonces, and bytecode. eth_call executes read-only contract calls, eth_getLogs retrieves event logs for a block range, and eth_sendRawTransaction submits signed transactions.

Sei also provides Cosmos-style association queries, such as eth_getSei... helpers, which bridge EVM addresses and Cosmos accounts. These are specific to Sei and are documented in the Sei EVM documentation.

• eth_chainId: returns the EVM chain ID (e.g., 1329 for Sei mainnet).
• eth_blockNumber: returns the latest EVM block number.
• eth_getBalance: returns the balance of an address at a given block.
• eth_call: executes a read-only call against a contract.
• eth_getLogs: returns logs matching a filter for a block range.
• eth_sendRawTransaction: submits a signed raw transaction.

EVM Block Height vs Cosmos Block Height: Correctness-Critical Distinction

Sei separates Cosmos finality (CometBFT BFT finality) from EVM block production. The EVM block height and the Cosmos block height are different counters. When reconciling a transaction, you must deliberately choose the correct height source. For EVM transactions, use the EVM block number from eth_blockNumber or eth_getTransactionReceipt. For Cosmos transactions, use the Cosmos block height from the Tendermint RPC or Cosmos gRPC/REST.

Mixing these heights can lead to incorrect assumptions about transaction finality or data availability. Always verify which height a given API returns and document it in your integration.

• EVM height: increments with each EVM block, used by eth_* methods.
• Cosmos height: increments with each CometBFT block, used by Tendermint RPC and Cosmos modules.
• Reconciliation: map EVM transactions to their Cosmos block via the transaction receipt or indexer.

Running a Sei Node to Serve the JSON-RPC API

To run a Sei node, you use the seid binary. After initializing the node with seid init, you configure config.toml and app.toml. In app.toml, enable the JSON-RPC server and the evm_rpc section, including websocket support if needed. The node exposes multiple ports: the consensus port (default 26656), the Tendermint RPC port (26657), the Cosmos gRPC port (9090), the Cosmos REST port (1317), and the EVM JSON-RPC port (8545) with websocket (8546).

The Sei documentation provides detailed instructions for node operation and configuration. Ensure your node is fully synced before serving API requests.

seid init my-node --chain-id sei-chain
# Edit ~/.sei/config/app.toml to enable JSON-RPC and EVM RPC
# [json-rpc]
# enabled = true
# [evm_rpc]
# enabled = true
# ws-enabled = true
seid start

Verifying a Sei Endpoint: A Reproducible Procedure

To verify that a Sei endpoint is live and honest, perform a series of JSON-RPC calls. First, call eth_chainId and confirm it matches the expected Sei chain ID (e.g., 1329 for mainnet). Second, call eth_blockNumber twice and confirm the block number advances. Third, call eth_getBlockByNumber at the reported height and confirm the block hash is consistent. Fourth, call a Cosmos query for a known account to confirm the module surface works. This detects an endpoint that answers the wrong chain or is stalled.

Use the following Node.js script to automate these checks. Record your results in a table for comparison across endpoints.

const axios = require('axios');
const endpoint = 'https://your-sei-endpoint';

async function verify() {
  const chainId = await axios.post(endpoint, { jsonrpc: '2.0', method: 'eth_chainId', params: [], id: 1 });
  console.log('Chain ID:', chainId.data.result);
  const block1 = await axios.post(endpoint, { jsonrpc: '2.0', method: 'eth_blockNumber', params: [], id: 2 });
  await new Promise(r => setTimeout(r, 2000));
  const block2 = await axios.post(endpoint, { jsonrpc: '2.0', method: 'eth_blockNumber', params: [], id: 3 });
  console.log('Block numbers:', block1.data.result, block2.data.result);
  const block = await axios.post(endpoint, { jsonrpc: '2.0', method: 'eth_getBlockByNumber', params: [block1.data.result, false], id: 4 });
  console.log('Block hash:', block.data.result.hash);
}
verify();

Results Table: Measuring Endpoint Behavior Against Your Own Checks

Use the following table to record your measurements. Fill it in with the values you observe from your endpoint. This is a verified-by-the-reader method; no benchmark numbers are provided here.

Columns: Check, Expected, Observed, Pass/Fail. Rows: eth_chainId, eth_blockNumber (first call), eth_blockNumber (second call), eth_getBlockByNumber hash, Cosmos account query.

• eth_chainId: expected 1329 for Sei mainnet.
• eth_blockNumber: second call should be greater than first.
• eth_getBlockByNumber: hash should match the block at that height.
• Cosmos account query: should return the account's balance or sequence.

Self-Hosting vs Hosted Endpoint: Trade-offs and Selection

Self-hosting a Sei node gives you full control over data and privacy, but requires significant operational effort, including hardware, upgrades, and monitoring. A hosted endpoint, such as those offered by OnFinality, provides managed infrastructure with higher availability and often archive support. The choice depends on your team's capacity and your application's latency and reliability requirements.

For a list of supported networks and to choose an endpoint, see RPC pricing and API service. You can also explore adjacent protocol guides like HyperEVM JSON-RPC EVM methods guide and NEAR Protocol JSON-RPC API and node setup for comparison.

• Self-hosted: control, but you manage uptime and upgrades.
• Hosted: managed, often with archive and higher throughput.
• Hybrid: use hosted for production and self-hosted for development.

Limitations and Assumptions

This article assumes you are familiar with JSON-RPC and basic blockchain concepts. It does not cover every Sei-specific method or the full Cosmos SDK query surface. The exact port numbers and configuration options may vary by Sei version; always refer to the Sei documentation for the latest details. The verification procedure assumes a standard Sei node without custom modifications.

Provider-specific behavior, such as rate limits and supported methods, varies by provider. Always test against your chosen endpoint.

• Not all eth_* methods may be supported by every provider.
• Archive nodes are required for historical EVM state.
• Cosmos gRPC/REST endpoints may be disabled by default.

Troubleshooting Playbook for Sei Endpoints

Common issues include wrong chain ID, mismatched EVM vs Cosmos height, empty getLogs range, and websocket drops. For wrong chain ID, verify the endpoint's eth_chainId against the expected Sei chain ID. For height mismatch, ensure you are using the correct height source for your query. For empty getLogs, check that the block range is valid and that the contract emitted events. For websocket drops, implement reconnection logic and monitor connection health.

If the endpoint is stalled, compare block numbers over time. If the Cosmos surface fails, check that the gRPC/REST ports are enabled and accessible.

• Wrong chain ID: endpoint may be pointing to a different network.
• Height mismatch: use EVM height for EVM queries, Cosmos height for Cosmos queries.
• Empty getLogs: verify block range and contract events.
• Websocket drops: add heartbeat and reconnect logic.

Next Steps: Integrating Sei into Your Stack

After verifying your Sei endpoint, integrate it into your application using standard Ethereum libraries like ethers.js or web3.js for EVM interactions, and Cosmos SDK clients for module queries. For identity methods, see Ethereum node identity methods: chainId and clientVersion. For a broader overview of networks, visit the OnFinality Learn hub and explore Optimism as an example of another EVM-compatible network.

Consider using a hosted provider for production workloads to ensure reliability and archive access. Always monitor your endpoint's health and block height progression.

• Use ethers.js for EVM JSON-RPC calls.
• Use CosmJS for Cosmos gRPC/REST queries.
• Monitor block height and chain ID regularly.