Skip to Content
EVMRPC Reference

RPC Reference Guide

Sei provides comprehensive RPC (Remote Procedure Call) support for its EVM implementation, including both standard Ethereum JSON-RPC endpoints and Sei-specific custom extensions that enhance functionality for developers.

Table of Contents

Overview

Sei supports the Ethereum JSON-RPC API with some Sei-specific extensions to support cross-VM operations, synthetic transactions, and other advanced features.

All endpoints follow the standard JSON-RPC format:

JSON-RPC Request/Response Format

Request Format

  • HTTP method: always “GET
  • Header: accept: application/json
  • Header: content-type: application/json
  • Body (JSON):
    • id: an arbitrary string identifier
    • jsonrpc: always “2.0”
    • method: endpoint name (e.g. “eth_sendRawTransaction”)
    • params: an array that differs from endpoint to endpoint

Response Format

  • Body (JSON):
    • id: the same identifier in request
    • jsonrpc: always “2.0”
    • result: an object that differs from endpoint to endpoint
    • error (if applicable): error details

Standard Ethereum Endpoints

Sei supports all standard Ethereum JSON-RPC endpoints, organized into the following categories. Click on each category to view the available endpoints and their documentation.

Send Transactions

These endpoints allow you to send transactions to the Sei network.

View Send Transaction Endpoints

eth_sendRawTransaction

Sends a signed transaction.

  • Parameters:
TypeDescription
stringThe hex-encoding of the signed transaction.
  • Result:
TypeDescription
stringThe transaction hash.

sei_associate

Sends a transaction to establish association between the signer’s Sei address and EVM address on-chain.

  • Parameters:
TypeDescription
objectA custom object containing a string message and the v, r, s of the signed message.

Object Schema:

