@coinbase/coinbase-cli 0.0.5 → 0.0.7

package/dist/version.txt

@@ -1 +1 @@
-0.0.5
+0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/coinbase-cli",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Coinbase for agents — CLI and MCP server for trading, wallets, payments, and onchain across the Coinbase platform",
   "type": "module",
   "bin": {

package/skills/coinbase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coinbase
-description: Umbrella skill for the coinbase CLI — the agent-first interface to the Coinbase Advanced Trade brokerage. Use when the user mentions Coinbase trading, spot orders, crypto prices, balances, portfolios, converting currencies, or wants to know which coinbase tool/lane to use. Indexes the granular journey skills (trading, market-data, watch, convert, portfolios) and explains auth, env, and MCP-vs-CLI selection.
+description: Umbrella skill for the coinbase CLI — the agent-first interface to the Coinbase Advanced Trade brokerage and curated x402 resources. Use when the user mentions Coinbase trading, spot orders, crypto prices, balances, portfolios, conversions, x402 payments, or wants to know which coinbase tool/lane to use. Indexes the granular journey skills and explains auth, env, and MCP-vs-CLI selection.
 ---
 
 # coinbase CLI
@@ -53,7 +53,7 @@ Add MCP with: `claude mcp add --scope user --transport stdio coinbase -- coinbas
 
 ## Install agent skills
 
-Skills give your agent step-by-step guidance for common Coinbase workflows (trading, market data, watch, convert, portfolios).
+Skills give your agent step-by-step guidance for common Coinbase workflows (trading, market data, watch, convert, portfolios, x402).
 
 ```sh
 coinbase skills add
@@ -105,3 +105,4 @@ Output: `stdout` = raw JSON (parseable), `stderr` = human status/errors. Exit `0
 | `coinbase-watch` | trigger an action on a live condition (`--until` watchers) |
 | `coinbase-convert` | convert between currencies (USDC ↔ USD, etc.) |
 | `coinbase-portfolios` | list / create / manage portfolios, move funds between them |
+| `coinbase-x402` | discover curated x402 resources, pay and fetch them, attach the correct v1/v2 payment header |

package/skills/coinbase-equities/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: coinbase-equities
+description: Places and manages equity (stock) orders on Coinbase Advanced Trade — market/limit orders, trading sessions (pre-market, regular, after-hours, overnight, multi-session), and halted-symbol handling. Use when the user wants to buy or sell a stock/ETF, or asks about equity trading sessions, market hours, or halts. Uses the same `coinbase orders`/`coinbase products` commands as crypto (see `coinbase-trading`), plus equity-only fields covered here. These are real orders.
+requires: coinbase env configured with Trade permission (see `coinbase` skill)
+---
+
+# coinbase-equities
+
+Equity (stock) orders use the same `coinbase orders create` command as crypto (see `coinbase-trading` for the shared market/limit/stop_limit mechanics, sizing, and order-management commands). This skill covers what's different for equities: **product IDs use the TICKER-QUOTE form** (e.g. `AAPL-USD` or `AAPL-USDC`, same shape as crypto pairs) — many tickers have separate USD and USDC listings, so a bare ticker like `AAPL` is rejected; you must pick the exact listing. Orders are also subject to **trading sessions** and **halts** — concepts that don't exist for 24/7 crypto.
+
+**`orders preview` is not available for equities** — it's rejected upstream regardless of product or session. Go straight to `orders create` for equities (still preview first for crypto/futures).
+
+## Trading sessions
+
+`equity_trading_session` is required on every equity order:
+
+- `NORMAL` — standard market hours. Only session that accepts market orders. Rejected (`untradable product`) if the market is currently closed.
+- `PRE_MARKET` — pre-market hours. Whole-share limit orders only.
+- `AFTER_HOURS` — after-hours session. Whole-share limit orders only.
+- `OVERNIGHT` — overnight session. Whole-share limit orders only.
+- `MULTI_SESSION` — spans pre-market + regular + after-hours in one order. Whole-share limit orders only.
+
+"Whole-share limit orders only" means: `type=limit`, no `quote_size`, no fractional `base_size` — no market orders.
+
+```sh
+# Regular-hours market buy of $500 of AAPL
+coinbase orders create product_id=AAPL-USD side=BUY type=market quote_size=500 \
+  equity_trading_session=NORMAL
+
+# Pre-market limit buy — must be a whole-share limit order
+coinbase orders create product_id=AAPL-USD side=BUY type=limit base_size=2 limit_price=195.00 \
+  equity_trading_session=PRE_MARKET
+
+# Multi-session (pre-market + regular + after-hours) — must be a whole-share limit order
+coinbase orders create product_id=AAPL-USD side=BUY type=limit base_size=2 limit_price=195.00 \
+  equity_trading_session=MULTI_SESSION
+```
+
+`equity_order_date` (format `YYYY-MM-DD`) is optional and only needed if the user is scheduling an order for a specific trading day rather than today.
+
+## Halts and closed markets
+
+An order against a halted symbol or submitted when the requested session isn't open is rejected — market orders are also prohibited outside the core session for a symbol. If `coinbase orders create` fails, **report the rejection reason to the user rather than silently retrying** (e.g. with a different session or order type) — a different session may not be what they intended.
+
+If the user wants to know whether a symbol is currently tradable, check `coinbase products get <TICKER-QUOTE>` before placing a market order during a session that might not be open.
+
+## Everything else
+
+Sizing (`quote_size`/`base_size`), preview, edit, cancel, fills, and portfolio scope work exactly as for crypto — see `coinbase-trading`. Equity positions and cash balance appear in `coinbase portfolios get` alongside crypto positions (`equity_positions`, `total_equities_balance`).

package/skills/coinbase-futures/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: coinbase-futures
+description: Places and manages CFM dated futures orders on Coinbase Advanced Trade — liquidation risk. Use when the user wants to open a dated futures position, or asks about liquidation risk. Uses the same `coinbase orders`/`coinbase portfolios` commands as spot (see `coinbase-trading`). These are real orders — losses can occur.
+requires: coinbase env configured with Trade permission (see `coinbase` skill)
+---
+
+# coinbase-futures
+
+CFM dated futures orders use the same `coinbase orders create` / `orders preview` commands as spot (see `coinbase-trading` for the shared market/limit/stop_limit mechanics and order-management commands). This skill covers what's different for CFM.
+
+**Portfolio scope**: CFM dated futures are documented as available only in the caller's default portfolio for now. Pass the default portfolio_uuid (equal to the user's UUID — see `coinbase-trading`) rather than a named sub-portfolio for any futures order.
+
+**Product IDs**: `<BASE>-<DDMMMYY>-CDE`, e.g. `BIT-28AUG26-CDE` (Bitcoin) or `BIP-20DEC30-CDE` (a separate Bitcoin-linked contract series — note the ticker root is `BIP`, not `BTC`). These roll to a new contract code every cycle — don't hardcode a date-coded ticker long-term; discover the live one with `coinbase products list product_type=FUTURE` and filter by the `-CDE` suffix.
+
+## Market orders: `base_size` only, and can fail after acceptance
+
+Futures market orders **must use `base_size`** (number of contracts) — `quote_size` is rejected with `"Futures market orders must be parameterized in base (number of contracts)"`. A market order can also be accepted (an `order_id` is returned) and then transition to `FAILED` asynchronously — not something the CLI can detect at submission time. For a reliable, immediate-fill order, prefer an IOC limit at/above the ask (buy) or at/below the bid (sell) instead of a plain market order:
+
+```sh
+coinbase orders create product_id=BIT-28AUG26-CDE side=BUY type=limit base_size=1 limit_price=65000 \
+  time_in_force=IOC
+```
+
+CFM's margin/leverage is fixed by the exchange per contract, not user-selectable per order — there's no `leverage`/`margin_type` param for orders.
+
+**Before placing an order, preview it and read back `predicted_liquidation_price`** — check current position risk from `portfolios get` alongside it, and confirm with the user if margin looks tight:
+
+```sh
+coinbase orders preview product_id=BIT-28AUG26-CDE side=BUY type=limit base_size=1 limit_price=65000
+```
+
+## Checking liquidation risk
+
+`coinbase portfolios get <portfolio_uuid>` includes `futures_positions` alongside spot.
+
+```sh
+coinbase portfolios get <portfolio_uuid> --jq '.futures_positions'
+```
+
+## Everything else
+
+Sizing (`quote_size`/`base_size`), order types, preview, edit, cancel, and fills work exactly as for spot — see `coinbase-trading`. `reduce_only` is not yet supported for CFM orders through this tool.

package/skills/coinbase-market-data/SKILL.md

@@ -48,4 +48,5 @@ coinbase products list --jq '.products[].product_id' --paginate
 ## Notes
 
 - For streaming/conditional reads ("tell me when BTC > 65k"), use `coinbase-watch` (`--until`), not polling loops.
-- Market data is read-only and does not place orders. To act on a price, hand off to `coinbase-trading`.
+- Market data is read-only and does not place orders. To act on a price, hand off to `coinbase-trading` (spot), `coinbase-futures` (CFM dated futures), or `coinbase-equities` (stocks).
+- Unlike crypto (always open), an equity quote can be stale outside its trading session, and a halted symbol won't move at all — check `coinbase products get <TICKER-QUOTE>` before treating an equity price as tradable now.

package/skills/coinbase-portfolios/SKILL.md

@@ -25,6 +25,10 @@ coinbase portfolios edit <portfolio_uuid> name="Renamed"
 coinbase portfolios delete <portfolio_uuid>
 ```
 
+`portfolios get` includes `futures_positions` alongside spot for any portfolio holding CFM dated-futures positions — see `coinbase-futures` for placing futures orders and reading liquidation risk.
+
+`portfolios get` includes equity positions and cash alongside crypto (`equity_positions`, `portfolio_balances.total_equities_balance`) for any account holding stocks — see `coinbase-equities` for placing equity orders.
+
 ## The per-key scoping model
 
 Each CDP API key is scoped to ONE portfolio — the key can only trade within it. To operate across portfolios, register one env per portfolio using the `live-<portfolio>` convention:

package/skills/coinbase-x402/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: coinbase-x402
+description: Discovers curated x402 resources and pays for them with Coinbase custodial USDC. Use when the user wants to find, call, or pay an x402 resource, handle a 402 Payment Required challenge, or needs to know whether to send X-PAYMENT or PAYMENT-SIGNATURE.
+requires: coinbase env configured with the required x402 payment scopes (see `coinbase` skill)
+---
+
+# coinbase-x402
+
+Discover and call curated x402 resources through the Coinbase Agent API. Discovery is free, but `pay` and `fetch` can place a real USDC hold. Confirm the resource and maximum spend with the user before paying.
+
+## Choose the flow
+
+- Use `x402 resources` to search the curated catalog without spending funds.
+- Prefer `x402 fetch` for a catalog resource. It handles the v2 challenge, payment, and retry in one call.
+- Use `x402 pay` only when the caller must attach a payment header to its own HTTP request.
+
+## Discover and fetch
+
+```sh
+coinbase x402 resources q==wallet
+
+coinbase x402 fetch \
+  resource=https://example.com/paid-resource \
+  input:='{"address":"0x..."}' \
+  max_amount=1000000
+```
+
+Use the exact URL and only the input fields returned by discovery. Inspect the advertised payment requirement before fetching. Set `max_amount` when the user wants a cap below the catalog ceiling. It is denominated in the payment asset's atomic units.
+
+`x402 fetch` supports protocol v2 resources and automatically uses the correct payment header.
+
+## Create a payment header
+
+Copy the resource's 402 challenge fields exactly. In particular, copy `x402Version` into `x402_version`; do not assume the version from the resource URL or the encoded header.
+
+```sh
+coinbase x402 pay \
+  scheme=exact \
+  network=eip155:8453 \
+  asset=0x... \
+  pay_to=0x... \
+  amount=10000 \
+  max_amount=10000 \
+  max_timeout_seconds:=300 \
+  x402_version:=2 \
+  extra:='{"name":"USD Coin","version":"2"}'
+```
+
+The result contains `payment_header`. Attach it according to the challenge version:
+
+| `x402_version` | HTTP header |
+| :--- | :--- |
+| `1` | `X-PAYMENT` |
+| `2` | `PAYMENT-SIGNATURE` |
+
+The header names are not interchangeable. Never send `X-PAYMENT` to a v2 resource or `PAYMENT-SIGNATURE` to a v1 resource.
+
+If the resource rejects the header, first verify that the challenge's `x402Version`, the `x402_version` passed to `pay`, and the HTTP header name agree. Do not create another payment merely to try the other header name.
+
+## Retry safety
+
+Use the smallest `amount` and `max_amount` that satisfy the requirement. Reuse the returned `idempotency_key` only when retrying the same logical payment after an outcome-unknown failure. Starting a retry without it can create another hold.