@coinbase/coinbase-cli 0.0.2 → 0.0.4

package/dist/version.txt

@@ -1 +1 @@
-0.0.2
+0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/coinbase-cli",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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,141 +1,81 @@
 ---
 name: coinbase
-description: Use this skill when the user wants to trade cryptocurrency on Coinbase Advanced Trade — check prices, place market or limit orders, manage portfolios, view balances, convert currencies, or query brokerage data. Execute commands with the `coinbase` binary.
+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.
 ---
 
 # coinbase CLI
 
 `coinbase` is an agent-first CLI for the Coinbase Advanced Trade brokerage API. All commands output JSON to stdout by default. Errors are JSON to stderr with non-zero exit codes.
 
-## Prerequisites
+These are REAL orders against a live brokerage. Confirm the full plan with the user before placing or arming anything.
+
+## Auth & env
 
 Authenticated commands need a CDP API key configured per environment.
 
-1. Go to https://portal.cdp.coinbase.com/projects/api-keys → Click **Create API Key**
-2. In the Create API Key modal:
-   - Under **API restrictions → Coinbase App & Advanced Trade**:
-     - Select the **Portfolio** this key will be scoped to (e.g. "Primary"). The key can only trade within this portfolio.
-     - Enable **Trade** and **Transfer** permissions (View is on by default).
-   - Under **Advanced Settings** (bottom of modal):
-     - Select **ECDSA** signature algorithm. The brokerage SDK rejects Ed25519.
-3. Download the key file and configure:
+1. https://portal.cdp.coinbase.com/projects/api-keys → **Create API Key**
+2. Under **API restrictions → Coinbase App & Advanced Trade**: pick the **Portfolio** to scope the key to, enable **Trade** and **Transfer** (View is default).
+3. Under **Advanced Settings**: select **ECDSA** (the brokerage SDK rejects Ed25519).
+4. Download the key file, then:
    ```sh
    coinbase env live --key-file path/to/cdp_api_key.json
+   coinbase balance          # verify
    ```
-4. Verify: `coinbase balance`
-
-### Multiple portfolios
 
-Each CDP key is scoped to one portfolio. To operate across portfolios, create a key per portfolio and register each as a separate environment using the `live-<portfolio>` convention:
-
-```sh
-coinbase env live-primary --key-file primary-key.json
-coinbase env live-trading --key-file trading-key.json
-```
+Each CDP key is scoped to one portfolio. To operate across portfolios, register one env per portfolio (`live-primary`, `live-trading`) and switch with `coinbase env live-trading` or per-command `-e live-primary`. See `coinbase-portfolios`.
 
-Switch with `coinbase env live-trading` or per-command with `-e live-primary`. Moving funds between portfolios requires switching to the source portfolio's key first.
+## Permissions
 
+By default agents prompt before each `coinbase` command. To reduce or remove those prompts, allow-list commands in your agent's permission settings. Offer the user two tiers:
 
-## Discovery
+- **Read-only** — never prompted for safe reads (prices, balances, history); still prompted before any order or transfer. Good default.
+- **Everything** — never prompted at all, including orders and transfers. Confirm explicitly before enabling.
 
-```sh
-coinbase --help                                # All resources + commands
-coinbase orders --help                         # Actions in a resource
-coinbase orders create --template              # Request body template
-```
+Allow-list rules for each tier:
 
-## Common workflows
+| Tier | Rules |
+| :--- | :--- |
+| Read-only | `coinbase balance`, `coinbase products *`, `coinbase orders list`, `coinbase orders get *`, `coinbase orders fills`, `coinbase fees`, `coinbase env`, `coinbase portfolios list`, `coinbase portfolios get *` |
+| Everything | `coinbase *` |
 
-### Check a price (authenticated)
+How to apply depends on the agent. For Claude Code, add the rules to `permissions.allow` in settings.json (e.g. `Bash(coinbase products *)`) — `~/.claude/settings.json` for all projects or `.claude/settings.json` to share with a team. Other agents have their own allow-list mechanism.
 
-```sh
-coinbase products get BTC-USD                  # Current BTC product info
-coinbase products candles BTC-USD --jq '.candles[0]'
-coinbase products book BTC-USD --jq '.pricebook'
-```
+## MCP vs CLI — which lane
 
-### List balances
+Both surfaces wrap the same API. Pick by the shape of the task:
 
