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_blockwhen 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 aswap_executed; it appears as a singletoken_receivedortoken_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_amountthe agent recorded, within the tolerance set in the wizard. - A
removedlog 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.