Skip to content
Browse the documentation
Connectors

EVM chain (JSON-RPC)

What the EVM chain (JSON-RPC) connector reads, with which permissions, what it never touches, how it syncs, and the facts it produces.

Last changed Markdown versionllms.txt

Source module: app/connectors/evm_chain.py. Kind: facts only. Display name: "EVM chain (JSON-RPC)".

Purpose

Reads the record an agent that trades onchain cannot edit: the chain itself. For the wallets you name (a Coinbase CDP Server Wallet's EVM account, an AgentKit wallet, any EVM address) the connector reads the ERC-20 Transfer events that name them, pairs the legs of each transaction, and keys the facts on the wallet address. The Coinbase Agent Trade pack's place_wallet_swap workflow verifies an agent's onchain swap against these facts: the token sold, the token bought, the network, the amount sold, the amount bought within the slippage allowed, once, in the window.

Coinbase's wallet APIs sign and send; they do not list a wallet's past swaps (the CDP v2 reference offers account lists and current token balances, not transaction history, as read on 2026-11-12). The chain does. Nothing here needs a CDP key or a wallet secret: a JSON-RPC endpoint for the network is enough, and only read methods are used.

Auth and scopes

Item Value
Method A JSON-RPC endpoint URL over https (your node provider's URL, which usually carries a key in its path or query, or a public endpoint). Stored encrypted; requests go to the URL exactly as given
Credentials stored (encrypted) rpc_url; non-secret settings network (CAIP-2, eip155:8453 is Base, eip155:1 Ethereum), wallets (comma-separated addresses), optional start_block
Least-privilege permissions None to grant: the methods used are reads any endpoint serves (eth_chainId, eth_blockNumber, eth_getLogs, eth_getBlockByNumber, eth_getTransactionByHash, eth_call for decimals()). Nothing is signed, nothing is sent, no private key or wallet secret is ever asked for
Connection test eth_chainId must equal the network's chain id (an endpoint for another chain is refused with the reason), then eth_blockNumber

Fields pulled and why

Call Fields Used for
eth_getLogs with topics [Transfer, [wallets]] and [Transfer, null, [wallets]], 2 000 blocks per call address (token contract), topics[1] from, topics[2] to, data (amount), transactionHash, blockNumber, logIndex, removed Every leg the wallet sent or received; a log the node marks removed (reorganised away) is skipped
eth_getBlockByNumber(block, false) timestamp The fact's time (the block's), and the watermark
eth_getTransactionByHash to The router or contract the wallet called (router on the facts)
eth_call decimals() per token (0x313ce567) the token's decimals amount in token units beside the atomic amount; null when the token does not answer

Incremental sync and watermark

  • The connection remembers the last block it read (config.last_block). Every sync re-reads from 64 blocks behind it to the tip (a short reorg rewrites the tip; facts are keyed on transaction and log index, so the re-read is idempotent), at most 60 chunks of 2 000 blocks per sync; a connection further behind says how many blocks remain and continues on the next sync.
  • First sync: from start_block when given, otherwise about a day of blocks behind the tip (43 200 blocks).
  • Watermark = the timestamp of the last block read, so coverage and settlement reason about time as for every other source.

Fact types produced

Subject id is the wallet address, lowercase; subject kind wallet. Token addresses are lowercase too. Every fact carries tx_hash, network (CAIP-2), router (the transaction's to), block and status: confirmed (eth_getLogs returns the events of mined, successful transactions only).

fact_type When Extra attributes raw_ref
token_sent A Transfer from the wallet token, atomic_amount, amount, decimals, counterparty (the receiver), log_index chain:{network}:{tx}:{log_index}
token_received A Transfer to the wallet as above; counterparty is the sender chain:{network}:{tx}:{log_index}
swap_executed A transaction in which the wallet both sent and received tokens sold_token, sold_amount, sold_atomic_amount (the largest sent leg), bought_token, bought_amount, bought_atomic_amount (the largest received leg), sent_legs, received_legs chain:{network}:{tx}:swap:{wallet}

A chain watcher of your own may push facts of the same source with an evidence key (POST /v1/facts, source chain): the pack's contracts accept shared trust for them. A watcher can also report what the connector cannot: swap_executed with status: pending for a transaction it saw in the mempool (the pack reads that as UNKNOWN), and swap_reverted when it was dropped or reverted (the pack reads that as a reversal). When a chain connection is live, pushed chain facts are refused (409 source_served_by_connector), as for every connector-served source.

What is hashed / never stored

  • Addresses and transaction hashes are public chain data; nothing identifies a person and nothing is hashed.
  • No balance, no native-currency movement, no contract state and no transaction other than the watched wallets' ERC-20 transfers is requested. The endpoint URL is stored as a secret because provider URLs carry keys.

Rate-limit handling

Shared HttpClient (Retry-After, exponential backoff on 429/5xx, 6 attempts). Public endpoints often cap eth_getLogs ranges; the 2 000-block chunk stays under the common caps.

Known limitations

  • Native-currency legs are not events. ETH (or the chain's native coin) sent as transaction value does not emit a Transfer, so a swap whose sold or bought side is native ETH rather than WETH shows only one leg and is not a swap_executed; it appears as a single token_received or token_sent. Agents that swap through WETH are read in full.
  • Routes with several legs. A swap through two pools emits several transfers; the sold and bought legs are the largest sent and received amounts, and the leg counts are recorded. Fee legs (a small transfer to a fee collector) are recorded as their own token_sent.
  • A wallet that never traded has no record, so an action on it answers UNKNOWN (identity_unmatched) rather than FAIL until any transfer that names it exists.
  • Chain data only. Prices, the quote the agent received and the agent's intended slippage are not on the chain; the contract compares the amount bought with the expected_bought_amount the agent recorded, within the tolerance set in the wizard.
  • A removed log the connector had already stored before the reorganisation is not deleted; it stays with the block it was read in. Reorganisations deeper than 64 blocks are not re-read.
  • The connector has been tested against recorded JSON-RPC responses in the shape of the specification, not yet against a live endpoint; the first live sync is on the backlog.