-```sh
-coinbase balance                               # All account balances
-coinbase balance show_zero==true               # Include zero-balance accounts
-```
+- **MCP** (`coinbase_<resource>_<action>` tools) — for **atomic, structured calls**: place one order, fetch a ticker, list portfolios. Typed args, structured result, no shell needed.
+- **CLI** (`coinbase ...` in Bash) — for **composition and streaming**: `--until` conditional watchers, piping (`| jq`), chaining with `&&`, `--paginate`, scripting multi-step flows. Anything MCP can't express as a single call.
 
-### Funding a fresh account
+Rule of thumb: one structured action → MCP; a pipeline, a stream, or a conditional → CLI.
 
-The brokerage API does not support buying crypto with a payment method directly. To fund an account for trading:
+Add MCP with: `claude mcp add --scope user --transport stdio coinbase -- coinbase mcp`
 
-1. Deposit USD or crypto via [coinbase.com](https://www.coinbase.com) or the Coinbase mobile app. Deposits land in the **default portfolio**.
-2. If trading from a non-default portfolio, transfer funds from default using:
-   ```sh
-   coinbase transfer \
-     amount=100 currency=USD \
-     from=<default_portfolio_uuid> \
-     to=<trading_portfolio_uuid>
-   ```
-3. Verify: `coinbase balance`
+## Install agent skills
 
-### Place a market order
+Skills give your agent step-by-step guidance for common Coinbase workflows (trading, market data, watch, convert, portfolios).
 
 ```sh
-# Buy $100 of BTC at market
-coinbase orders create \
-  client_order_id=$(uuidgen) \
-  product_id=BTC-USD \
-  side=BUY \
-  type=market \
-  quote_size=100
-
-# Sell 0.5 ETH at market
-coinbase orders create \
-  client_order_id=$(uuidgen) \
-  product_id=ETH-USD \
-  side=SELL \
-  type=market \
-  base_size=0.5
-
-# Preview before sending
-coinbase orders preview \
-  product_id=BTC-USD \
-  side=BUY \
-  type=market \
-  quote_size=100
+coinbase skills add
 ```
 
-SELL market orders use `base_size` (amount of asset to sell). BUY market orders use `quote_size` (amount of USD to spend).
-
-### Manage orders
+If non-interactive, pass the directory explicitly:
 
 ```sh
-coinbase orders list status==OPEN
-coinbase orders get <order_id>
-coinbase orders cancel order_ids:='["id-1","id-2"]'
-coinbase orders edit <order_id> limit_price=50000
+coinbase skills add --dir ~/.claude/skills
 ```
 
-### Portfolios
+Skills auto-update on future `npm i -g @coinbase/coinbase-cli` upgrades.
 
-```sh
-coinbase portfolios list
-coinbase portfolios get <portfolio_uuid>
-coinbase portfolios create name="Day Trading"
-```
-
-### Convert (USDC ↔ USD, etc.)
-
-```sh
-coinbase convert quote from=USD to=USDC amount=100
-coinbase convert execute <quote_id> from=USD to=USDC
-coinbase convert get <quote_id>
-```
-
-### Transfer funds between portfolios
+## Discovery
 
 ```sh
-coinbase transfer amount=1000 currency=USD from=<src_uuid> to=<dst_uuid>
+coinbase --help                # all resources + commands
+coinbase orders --help         # actions in a resource
+coinbase orders create --template   # request body schema
 ```
 
-## Field syntax
+## Field & flag syntax
 
 | Syntax | Meaning |
 | :---- | :---- |
@@ -143,35 +83,25 @@ coinbase transfer amount=1000 currency=USD from=<src_uuid> to=<dst_uuid>
 | `key:=value` | Raw JSON body field |
 | `key==value` | Query parameter |
 | `a.b.c=value` | Nested body field |
-| `@file.json` | Body from file |
-| `-` | Body from stdin |
-
-## Flags
+| `@file.json` / `-` | Body from file / stdin |
 
 | Flag | Behavior |
 | :---- | :---- |
-| `--template` | Print request body schema, don't send |
+| `--template` | Print body schema, don't send |
 | `--dry-run` | Assemble + print request, don't send |
-| `--edit` | Open body in `$EDITOR` |
 | `--jq <expr>` | Filter JSON response |
 | `--paginate` | Auto-follow `cursor` until exhausted |
 | `-e <env>` | Override active environment |
-| `-v` | Verbose; print headers (sensitive redacted) |
+| `-v` | Verbose; print headers (redacted) |
 
-## Output
+Output: `stdout` = raw JSON (parseable), `stderr` = human status/errors. Exit `0` success, `1` error.
 
-- `stdout`: raw JSON response (default), parseable.
-- `stderr`: human status, errors, warnings.
-- Exit codes: `0` success, `1` error.
+## Journey skills (index)
 
-## Portfolio ID for spot orders (CDP-key auth)
-
-CDP API keys derive portfolio scope from the key itself — no `retail_portfolio_id` needed in the body.
-
-## MCP
-
-```sh
-claude mcp add --scope user --transport stdio coinbase -- coinbase mcp
-```
-
-29 tools generated from the spec: `coinbase_<resource>_<action>` (e.g. `coinbase_orders_create`) and top-level actions (e.g. `coinbase_balance`, `coinbase_transfer`, `coinbase_fees`), plus meta tools `coinbase_env`, `coinbase_set_env`, `coinbase_template`, `coinbase_help`.
+| Skill | Use when the user wants to… |
+| :---- | :---- |
+| `coinbase-trading` | place / preview / cancel / edit spot orders, market & limit, stop-loss |
+| `coinbase-market-data` | check prices, candles, order book, best bid/ask, ticker |
+| `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 |

package/skills/coinbase-convert/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: coinbase-convert
+description: Converts between currencies on Coinbase (e.g. USDC ↔ USD, USD ↔ a stablecoin) using the quote-then-execute flow. Use when the user wants to convert, swap stablecoins, or move between fiat and USDC. Not for buying/selling crypto assets — use `coinbase-trading` (a spot order) for that.
+requires: coinbase env configured with Trade permission (see `coinbase` skill)
+---
+
+# coinbase-convert
+
+Convert between supported currency pairs (commonly USDC ↔ USD). Convert is a distinct flow from trading — for buying/selling a crypto asset, place a spot order via `coinbase-trading` instead of converting.
+
+## Flow: quote → execute
+
+```sh
+# 1. Get a quote (returns a quote_id)
+coinbase convert quote from=USD to=USDC amount=100
+
+# 2. Execute the quote
+coinbase convert execute <quote_id> from=USD to=USDC
+
+# 3. Inspect a quote/trade
+coinbase convert get <quote_id>
+```
+
+Always quote first, surface the rate/fees to the user, and confirm before executing — `execute` is a real conversion.
+
+## Notes
+
+- `from` / `to` are currency codes (e.g. `USD`, `USDC`).
+- `amount` is denominated in the `from` currency.
+- This is the conversion product, not a market order. "Buy N USDC worth of BTC" is a spot order (`coinbase-trading`), not a convert.

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

@@ -0,0 +1,51 @@
+---
+name: coinbase-market-data
+description: Reads market data from Coinbase Advanced Trade — current prices, candles/OHLCV, order book depth, best bid/ask, ticker, and product metadata. Use when the user wants to check a price, look at a chart, see the order book, get the spread, or list tradable products. Read-only.
+requires: coinbase env configured (see `coinbase` skill)
+---
+
+# coinbase-market-data
+
+Read-only market data. All commands return JSON to stdout.
+
+## Current price / product info
+
+```sh
+coinbase products get BTC-USD
+coinbase products ticker BTC-USD                      # latest trades
+coinbase products ticker BTC-USD --jq '.trades[0].price'   # just the last price
+```
+
+Extract a bare spot price (useful when resolving relative targets):
+
+```sh
+SPOT=$(coinbase products ticker BTC-USD --jq '.trades[0].price' | tr -d '"')
+```
+
+## Candles (OHLCV)
+
+```sh
+coinbase products candles BTC-USD
+coinbase products candles BTC-USD --jq '.candles[0]'
+# narrow with query params, e.g. granularity / time range
+coinbase products candles BTC-USD granularity==ONE_HOUR
+```
+
+## Order book & spread
+
+```sh
+coinbase products book BTC-USD --jq '.pricebook'
+coinbase products best_bid_ask product_ids==BTC-USD
+```
+
+## List / discover products
+
+```sh
+coinbase products list
+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`.

package/skills/coinbase-portfolios/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: coinbase-portfolios
+description: Manages Coinbase Advanced Trade portfolios — list, get, create, edit, delete portfolios, view balances, and move funds between portfolios. Use when the user wants to see their portfolios, create a new one (e.g. "day trading"), check balances, or transfer funds between portfolios. Covers the per-portfolio API-key scoping model.
+requires: coinbase env configured (see `coinbase` skill); transfers need Transfer permission
+---
+
+# coinbase-portfolios
+
+Manage portfolios and move funds between them.
+
+## Balances
+
+```sh
+coinbase balance                       # all account balances (active portfolio)
+coinbase balance show_zero==true       # include zero-balance accounts
+```
+
+## Portfolios
+
+```sh
+coinbase portfolios list
+coinbase portfolios get <portfolio_uuid>
+coinbase portfolios create name="Day Trading"
+coinbase portfolios edit <portfolio_uuid> name="Renamed"
+coinbase portfolios delete <portfolio_uuid>
+```
+
+## 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:
+
+```sh
+coinbase env live-primary --key-file primary-key.json
+coinbase env live-trading --key-file trading-key.json
+```
+
+Switch with `coinbase env live-trading`, or per-command with `-e live-primary`.
+
+## Move funds between portfolios
+
+Switch to the SOURCE portfolio's key first, then transfer:
+
+```sh
+coinbase transfer amount=1000 currency=USD from=<src_uuid> to=<dst_uuid>
+```
+
+## Funding a fresh account
+
+The brokerage API does not buy crypto with a payment method directly. To fund for trading:
+
+1. Deposit USD or crypto via coinbase.com or the mobile app — deposits land in the **default portfolio**.
+2. If trading from a non-default portfolio, transfer from default (see above).
+3. Verify: `coinbase balance`

package/skills/coinbase-trading/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: coinbase-trading
+description: Places, previews, edits, and cancels spot orders on Coinbase Advanced Trade — market buys/sells, limit orders, stop-loss / take-profit, and order management. Use when the user wants to buy or sell crypto, place an order, set a limit or stop, or check/cancel existing orders. These are real orders.
+requires: coinbase env configured with Trade permission (see `coinbase` skill)
+---
+
+# coinbase-trading
+
+Place and manage spot orders. **These are REAL orders.** Confirm the full plan (product, side, size) with the user before placing.
+
+## Market orders
+
+Side determines which size field you use:
+- **Market BUY uses `quote_size`** (amount of quote currency, e.g. USD/USDC, to spend).
+- **Market SELL uses `base_size`** (amount of the asset to sell).
+
+`client_order_id` is auto-generated — omit it. Place market orders directly in one call; preview only for large or limit/stop orders.
+
+```sh
+# Buy $100 of BTC at market
+coinbase orders create product_id=BTC-USD side=BUY type=market quote_size=100
+
+# "Buy N USDC worth of <ASSET>" → BUY on <ASSET>-USDC with quote_size=N
+coinbase orders create product_id=BTC-USDC side=BUY type=market quote_size=1
+
+# Sell 0.5 ETH at market
+coinbase orders create product_id=ETH-USD side=SELL type=market base_size=0.5
+```
+
+**Report the result from the create response.** Do NOT automatically run `coinbase orders get <order_id>` afterward — check back with the user first; only run the confirmation `get` if they ask.
+
+## Preview (large or limit/stop orders)
+
+Skip preview for small market buys — place directly. For a large order, or any limit/stop, preview first to check fees, fill price, and slippage:
+
+```sh
+coinbase orders preview product_id=BTC-USD side=BUY type=limit base_size=0.5 limit_price=50000
+```
+
+## Limit orders (resting, server-side)
+
+```sh
+# Resting buy at a price
+coinbase orders create product_id=BTC-USD side=BUY type=limit base_size=0.01 limit_price=50000
+
+# Take-profit / sell-at-price
+coinbase orders create product_id=ETH-USD side=SELL type=limit base_size=0.5 limit_price=4000
+```
+
+## Stop orders (server-side, durable)
+
+```sh
+# Stop-loss sell
+coinbase orders create product_id=BTC-USD side=SELL type=stop_limit \
+  base_size=0.01 limit_price=48000 stop_price=49000 stop_direction=down
+```
+
+Prefer native order types — they are durable and server-side. Only use a `--until` watcher (see `coinbase-watch`) when the trigger is something a single resting order cannot express (cross-product price, spread/volume, fill sequencing).
+
+## Manage orders
+
+```sh
+coinbase orders list status==OPEN
+coinbase orders get <order_id>
+coinbase orders cancel order_ids:='["id-1","id-2"]'
+coinbase orders edit <order_id> limit_price=50000
+coinbase orders fills order_id==<order_id>
+coinbase orders close_position product_id=BTC-USD
+```
+
+## Portfolio scope
+
+CDP API keys derive portfolio scope from the key itself — no `retail_portfolio_id` needed in the body. To trade in a different portfolio, switch envs (`-e live-trading`); see `coinbase-portfolios`.

package/skills/coinbase-watch/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: coinbase-watch
+description: Watches a live Coinbase data stream and triggers an action when a condition becomes true, via the CLI's `--until` flag. Use when the user wants to "do X when price hits Y", "buy on a dip", "wait until my order fills then…", or any cross-product / spread / volume trigger that a single resting order cannot express. Places real orders when chained.
+requires: coinbase env configured with Trade permission (see `coinbase` skill); CLI lane only (not MCP)
+---
+
+# coinbase-watch (`--until`)
+
+`coinbase products ticker|book | orders list <ARGS> --until "<predicate>"` watches a live stream, blocks until the predicate is true, prints the matching event as JSON to stdout, and exits 0 (timeout → 124, permanent failure → 2). Chain an action onto it with `&&`.
+
+**Use `--until` ONLY for triggers native `orders` cannot express.** It does not replace native order types — those are durable and server-side; a `--until` watcher is a monitored, session-lived process (see Safety).
+
+## Use native `orders` (see `coinbase-trading`) for — do NOT rebuild with `--until`
+
+- Stop-loss → `type=stop_limit` sell, `stop_direction=down`
+- Take-profit / sell-at-price → `type=limit` (or `stop_limit`)
+- Triggered / breakout / dip entry on the *same* product's price → `type=stop_limit`
+- Resting buy/sell at a price → `type=limit`
+- Price ladder → several `type=limit` orders
+
+## Reach for `--until` only when a single resting order can't watch the trigger
+
+Cross-product (act on one product based on ANOTHER's price):
+```sh
+coinbase products ticker BTC-USDC ETH-USDC --until "price BTC-USDC >= 65000" --until-timeout 3600 \
+  && coinbase orders create client_order_id=$(uuidgen) product_id=ETH-USDC side=BUY type=market quote_size=50
+```
+
+Compound, multi-field / multi-product:
+```sh
+coinbase products ticker BTC-USDC ETH-USDC --until "price BTC-USDC >= 65k && price ETH-USDC <= 1500" --until-timeout 3600 \
+  && coinbase orders create client_order_id=$(uuidgen) product_id=ETH-USDC side=BUY type=market quote_size=50
+```
+
+Non-price trigger — spread / volume / 24h move:
+```sh
+# only execute when the book is tight (low slippage)
+coinbase products book BTC-USDC --until "spread <= 1" --until-timeout 600 \
+  && coinbase orders create client_order_id=$(uuidgen) product_id=BTC-USDC side=BUY type=market quote_size=50
+# enter only after a sharp 24h drawdown
+coinbase products ticker SOL-USDC --until "pct_24h <= -8" --until-timeout 86400 \
+  && coinbase orders create client_order_id=$(uuidgen) product_id=SOL-USDC side=BUY type=market quote_size=25
+```
+
+Fill / state sequencing — run the next leg only AFTER another order fills:
+```sh
+coinbase orders list --until "status == FILLED" --until-timeout 86400 \
+  && coinbase orders create client_order_id=$(uuidgen) product_id=ETH-USDC side=BUY type=market quote_size=50
+```
+
+Arbitrary "then" — the matched event is JSON on stdout; the chained action can be anything (notify, call another tool, place a *different* order), not just an order.
+
+## Predicate syntax
+
+Form: `field [product] op value`. Operators `== != > < >= <=`, combined with `&& || ( )`; numeric suffixes `k m b`. Scope to a product when watching several: `price BTC-USDC >= 65k`.
+
+**Don't memorize the fields — they're per-stream and authoritative in `--help`** (generated from the spec). Run `coinbase products ticker --help` (or `products book` / `orders list`) for the valid fields, types, and ready examples for that surface.
+
+## Safety rules
+
+- Gate every action on a match: chain with `&&` (runs only on exit 0). A timeout (124) or failure (2) must NOT trade. Always set `--until-timeout`.
+- Resolve relative targets ("3% below") from LIVE spot at arm time, and confirm the resolved absolute number with the user before arming:
+  `SPOT=$(coinbase products ticker BTC-USDC --jq '.trades[0].price' | tr -d '"')`
+- These are REAL orders. Confirm the full plan before arming; do NOT auto-run `orders get` afterward.
+- A `--until` watcher is MONITORED and session-lived, not a resting server-side order — if it stops, the trigger is gone. For anything that must survive, use a native `limit` / `stop_limit`.