JSON-RPC API

For complete read-only examples, follow Query the EVM or the Python Quickstart. Use Debug Transactions to work from a failed receipt to a reproducible diagnosis.

Architecture Overview

Paxeer provides a comprehensive RPC interface that combines standard Ethereum JSON-RPC compatibility with Paxeer-specific enhancements. The API includes these namespaces:

Namespace Summary

eth_ Endpoints

The eth_ prefixed endpoints provide a pure EVM-compatible view:

• EVM-only: Only process and return EVM transactions
• Ethereum tooling: Use ethers.js, viem, web3.js, Hardhat, and Foundry with the method-specific differences below
• Transaction view: EVM transactions and their emitted logs
• Method contracts: Standard request shapes with documented Paxeer differences

Key eth_ Methods

• eth_blockNumber
• eth_getBlockByNumber, eth_getBlockByHash
• eth_getTransactionByHash
• eth_getTransactionReceipt
• eth_getLogs
• eth_call, eth_estimateGas
• eth_sendRawTransaction
• eth_getBalance, eth_getCode

pax_ Endpoints

The pax_ prefixed endpoints provide an enhanced view that includes both EVM and relevant Cosmos transactions:

• Synthetic transactions: Cosmos events (CW20, CW721) exposed as EVM logs
• Full visibility: See both EVM and Cosmos activity
• Cross-chain events: Index pointer contracts and token transfers
• Trace filtering: Variants to exclude pre-state check failures

Synthetic Transaction Endpoints

These endpoints bridge Cosmos and EVM by exposing Cosmos-native events as EVM-compatible logs:

• pax_getLogs — Enhanced eth_getLogs with synthetic logs
• pax_getFilterLogs — Enhanced eth_getFilterLogs with synthetic logs
• pax_getBlockByNumber, pax_getBlockByHash — Include synthetic transactions
• pax_getBlockReceipts — Include receipts for synthetic transactions

Trace Failure Filtering

A block can contain transactions that fail before EVM execution, including nonce or balance checks. Use the following endpoints when you need a view that excludes those failures:

• pax_traceBlockByNumberExcludeTraceFail
• pax_traceBlockByHashExcludeTraceFail
• pax_getTransactionReceiptExcludeTraceFail
• pax_getBlockByNumberExcludeTraceFail
• pax_getBlockByHashExcludeTraceFail

pax2_ Endpoints (Bank Transfers)

The pax2_ namespace exposes the same block shape as pax_ but includes bank transfers in block payloads:

• Seven methods: block, block receipts, transaction counts, ExcludeTraceFail variants
• No pax2_ transaction or filter API
• HTTP only (not WebSocket)

Legacy API Gating

Both pax_* and pax2_* are legacy APIs gated by [evm].enabled_legacy_pax_apis in app.toml:

• Deprecated: Scheduled for removal
• Allow list: Only methods in the config array are enabled
• Default config: Three pax_* address/Cosmos helpers pre-filled
• Docker localnet: Enables all gated methods except pax_sign
• Disabled response: JSON-RPC error -32601, message explains deprecation

Transaction Index Mismatches

Important: Transaction indices differ between eth_ and pax_ endpoints.

Example

Consider a block with:

1. EVM Transaction 1
2. Cosmos Transaction 1
3. EVM Transaction 2

eth_getBlockReceipts

Returns only EVM transactions with sequential indices:

• EVM Transaction 1 (tx index: 0)
• EVM Transaction 2 (tx index: 1)

pax_getBlockReceipts

Returns all transactions (EVM + Cosmos) with sequential indices:

• EVM Transaction 1 (tx index: 0)
• Cosmos Transaction 1 (tx index: 1)
• EVM Transaction 2 (tx index: 2)

Receipts and Logs

• EVM-originating: Synthetic events included in both eth_getLogs and eth_getTransactionReceipt
• Cosmos-originating: Synthetic events not in eth_ methods; use pax_getLogs and pax_getBlockReceipts
• logIndex values: Strictly increasing and consistent within each namespace

Best Practice

• Use the same endpoint consistently within your application
• Account for index differences when switching endpoints
• Prefer transaction hashes over indices (hashes are consistent across endpoints)

debug_ Endpoints

Use debug_trace* methods to inspect historical execution:

• Inspect failed call frames and returned error data
• Compare gas consumption across calls and opcodes
• Review the state accesses and changes exposed by the selected tracer

Key debug_ Methods

• debug_traceBlockByNumber, debug_traceBlockByHash
• debug_traceTransaction
• debug_traceCall

Paxeer RPC Distinctions

Paxeer's RPC deviates from Ethereum in several areas:

Block Tags and Pending Nonces

• Committed-state reads resolve supported latest, safe, and finalized tags through the RPC publication watermarks
• Pending account nonces have a separate path: eth_getTransactionCount(address, "pending") uses the mempool’s next nonce or a configured proxy
• Track submitted hashes and use the pending nonce when coordinating multiple transactions from one account

No Uncle Blocks

• Paxeer finalizes blocks through BFT consensus and does not produce Ethereum uncle blocks
• Uncle-related endpoints are not supported

Storage Proof Format

• eth_getProof is implemented for proof-capable stores
• The result contains address, hexValues, and IAVL storageProof operations; it is not Ethereum’s Merkle Patricia account-proof shape
• Use an IAVL proof verifier and an endpoint retaining proof-capable state at the requested height

No Proof-of-Work

• eth_mining, eth_hashrate not supported
• Paxeer uses BFT consensus, not PoW

No Blobs

• EIP-4844 blob transactions not supported
• eth_blobBaseFee returns error -32000: "blobs not supported on this chain"

See Unsupported Methods for the complete list.

Consistent Historical Reads

Pin related reads to one block number and retain its block hash with indexed data. Use a provider with the historical state your application needs, and keep the same namespace when reading blocks, receipts, and logs.

WebSocket Support

Paxeer RPC supports WebSocket for:

• eth_subscribe for newHeads and logs
• Pending-transaction subscriptions are not implemented by SubscriptionAPI
• eth_unsubscribe

Legacy pax2_* endpoints are HTTP-only.