Coinbase Grid Trader

For Claude: How to Use This Skill

Skill instructions are preloaded in context when this skill is active. Do not perform filesystem searches or tool-driven exploration to rediscover them; use the guidance below directly.

Automated grid trading bot for Coinbase Exchange, powered by the Seren Gateway.

On Invoke

Immediately run a dry-run grid simulation without asking. Do not present a menu of modes. Execute:

cd ~/.config/seren/skills/grid-trader && source .venv/bin/activate && python3 scripts/agent.py --config config.json

Display the full dry-run results to the user. Only after results are displayed, present available next steps (live mode with --allow-live). If the user explicitly requests a specific mode in their invocation message, run that mode instead.

What This Skill Provides

• Automated Coinbase Exchange grid trading with dry-run and live modes
• Price-range based grid generation with risk controls
• JSONL logs for setup, orders, fills, positions, and errors
• MCP-native SerenDB persistence for sessions, events, orders, fills, and position snapshots

What is Grid Trading?

Grid trading places a ladder of buy orders below the market price and sell orders above it. When a buy fills, a sell is placed one spacing above it. When a sell fills, a buy is placed one spacing below. Profit accumulates through price oscillation within the range — no direction prediction required.

API Key Setup

Before running this skill, check for an existing Seren API key in this order:

1. Seren Desktop auth — if the skill is running inside Seren Desktop, the runtime injects API_KEY automatically. Check: echo $API_KEY. If set, no further action is needed.
2. Existing .env file — check if SEREN_API_KEY is already set in the skill's .env file. If set, no further action is needed.
3. Shell environment — check if SEREN_API_KEY is exported in the current shell. If set, no further action is needed.

Only if none of the above are set, register a new agent account:

curl -sS -X POST "https://api.serendb.com/auth/agent" \
  -H "Content-Type: application/json" \
  -d '{"name":"grid-trader"}'

Extract the API key from the response at .data.agent.api_key — this key is shown only once. Write it to the skill's .env file:

SEREN_API_KEY=<the-returned-key>

Verify:

curl -sS "https://api.serendb.com/auth/me" \
  -H "Authorization: Bearer $SEREN_API_KEY"

Do not create a new account if a key already exists. Creating a duplicate account results in a $0-balance key that overrides the user's funded account.

Reference: https://docs.serendb.com/skills.md

Setup

1. Configure Coinbase publisher credentials in Seren Desktop Settings → Publisher MCPs (desktop sidecar/keychain flow)
2. Copy .env.example to .env and set SEREN_API_KEY (SEREN_DESKTOP_PUBLISHER_AUTH=true is recommended)
3. Optional legacy fallback: set SEREN_DESKTOP_PUBLISHER_AUTH=false and fill CB_ACCESS_* values
4. Copy config.example.json to config.json and configure your grid parameters
5. Install dependencies: pip install -r requirements.txt
6. Run: python scripts/agent.py

Trade Execution Contract

When the user says sell, close, exit, unwind, or flatten, treat that as an immediate operator instruction to stop new grid entries and cancel open Coinbase orders for the configured pair. If the user did not identify which pair or campaign to stop, ask only the minimum clarifying question needed to identify it.

Pre-Trade Checklist

Before any live start --allow-live run:

1. Fetch current balances and the latest market price for the configured pair.
2. Verify Coinbase publisher credentials and SEREN_API_KEY are loaded.
3. Verify the configured grid range, quote reserve, and drawdown caps still fit the account.
4. If any credential, dependency, or market probe fails, stop here and fail closed instead of placing orders.

Dependency Validation

Dependency validation is required before live trading. Verify SEREN_API_KEY, the Coinbase publisher credentials, and Python dependencies from requirements.txt are installed and loaded. If credentials are missing, the pair cannot be queried, or the publisher is unavailable, the runtime must stop with an error instead of submitting orders.

Live Safety Opt-In

Default mode is dry-run. Live trading requires:

• python scripts/agent.py start --config config.json --allow-live
• the normal startup risk checks to pass

The --allow-live flag is a startup-only opt-in for that process. It is not a per-order approval prompt.

Emergency Exit Path

To stop trading immediately, run python scripts/agent.py stop --config config.json. The stop path cancels all open orders for the configured pair, clears the active grid state, and leaves held spot inventory untouched until the operator chooses how to liquidate it.

SerenDB Persistence (MCP-native)

Set these optional environment variables in .env:

• SERENDB_PROJECT_NAME (default auto target: coinbase)
• SERENDB_DATABASE (default auto target: coinbase)
• SERENDB_BRANCH (optional)
• SERENDB_REGION (default: aws-us-east-1)
• SERENDB_AUTO_CREATE (default: true)
• SEREN_MCP_COMMAND (default: seren-mcp)

Persistence is best-effort: if SerenDB/MCP is unavailable, trading still runs and logs locally.

Configuration

See config.example.json for available parameters including grid spacing, order size, and trading pair selection.