# Coinbase

Source module: `app/connectors/coinbase.py`. Kind: **facts** only. Display name: "Coinbase".

## Purpose

Reads the orders and fills of a Coinbase account through the Advanced Trade API, so that a trade an agent
places (through the Coinbase MCP server of Coinbase for Agents, `orders_create`, or the API directly) can be
verified under the `coinbase_agent_trade` library contract: did an order on the product the agent was told to
trade exist, once, for the notional asked, did it fill within the window, and was it not cancelled, rejected,
busted or corrected afterwards.

Coinbase's own controls run **before** the order: the portfolio the agent's key is scoped to, the permissions
on the key, the spending cap on x402 payments. This connector adds nothing there. It reads Coinbase's record
**after** the order, so that the agent's report of what it traded is checked against what Coinbase says it
traded.

## Auth and scopes

| Item | Value |
|---|---|
| Method | CDP API key (Coinbase Developer Platform, "Secret API Keys"); every request carries a two-minute ES256 JWT signed with the key's EC private key, as Coinbase's reference signs it (`sub` and `kid` the key name, `iss` `cdp`, `nbf`, `exp` now + 120 s, `uri` `GET api.coinbase.com/<path>`, a nonce header) |
| Credentials stored (encrypted) | `key_name`, `private_key` (PEM); optional `portfolio_id`; optional `base_url` |
| Least-privilege permissions for the key | **View** only. No Trade, no Transfer. Create the key with the signature algorithm set to **ECDSA** (Advanced Trade does not accept Ed25519 keys; the connector refuses one with the reason) and, when the portal offers it, restricted to the portfolio the agent trades in |
| Connection test | `GET /api/v3/brokerage/orders/historical/batch?limit=1` |
| Non-secret config | `portfolio_id`: when set, only orders and fills whose `retail_portfolio_id` matches are read. Coinbase for Agents keeps each agent in its own portfolio; naming it keeps a person's own trades out of the agent's evidence |

The private key is stored only as ciphertext and is used only to sign tokens for read requests. It is never
logged and never leaves the API process.

## Fields pulled and why

| Endpoint | Fields | Used for |
|---|---|---|
| `GET /api/v3/brokerage/orders/historical/batch?start_date=since-7d&limit=100` (pages by `cursor` while `has_next`) | `order_id`, `client_order_id`, `product_id`, `side`, `status`, `order_type`, `order_configuration` (`quote_size`, `base_size`, `limit_price`), `filled_size`, `filled_value`, `average_filled_price`, `total_fees`, `number_of_fills`, `created_time`, `last_fill_time`, `last_update_time`, `retail_portfolio_id`, `order_placement_source`, `reject_reason` | Order facts, subject id, watermark |
| `GET /api/v3/brokerage/orders/historical/fills?start_sequence_timestamp=since-7d&limit=100` (pages by `cursor`) | `trade_id`, `order_id`, `product_id`, `side`, `trade_type`, `price`, `size`, `commission`, `trade_time`, `retail_portfolio_id` | Reversal facts |

Orders are re-read seven days behind the watermark on every sync: an order placed days ago can still fill, be
cancelled or have a fill reversed, and the facts for those are keyed on the order, so the re-read is idempotent.
A fills list the key cannot read (`403`) is noted on the sync and does not fail it; reversals are then not
observed, and the connection's notes say so.

## The order's notional

Agents are asked to trade an amount in the quote currency ("buy $50 of TSLA"). The connector derives one
number, `quote_value`, from the order: the `quote_size` it was placed with when it was; otherwise
`filled_value`; otherwise, for a limit order placed by base size, `base_size × limit_price`. The contract
compares it with the action's `amount`.

## What is hashed / never stored

- Nothing in these two lists identifies a person; no hashing is needed.
- Account balances, deposit and withdrawal history, payment methods, addresses, names, tax forms and anything
  outside the two endpoints above are never requested.

## Incremental sync and watermark

- Orders: `start_date = watermark − 7 days` (2020-01-01 on first sync), page size 100, `cursor` while `has_next`.
- Fills: `start_sequence_timestamp = watermark − 7 days`, page size 100, `cursor` while pages are non-empty.
- Watermark = maximum order `created_time`.
- Upserts are idempotent (by `raw_ref`).

## Rate-limit handling

Shared `HttpClient` (Retry-After, exponential backoff on `429`/`5xx`, 6 attempts, immediate `reauth` failure
on `401`/`403` for the orders list).

## Fact types produced

Subject id is Coinbase's product id (`BTC-USD`, `TSLA-USD`), subject kind `product`: the thing the agent was
told to trade, which is what its recorded action names. Every fact carries `order_id`, `client_order_id`,
`side`, `order_type`, `quote_value` and `portfolio_id`.

| `fact_type` | When | Extra attributes | `raw_ref` |
|---|---|---|---|
| `order_created` | Every order, at `created_time`; attributes refresh on every sync | `status` (current), `placement_source` | `coinbase:order:{order_id}` |
| `order_filled` | Status `FILLED`, at `last_fill_time` | `filled_size`, `filled_value`, `average_filled_price`, `total_fees`, `number_of_fills` | `coinbase:order:{order_id}:filled` |
| `order_failed` | Status `CANCELLED`, `EXPIRED` or `FAILED`, at `last_update_time` | `status`, `reject_reason` | `coinbase:order:{order_id}:{status}` |
| `order_reversed` | A fill whose `trade_type` is `REVERSAL` or `CORRECTION`, at `trade_time` | `trade_id`, `trade_type`, `price`, `size`, `commission` | `coinbase:fill:{trade_id}` |

Ordinary fills (`trade_type` `FILL`) do not become facts of their own: the order's fill is already
`order_filled`.

## Claims produced

None.

## Subject id format

The product id as Coinbase spells it. An agent that records a `coinbase_agent_trade` action uses the same
subject (the `product_id` it passes to `orders_create`); the recorder mapping in
`recorder/python/examples/coinbase.json` does this.

## Known limitations

- A product the account has never traded has no record at all, so an agent's claim to have traded it, when
  nothing was created, answers UNKNOWN (`identity_unmatched`, "subject not found") rather than FAIL; once any
  order on the product exists, a missing one is a FAIL. The sandbox's broker seeds a `product_status` record per
  product for this reason; a production workspace can push one through the facts API for the products its
  agents are allowed to trade.
- The side (`BUY` or `SELL`) is limited on the action's parameter and shown in the evidence; the engine's
  value comparisons are numeric, so the order's side is not compared with the request.
- `order_placement_source` is read and shown but its values for orders placed through the Coinbase MCP server
  are not documented (listed under `unknown_fields` on the contract); nothing is keyed on it.
- Balances and positions are not read: whether the account could afford the order is Coinbase's check before
  the order, not evidence of it afterwards.
- The connector has been tested against recorded responses in the shape of the reference, not yet against a
  live Coinbase account; the first live sync is on the backlog.