# Coinbase Agent Trade pack

**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.
