Skip to content
Browse the documentation
Workflow packs

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 says transfers not read and 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

  1. Connector. Coinbase, on a CDP key with View only, ECDSA, restricted to the agent's portfolio (portfolio_id on the connection keeps a person's own trades out of the agent's evidence).
  2. Contracts. Five action contracts, shown with every check; the diff of coinbase_agent_trade v1 to v2 if v1 is selected. Install saves drafts, pinned by version.
  3. 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).
  4. 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.
  5. Activate. POST /v1/contracts/{id}/select per contract, by a person with the analyst role; the recorder mapping with version 2 pinned is served at GET /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.