Coinbase Agent Trade pack
Trades, closes, rebalances and payments an agent makes on a Coinbase account, verified against Coinbase's orders, fills, balances and sends, and onchain swaps from a CDP Server Wallet verified against the chain; version 2 of coinbase_agent_trade as an upgrade beside version 1.
Last changed Markdown versionllms.txt
Version 1.2.0 (beta) · Builder plan and above · requires the Coinbase connector; the chain connector for wallet agents
For teams whose agents trade on a Coinbase account (through Coinbase for Agents and its MCP server,
orders_create, or the Advanced Trade API) and for teams whose agents trade onchain from a Coinbase CDP Server
Wallet (AgentKit, the CDP MCP server, a wallet of their own). Coinbase's own controls run before the order: the portfolio the
agent's key is scoped to, the key's permissions, the x402 spending cap. This pack runs after: it reads
Coinbase's record of the account's orders and fills, the portfolio's balances and the account's sends on a View-only
key and says whether the trade or payment the agent reported is the one that happened.
What it does not do
CommitLayer never places, cancels or edits an order, never sends a payment, never holds a trading or transfer key
and never moves funds. Its connector key is View only (orders, fills, balances, sent transactions), scoped to the
agent's portfolio; balances are read to say whether a position is open or flat after a close, never to judge whether
an order was affordable. The tool's response to orders_create or to a send is context in the evidence view,
never an order or transfer record.
Workflows
| Workflow | Contract | Subject | Must be true afterwards | Fails the action |
|---|---|---|---|---|
place_agent_trade |
coinbase_agent_trade v2 (upgrade of the library's v1) |
the product (TSLA-USD) |
one order on the product created in the window and filled; on the side asked; in the agent's portfolio; for the notional asked; the fill within the slippage allowed | a second order, a wrong side or portfolio, another notional, a fill too far from the request, an order cancelled, expired or rejected, a product or order type outside the approved lists, the per-order or daily total exceeded, a fill busted or corrected within 7 days |
close_agent_position |
cbat_close_agent_position v2 |
the product | one closing order on the product, on the closing side, in the agent's portfolio, filled for the whole position size; Coinbase's latest balance for the product within a day of the close shows no position | a partial fill (the position stays open), a wrong side (the position doubled), a second order, a wrong portfolio, a cancelled order, a busted fill, a balance that still shows the position |
rebalance_portfolio |
cbat_rebalance_portfolio v1 |
the portfolio, with its legs' products linked | the legs filled in the agent's portfolio, within the approved total and leg count | a leg cancelled, expired or rejected; more orders than legs; a leg in another portfolio; the daily total exceeded; a leg's fill busted later |
send_agent_payment |
cbat_send_agent_payment v1 |
the recipient (address, Coinbase user or email, as Coinbase records it) | one send to the recipient created in the window and completed, for the amount, asset and network approved, within the per-payment and daily limits | no send, a second send, another amount, asset or network, an asset or network outside the approved lists, a send Coinbase reports failed, cancelled or expired |
place_wallet_swap |
cbat_place_wallet_swap v1 |
the wallet address (a CDP Server Wallet's EVM account, or any EVM wallet) | one confirmed swap by the wallet in the window on the chain's own record: the token sold, the token bought and the network as approved, the amount sold as approved, the amount bought within the slippage allowed, within the per-swap and daily limits | no swap, a second swap, another token, network or amount, a token or network outside the approved lists, a swap a watcher later reports reverted |
An order Coinbase still reports as PENDING leaves the action UNKNOWN until the status changes; an order still
OPEN when the window closes is a FAIL: the trade did not complete in the time approved. A send Coinbase still
reports as pending, waiting_for_signature or waiting_for_clearing likewise leaves the payment UNKNOWN (Coinbase
documents sends as asynchronous and cancellable); a send that later fails, is cancelled or expires fails it.
Version 1 to version 2
The library's coinbase_agent_trade version 1 keeps working and keeps governing every workspace that selected it.
Installing the pack saves version 2 of the same contract as a draft beside it; compare_pack_versions and the
install's weakening report show the diff, which is all strengthening: the side and the portfolio are compared with
the approval (text comparison, new in 0.9.26), the order type and the product must be on the approved lists, the
fill's notional must be within a slippage tolerance, and a PENDING order reads UNKNOWN instead of FAIL. Nothing
changes for live actions until a person selects version 2; actions recorded under version 1 stay pinned to it.
Version 1.1.0: the close reads the position it leaves; payments are verified
cbat_close_agent_position is now version 2: besides its closing order, the latest position_snapshot the
connector read for the product within a day of the close must not still show a position (state: open). The check
is a forbidden effect under the policy lens, so a workspace whose key cannot read balances keeps the order-based
verdict; it fails only when Coinbase positively shows the position still open. A workspace that installed 1.0.0
sees the change as a strengthening in the upgrade diff; nothing changes until a person selects the new draft.
send_agent_payment verifies a payment the agent sends from the account's wallets against Coinbase's record of
its sends (Coinbase App "List Transactions", type send, read on the same View permission). The subject is the
recipient as Coinbase records it, so a payment to the wrong address is a missing send to the approved one. The
contract compares amount, asset and network with the approval, caps each payment and the day's total (in the
account's native currency), and reads a pending or waiting send as UNKNOWN.
Version 1.2.0: agents that trade onchain from a CDP Server Wallet
Most agents on Coinbase's own platform do not place Advanced Trade orders: they hold a CDP Server Wallet and swap
onchain (FereAI, Questflow and the other AgentKit builders). Coinbase's wallet APIs sign and send but do not list a
wallet's past swaps, so the record that cannot be edited is the chain. The chain connector
(docs/connectors/chain.md) reads, from any JSON-RPC endpoint for the network, the ERC-20 Transfer events that
name the agent's wallets, pairs the legs of each transaction into swap_executed (token sold, token bought, router,
amounts) and keys the facts on the wallet address. It needs no CDP key and no wallet secret, signs nothing and
sends nothing. place_wallet_swap verifies the agent's recorded swap against that record; a chain watcher of your
own may push the same facts with an evidence key, and may add what the connector cannot see: a swap still pending
(UNKNOWN) and a swap later reverted (a reversal). Native-ETH legs are not events and are not read; agents that swap
through WETH are read in full.
What is still not in this version
purchase_x402_service. An x402 purchase an agent makes with its Coinbase wallet is the x402 Service Delivery pack's domain: install it beside this one; its adapter records the purchase on the payment's nonce.- Target allocations. The connector reads balances per asset, not the weights a rebalance was meant to reach, so
a rebalance is still judged by its legs. Stated on the contract's
unknown_fields. - Trades on other venues. An agent that also trades on Hyperliquid or another exchange is verified there only if that venue's record is read; the chain connector covers EVM swaps, the Coinbase connector the Coinbase account.
- Wallet tool mappings. The AgentKit and CDP MCP swap tools' names and arguments are not confirmed from
documentation, so no recorder mapping is shipped for them; the orchestrator records the swap through the SDK on the
wallet as subject, with the quote's expected amount as
expected_bought_amount. - Wallet visibility for a portfolio-scoped key. Coinbase's page does not say whether a key restricted to one
portfolio can list
/v2/accounts; when it cannot, the sync saystransfers not readand payments stay unverifiable on that key. A recipient the account never paid before has no record, so the first payment to it answers UNKNOWN (identity_unmatched) rather than FAIL.
Evidence
| Source | What it holds | Who reads it | Trust |
|---|---|---|---|
chain |
swap_executed (sold_token, sold_amount, bought_token, bought_amount, router, network, tx_hash, status), token_sent, token_received, all on the wallet address; a watcher may add status: pending and swap_reverted |
the chain connector on a JSON-RPC endpoint (independent, native_connector), or your chain watcher with an evidence key (customer_backend or blockchain_confirmation) |
independent or shared |
coinbase |
order_created (status refreshed on every sync; side, order_type, quote_value, quote_size, base_size, limit_price, portfolio_id, client_order_id), order_filled (filled_size, filled_value, average_filled_price, total_fees), order_failed, order_reversed; position_snapshot per traded product (asset, balance, state open or flat); transfer_created (status refreshed; amount, asset, native_amount, network, hash, to_address, idem), transfer_completed, transfer_failed on the recipient |
the Coinbase connector, View-only key, portfolio filter | independent (native_connector) |
A product the account has never traded has no record, so an action on it answers UNKNOWN (identity_unmatched,
subject not found) rather than FAIL until any order on the product exists; the pack's fixtures start from a product
the agent has traded before, as a live account does.
Install
- Connector. Coinbase, on a CDP key with View only, ECDSA, restricted to the agent's portfolio
(
portfolio_idon the connection keeps a person's own trades out of the agent's evidence). - Contracts. Five action contracts, shown with every check; the diff of
coinbase_agent_tradev1 to v2 if v1 is selected. Install saves drafts, pinned by version. - Parameters. Per-order and daily notional limits, the approved markets and order types (lists), the slippage tolerance, the window; for a rebalance the approved total and the most legs; for a payment the per-payment and daily limits, the approved assets and the allowed networks (as Coinbase names them on the transaction).
- Dry run. 83 fixture cases across the five workflows, in a savepoint; nothing is written. For wallet agents, add the chain connection (endpoint, network, the agents' wallet addresses) beside the Coinbase one, or instead of it when the agents never touch the exchange account.
- Activate.
POST /v1/contracts/{id}/selectper contract, by a person with the analyst role; the recorder mapping with version 2 pinned is served atGET /v1/packs/coinbase_agent_trade/recorder-mapping.
Recording
The recorder mapping covers orders_create as the public recorder's Coinbase example does: subject
arguments.product_id, amount from arguments.quote_size, side, order type, client order id and portfolio, action
id trade:{arguments.client_order_id} so a retried call is one action and the evidence view shows which Coinbase
order each action produced. A close or a rebalance is recorded by the orchestrator through the SDK (at the tool
layer a close is an orders_create on the opposite side and a rebalance is several); the rebalance's legs are
linked to the portfolio with portfolio_to_product links. A payment is recorded by the orchestrator through the
SDK too, with the recipient as the subject (record_action("cbat_send_agent_payment", recipient, params={amount, asset, network})): the Coinbase MCP server's transfer tool and its argument names are not confirmed from
documentation, so no tool mapping is shipped for it and the contract lists the name as unknown. Tool argument names
beyond the example's, and the tool names of other frameworks that trade on Coinbase, are likewise listed as unknown
rather than guessed.
Fixtures and scenarios
Each workflow ships PASS, FAIL, UNKNOWN, duplicate, delayed-evidence and reversal cases and the failures the brief names: the order drafted but never executed (Coinbase's own documented failure), the trace that says filled while the order rests open, the wrong product, the wrong side, the duplicate order after a retry, the fill below the threshold or beyond the slippage, the daily limit exceeded, the fill later busted or corrected, the wrong portfolio, the order still pending; for a close, the balance that still shows the position; for a payment, the send that never happened, the pending send, the send that failed, the wrong amount, asset, network or recipient, the duplicate after a retry, the limits, and the pending send Coinbase cancelled a day later; for an onchain swap, the swap that never happened, the pending swap, the wrong token, network, amount or wallet, the slippage beyond tolerance, the duplicate after a retry, the limits, and the pending swap later reverted. The scenario files label every case with one of the sixteen shared failure modes and carry the deterministic expectation.