{ custom_message: // Any string message r: // The R-part of the signature over the Keccak256 hash of the custom message. s: // The S-part of the signature over the Keccak256 hash of the custom message. v: // The V-part of the signature over the Keccak256 hash of the custom message. }

Transaction Lookup

These endpoints allow you to find transaction details.

View Transaction Lookup Endpoints

eth_getTransactionReceipt

Gets the receipt of a sent transaction

  • Parameters:
TypeDescription
stringThe transaction hash.
  • Result:
TypeDescription
objectThe receipt object.

eth_getTransactionByBlockNumberAndIndex

Gets transaction by the block number and the index of the transaction in the block

  • Parameters:
TypeDescription
stringThe block number, which can either be a hexadecimal number, or one of “safe”, “finalized”, “latest”, or “earliest”. Note that “safe”, “finalized”, and “latest” mean the same thing on Sei due to its instant finality.
stringThe transaction index as a hexadecimal number.
  • Result:
TypeDescription
objectThe transaction details.

eth_getTransactionByBlockHashAndIndex

Gets transaction by the block hash and the index of the transaction in the block.

  • Parameters:
TypeDescription
stringThe block hash.
stringThe transaction index as a hexadecimal number.
  • Result:
TypeDescription
objectThe transaction details.

eth_getTransactionByHash

Gets transaction by the transaction hash.

  • Parameters:
TypeDescription
stringThe transaction hash.
  • Result:
TypeDescription
objectThe transaction details.

Account Information

These endpoints allow you to query account-related information.

View Account Information Endpoints

eth_getTransactionCount

Gets the number of transactions sent by the account

  • Parameters:
TypeDescription
stringThe address to look up.
stringThe block number, which can either be a hexadecimal number, or one of “safe”, “finalized”, “latest”, or “earliest”. Note that “safe”, “finalized”, and “latest” mean the same thing on Sei due to its instant finality.
  • Result:
TypeDescription
stringThe hexadecimal form of the number of transactions.

eth_getBalance

Gets the balance in wei (i.e. 10^-12 usei) of the account

  • Parameters:
TypeDescription
stringThe address to look up.
stringThe block number or hash, which can be one of 1. block hash, 2. hexadecimal block number, 3. one of “safe”, “finalized”, “latest”, “pending”, or “earliest”. Note that “safe”, “finalized”, and “latest” mean the same thing on Sei due to its instant finality.
  • Result:
TypeDescription
stringThe hexadecimal form of the wei balance.

eth_getCode

Gets EVM code stored at the account address

  • Parameters:
TypeDescription
stringThe address to look up.
stringThe block number or hash, which can be one of 1. block hash, 2. hexadecimal block number, 3. one of “safe”, “finalized”, “latest”, “pending”, or “earliest”. Note that “safe”, “finalized”, and “latest” mean the same thing on Sei due to its instant finality.
  • Result:
TypeDescription
stringThe hexadecimal form of the code binary.

eth_getStorageAt

Gets value at given key of the account

  • Parameters:
TypeDescription
stringThe address to look up.
stringThe hexadecimal form of the key.
stringThe block number or hash, which can be one of 1. block hash, 2. hexadecimal block number, 3. one of “safe”, “finalized”, “latest”, “pending”, or “earliest”. Note that “safe”, “finalized”, and “latest” mean the same thing on Sei due to its instant finality.
  • Result:
TypeDescription
stringThe hexadecimal form of the storage value.

eth_getProof

Gets the IAVL proof (note: not a MPT proof) of the given keys for an account.

  • Parameters:
TypeDescription
stringThe address to look up.
string[]The hexadecimal form of the keys.
stringThe block number or hash, which can be one of 1. block hash, 2. hexadecimal block number, 3. one of “safe”, “finalized”, “latest”, “pending”, or “earliest”. Note that “safe”, “finalized”, and “latest” mean the same thing on Sei due to its instant finality.
  • Result:
TypeDescription
objectAn object with data from the IAVL proof.

Object Schema:

{ address: // The requested address. hexValues: // An array of the hexdecimal form of the values at the given keys. storageProof: // An array of storage proofs. }

Note: The storage proofs in the return object follow this format.

Other Standard Endpoint Categories

Block Information

Endpoints for retrieving block data and related information.

[View complete list of Block Information endpoints]

Blockchain Information

Endpoints for querying general blockchain data.

[View complete list of Blockchain Information endpoints]

Filter Endpoints

Endpoints for creating and managing event filters.

Note that log filters are subject to the following limits by default:

  • 10000 logs in one response if block range is open-ended
  • 2000 blocks to query over if block range is close-ended

[View complete list of Filter endpoints]

Simulation Endpoints

Endpoints for simulating contract execution.

[View complete list of Simulation endpoints]

Debugging Endpoints

Endpoints for debugging transactions and blocks.

[View complete list of Debugging endpoints]

Sei Custom Endpoints

Sei extends the standard Ethereum JSON-RPC API with custom endpoints that enhance functionality for developers. These extensions enable better handling of cross-VM interactions, synthetic transactions, improved error reporting, and other Sei-specific features.

Synthetic Transaction Support

These endpoints provide support for synthetic transactions, which represent activity from the Cosmos SDK modules in a way that is EVM client compatible:

EndpointDescription
sei_getFilterLogsLike eth_getFilterLogs but includes synthetic logs from Cosmos events
sei_getLogsLike eth_getLogs but includes synthetic logs from Cosmos events
sei_getBlockByNumberLike eth_getBlockByNumber but includes synthetic transactions
sei_getBlockByHashLike eth_getBlockByHash but includes synthetic transactions

View Synthetic Transaction Support API Details

sei_getFilterLogs

Returns an array of logs for a filter, including synthetic logs from Cosmos events.

Parameters

  • QUANTITY - The filter ID

Returns

  • Array - Array of log objects, including synthetic logs

Example Request

{ "jsonrpc": "2.0", "method": "sei_getFilterLogs", "params": ["0x16"], "id": 1 }

Example Response

{ "jsonrpc": "2.0", "id": 1, "result": [ { "address": "0x37dc71366ec655093b9930bc816e16e6b587f968", "blockHash": "0xf9e709...", "blockNumber": "0x5daf3b", "data": "0x0000000000000000000000000000000000000000000000000000000000000001", "logIndex": "0x0", "removed": false, "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"], "transactionHash": "0x5490b7...", "transactionIndex": "0x0", "synthetic": true } // ... more logs ] }

sei_getLogs

Returns an array of logs matching a given filter, including synthetic logs.

Parameters

  • Object - Filter options object with:
    • fromBlock: QUANTITY|TAG - Block number or “latest”, “earliest” or “pending”
    • toBlock: QUANTITY|TAG - Block number or “latest”, “earliest” or “pending”
    • address: DATA|Array - Contract address or array of addresses
    • topics: Array - Array of topic specifiers

Returns

  • Array - Array of log objects, including synthetic logs

Example Request

{ "jsonrpc": "2.0", "method": "sei_getLogs", "params": [ { "fromBlock": "0x1", "toBlock": "latest", "address": "0x37dc71366ec655093b9930bc816e16e6b587f968", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] } ], "id": 1 }

Tracing Failure Exclusion

These endpoints provide variants of standard Ethereum endpoints that exclude transactions that fail tracing:

EndpointDescription
sei_traceBlockByNumberExcludeTraceFailLike debug_traceBlockByNumber but excludes traces that panic
sei_traceBlockByHashExcludeTraceFailLike debug_traceBlockByHash but excludes traces that panic
sei_getTransactionReceiptExcludeTraceFailLike eth_getTransactionReceipt but excludes receipts for failed traces
sei_getBlockByNumberExcludeTraceFailLike eth_getBlockByNumber but excludes transactions with failed traces
sei_getBlockByHashExcludeTraceFailLike eth_getBlockByHash but excludes transactions with failed traces

View Tracing Failure Exclusion API Details

sei_traceBlockByNumberExcludeTraceFail

Traces all transactions in a block, excluding those that fail tracing.

Parameters

  • QUANTITY|TAG - Integer block number or “latest”, “earliest” or “pending”
  • Object - Trace options

Returns

  • Array - Array of trace results for successful traces

Example Request

{ "jsonrpc": "2.0", "method": "sei_traceBlockByNumberExcludeTraceFail", "params": [ "0x5BAD55", { "tracer": "callTracer" } ], "id": 1 }

sei_getTransactionReceiptExcludeTraceFail

Returns the transaction receipt for a given hash, but returns null for transactions that fail tracing.

Parameters

  • DATA - Transaction hash

Returns

  • Object|null - Transaction receipt object or null if transaction fails tracing

Example Request

{ "jsonrpc": "2.0", "method": "sei_getTransactionReceiptExcludeTraceFail", "params": ["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"], "id": 1 }

Other Sei Custom Endpoint Categories

Enhanced Querying

These endpoints provide enhanced querying capabilities:

EndpointDescription
sei_queryStorageAdvanced storage querying with pagination and filtering
sei_queryEventsEnhanced event querying across EVM and Cosmos
sei_queryStateDirect querying of account and contract state

Cross-VM Operations

These endpoints facilitate operations that span both the EVM and Cosmos environments:

EndpointDescription
sei_callCosmosAllows calling Cosmos-SDK modules from the EVM RPC
sei_estimateCosmosGasEstimates gas for cross-VM operations
sei_getCosmosAddressRetrieves the corresponding Cosmos address for an Ethereum address

[View complete Cross-VM Operations API details]

Understanding Synthetic Transactions

Synthetic transactions are a key concept in Sei’s cross-VM architecture. They are representations of Cosmos events on the EVM side and are generated when:

  1. Cosmos modules interact with pointer contracts
  2. Token transfers occur between the two environments
  3. Cross-VM events need to be represented in the EVM execution environment

Structure of Synthetic Transactions

Synthetic transactions have the following structure:

{ "hash": "0xsyntheticTransactionHash...", "from": "0xderivedfromCosmWasmAddress...", "to": "0xpointerContractAddress...", "value": "0x0", "input": "0xencoded_function_data...", "v": "0x0", "r": "0x0", "s": "0x0", "synthetic": true }

The synthetic field is a boolean indicator that the underlying transaction was a Cosmos event.

Use Case Examples

Here are practical examples of how to use Sei’s RPC endpoints for common tasks:

Tracking Cross-VM Token Transfers

To track token transfers across both EVM and Cosmos environments:

const Web3 = require('web3'); const web3 = new Web3('https://evm-rpc.sei-apis.com'); // Create a filter for Transfer events from a token contract async function trackCrossVMTransfers(tokenAddress) { // Topic0 is the event signature for Transfer(address,address,uint256) const transferEventSignature = web3.utils.sha3('Transfer(address,address,uint256)'); // Get logs including synthetic logs from Cosmos const logs = await web3.eth.send('sei_getLogs', [ { fromBlock: 'latest', toBlock: 'latest', address: tokenAddress, topics: [transferEventSignature] } ]); // Process logs for (const log of logs) { const isSynthetic = log.synthetic === true; console.log(`Transfer detected: ${isSynthetic ? 'Cross-VM' : 'EVM-only'}`); console.log(`From: ${web3.eth.abi.decodeParameter('address', log.topics[1])}`); console.log(`To: ${web3.eth.abi.decodeParameter('address', log.topics[2])}`); console.log(`Value: ${web3.eth.abi.decodeParameter('uint256', log.data)}`); } }

View Additional Use Case Examples

Block Explorer with Trace Failure Exclusion

When building a block explorer, you can use the trace failure exclusion endpoints to show only valid transactions:

const Web3 = require('web3'); const web3 = new Web3('https://evm-rpc.sei-apis.com'); async function getCleanBlock(blockNumber) { // Get block without failed trace transactions const block = await web3.eth.send('sei_getBlockByNumberExcludeTraceFail', [ web3.utils.toHex(blockNumber), true // include transaction details ]); // For each transaction, get a receipt that's guaranteed to be from a successful trace const receipts = await Promise.all(block.transactions.map((tx) => web3.eth.send('sei_getTransactionReceiptExcludeTraceFail', [tx.hash]))); return { block, receipts }; }

Querying CosmWasm State from EVM dApps

To query the CosmWasm contract state from an EVM dApp:

const Web3 = require('web3'); const web3 = new Web3('https://evm-rpc.sei-apis.com'); async function queryCWToken(cwTokenAddress) { // Get token info from Cosmos-SDK const tokenInfo = await web3.eth.send('sei_callCosmos', [ { cosmosAddress: cwTokenAddress, message: { token_info: {} } } ]); console.log(`Token Name: ${tokenInfo.name}`); console.log(`Token Symbol: ${tokenInfo.symbol}`); console.log(`Token Decimals: ${tokenInfo.decimals}`); console.log(`Token Total Supply: ${tokenInfo.total_supply}`); return tokenInfo; }

Retrieving Synthetic Transactions in a Block

To get all transactions in a block, including synthetic ones:

const Web3 = require('web3'); const web3 = new Web3('https://evm-rpc.sei-apis.com'); async function getBlockWithSyntheticTxs(blockNumber) { const block = await web3.eth.send('sei_getBlockByNumber', [ web3.utils.toHex(blockNumber), true // include transaction details ]); // Separate regular and synthetic transactions const regularTxs = block.transactions.filter((tx) => !tx.synthetic); const syntheticTxs = block.transactions.filter((tx) => tx.synthetic); console.log(`Block ${blockNumber} has:`); console.log(`- ${regularTxs.length} regular transactions`); console.log(`- ${syntheticTxs.length} synthetic transactions`); return { regularTxs, syntheticTxs }; }

Performance Considerations

When using Sei’s custom endpoints, consider these performance recommendations:

Optimizing Log Queries

  • Use specific topic filters to narrow down results
  • Limit block ranges to manageable chunks (e.g., 1,000 blocks at a time)
  • Consider using event subscriptions for real-time updates instead of polling

Handling Synthetic Transactions

  • Synthetic [Cosmos] transactions may have higher latency in appearing than EVM transactions
  • Consider slightly longer polling intervals when tracking synthetic data
  • Implement retry logic for recent synthetic transactions that might not be immediately available

Trace Failure Exclusion

  • The exclusion endpoints generally perform additional computation, so use them when needed
  • For high-volume applications, consider caching results

Error Handling

Sei’s custom endpoints return standard Ethereum JSON-RPC errors plus some additional error codes:

CodeMessageDescription
-32000Invalid inputGeneric input error
-32001Resource not foundThe requested resource was not found
-32002Resource unavailableThe resource exists but is not available
-32003Transaction rejectedThe transaction was rejected
-32004Method not supportedThe method is not supported
-32005Limit exceededRequest exceeds defined limit
-32006Version not supportedJSON-RPC version is not supported
-32500Cross-VM errorError in cross-VM operation
-32501Synthetic tx errorError processing synthetic transaction

Example error response:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32500, "message": "Cross-VM operation failed", "data": { "details": "CosmWasm contract execution reverted" } } }

Advanced Topics

Creating Custom Tracers with Sei Extensions

Sei supports custom JavaScript tracers with additional capabilities for cross-VM operations:

// Custom tracer with Sei extensions const customTracer = { // Standard tracer functions step: function (log, db) { /* ... */ }, fault: function (log, db) { /* ... */ }, result: function (ctx, db) { /* ... */ }, // Sei extension to process synthetic operations syntheticOp: function (op, db) { // Handle synthetic operations if (op.type === 'cwTransfer') { // Process CosmWasm transfer } return null; } }; // Convert to string for JSON-RPC call const tracerJson = JSON.stringify(customTracer); // Use the custom tracer web3.eth.send('debug_traceTransaction', [txHash, { tracer: tracerJson }]);

Subscribing to Synthetic Events

Sei supports subscriptions that include synthetic events:

const Web3 = require('web3'); const web3 = new Web3('wss://evm-rpc.sei-apis.com'); // Subscribe to all logs including synthetic ones const subscription = web3.eth.subscribe('sei_logs', { address: '0x123...', topics: [...] }, (error, log) => { if (!error) { console.log(`New log: ${log.transactionHash} (Synthetic: ${!!log.synthetic})`); } }); // Unsubscribe subscription.unsubscribe((error, success) => { if (success) { console.log('Successfully unsubscribed'); } });
Last updated on