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
- Standard Ethereum Endpoints
- Sei Custom Endpoints
- Understanding Synthetic Transactions
- Use Case Examples
- Performance Considerations
- Error Handling
- Advanced Topics
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 identifierjsonrpc
: 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 requestjsonrpc
: always “2.0”result
: an object that differs from endpoint to endpointerror
(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:
Type | Description |
---|---|
string | The hex-encoding of the signed transaction. |
- Result:
Type | Description |
---|---|
string | The transaction hash. |
sei_associate
Sends a transaction to establish association between the signer’s Sei address and EVM address on-chain.
- Parameters:
Type | Description |
---|---|
object | A 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:
Type | Description |
---|---|
string | The transaction hash. |
- Result:
Type | Description |
---|---|
object | The receipt object . |
eth_getTransactionByBlockNumberAndIndex
Gets transaction by the block number and the index of the transaction in the block
- Parameters:
Type | Description |
---|---|
string | The 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. |
string | The transaction index as a hexadecimal number. |
- Result:
Type | Description |
---|---|
object | The transaction details . |
eth_getTransactionByBlockHashAndIndex
Gets transaction by the block hash and the index of the transaction in the block.
- Parameters:
Type | Description |
---|---|
string | The block hash. |
string | The transaction index as a hexadecimal number. |
- Result:
Type | Description |
---|---|
object | The transaction details . |
eth_getTransactionByHash
Gets transaction by the transaction hash.
- Parameters:
Type | Description |
---|---|
string | The transaction hash. |
- Result:
Type | Description |
---|---|
object | The 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:
Type | Description |
---|---|
string | The address to look up. |
string | The 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:
Type | Description |
---|---|
string | The hexadecimal form of the number of transactions. |
eth_getBalance
Gets the balance in wei (i.e. 10^-12 usei) of the account
- Parameters:
Type | Description |
---|---|
string | The address to look up. |
string | The 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:
Type | Description |
---|---|
string | The hexadecimal form of the wei balance. |
eth_getCode
Gets EVM code stored at the account address
- Parameters:
Type | Description |
---|---|
string | The address to look up. |
string | The 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:
Type | Description |
---|---|
string | The hexadecimal form of the code binary. |
eth_getStorageAt
Gets value at given key of the account
- Parameters:
Type | Description |
---|---|
string | The address to look up. |
string | The hexadecimal form of the key. |
string | The 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:
Type | Description |
---|---|
string | The 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:
Type | Description |
---|---|
string | The address to look up. |
string[] | The hexadecimal form of the keys. |
string | The 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:
Type | Description |
---|---|
object | An 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:
Endpoint | Description |
---|---|
sei_getFilterLogs | Like eth_getFilterLogs but includes synthetic logs from Cosmos events |
sei_getLogs | Like eth_getLogs but includes synthetic logs from Cosmos events |
sei_getBlockByNumber | Like eth_getBlockByNumber but includes synthetic transactions |
sei_getBlockByHash | Like 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 addressestopics
: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:
Endpoint | Description |
---|---|
sei_traceBlockByNumberExcludeTraceFail | Like debug_traceBlockByNumber but excludes traces that panic |
sei_traceBlockByHashExcludeTraceFail | Like debug_traceBlockByHash but excludes traces that panic |
sei_getTransactionReceiptExcludeTraceFail | Like eth_getTransactionReceipt but excludes receipts for failed traces |
sei_getBlockByNumberExcludeTraceFail | Like eth_getBlockByNumber but excludes transactions with failed traces |
sei_getBlockByHashExcludeTraceFail | Like 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:
Endpoint | Description |
---|---|
sei_queryStorage | Advanced storage querying with pagination and filtering |
sei_queryEvents | Enhanced event querying across EVM and Cosmos |
sei_queryState | Direct querying of account and contract state |
Cross-VM Operations
These endpoints facilitate operations that span both the EVM and Cosmos environments:
Endpoint | Description |
---|---|
sei_callCosmos | Allows calling Cosmos-SDK modules from the EVM RPC |
sei_estimateCosmosGas | Estimates gas for cross-VM operations |
sei_getCosmosAddress | Retrieves 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:
- Cosmos modules interact with pointer contracts
- Token transfers occur between the two environments
- 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:
Code | Message | Description |
---|---|---|
-32000 | Invalid input | Generic input error |
-32001 | Resource not found | The requested resource was not found |
-32002 | Resource unavailable | The resource exists but is not available |
-32003 | Transaction rejected | The transaction was rejected |
-32004 | Method not supported | The method is not supported |
-32005 | Limit exceeded | Request exceeds defined limit |
-32006 | Version not supported | JSON-RPC version is not supported |
-32500 | Cross-VM error | Error in cross-VM operation |
-32501 | Synthetic tx error | Error 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');
}
});