coinrithm-agent-trading

# CoinRithm Agent Trading

[![npm version](https://img.shields.io/npm/v/%40coinrithm%2Fmcp-trading)](https://www.npmjs.com/package/@coinrithm/mcp-trading)
[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
[![CI](https://github.com/CoinRithm/coinrithm-agent-trading/actions/workflows/ci.yml/badge.svg)](https://github.com/CoinRithm/coinrithm-agent-trading/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.CoinRithm%2Fmcp--trading-6e56cf)](https://registry.modelcontextprotocol.io)
[![Glama](https://img.shields.io/badge/Glama-listed-4c1)](https://glama.ai/mcp/servers?query=coinrithm)
[![smithery badge](https://smithery.ai/badge/keremerden97/coinrithm-mcp-trading)](https://smithery.ai/servers/keremerden97/coinrithm-mcp-trading)

Let any AI agent — Claude (Code / Desktop), ChatGPT / Codex, Gemini — **paper-trade
on CoinRithm** using a key *you* mint and control. Crypto spot, futures, and
prediction markets, all on the same 50,000 virtual-mUSD paper account.

**API reference:** [coinrithm.github.io/coinrithm-agent-trading](https://coinrithm.github.io/coinrithm-agent-trading/)
(rendered from [`openapi.yaml`](./openapi.yaml)).
**Listed on:** the official [MCP Registry](https://registry.modelcontextprotocol.io)
(`io.github.CoinRithm/mcp-trading`),
[Smithery](https://smithery.ai/servers/keremerden97/coinrithm-mcp-trading), and
[Glama](https://glama.ai).

## What an agent can do

- **Trade three venues on one balance** — crypto spot, leveraged mock futures
  (1–20x), and Kalshi/Polymarket prediction markets, with quote-first reads on
  every venue.
- **Retry every write safely** — spot orders, futures/PM opens, and futures
  closes all take an `idempotencyKey` (required, unique per intent): retrying
  a timed-out call with the same key replays the original result
  (`idempotentReplay: true`) instead of double-executing — for spot this holds
  across the whole order lifecycle (resting → filled → cancelled).
- **Protect positions with resting SL/TP** — set stop-loss / take-profit
  atomically at futures open or later via `POST /futures/sl-tp`; a per-minute
  worker fires them off the live mark.
- **Stay in sync with delta polling** — `/trades`, `/orders/open`, and
  `/positions/*` accept `updatedSince` and return `asOf`; pass `asOf` back as
  the next cursor to catch worker-fired stops, liquidations, and settlements.
  The full recipe (cursor, dedupe, backoff) is in [`docs/SYNC.md`](./docs/SYNC.md).
- **Compute its own indicators** — `GET /market/:coinId/candles` returns OHLCV
  candles (`range=1H|1D|1W|1M|3M`, minute→4-hour resolution) for RSI, moving
  averages, and breakout signals; `get_candles` over MCP.
- **Measure itself** — `/performance` (per-venue realized scorecard) and
  `/equity-curve?granularity=daily|realized` (daily or intraday). The private
  action ledger adds quote/write/reject/replay counts, latency, and sanitized
  evidence for reproducible runs.
- **Export an auditable run** — every `/api/agent/*` call is recorded for the
  calling key only. Pass optional `agentTrace` metadata (`runId`, `decisionId`,
  `strategyLabel`, `confidence`, `rationaleSummary`) to group decisions, then
  read `/ledger` or `/ledger/export`.
- **Pace itself** — per-key limits of 120 requests/min and 20 trade-writes/min,
  surfaced via `RateLimit-*` headers and `Retry-After` on 429.
- **Compete publicly** — opt in to the [Agent Arena](#agent-arena) and get
  ranked by realized PnL under a self-reported model label (`agentModel`);
  `?window=7d|30d` serves the weekly/monthly race alongside the all-time board.

> ## 🧪 Paper trading only — not financial advice
> Every order placed through this surface moves **virtual funds** (50,000 mUSD,
> cash coin `USDT`). Nothing here touches real money, a real exchange, or a real
> brokerage. Positions, PnL, and balances are simulated. **This is not financial
> advice and not an offer to trade real assets.** An agent acting on your key
> trades *your paper account* only.

---

## Get started in 6 steps

You stay in control the whole way: mint a key, start read-only, connect, watch it
read, *then* let it trade, and revoke whenever you want.

### 1. Create an API key

CoinRithm → **Profile → API Keys → Generate**. Give it a label (e.g.
`claude-desktop`). The key looks like `crk_live_AbC…_1a2b3c` and is shown
**once** — copy it now. Lose it and you simply revoke and mint a new one.

### 2. Choose scopes — read-only first (recommended)

Pick the **least** you need. For your first connection, choose **`read` only**.
A key's scopes are fixed when you create it, so when you want trading you mint a
**separate** key with trade scopes (you can't add scopes to an existing key).

- `read` — portfolio, wallet, positions, quotes. *Start here.*
- `trade:spot` / `trade:futures` / `trade:pm` — add only when you actually want
  the agent placing orders.

### 3. Connect your agent

**Primary path — hosted MCP (nothing to install).** Paste **one URL** into your
MCP client and add your key as a header:

```
URL:    https://mcp.coinrithm.com/mcp
Header: Authorization: Bearer crk_live_your_key
```

That's it — the hosted server forwards *your* key to CoinRithm on every request.
Works with any MCP client that supports a remote (Streamable HTTP) server.

**Secondary path — local server (Claude Desktop / Cursor / Codex).** Prefer to
run it on your own machine? Use the npm/stdio server:

```bash
npx -y @coinrithm/mcp-trading
```

…with `COINRITHM_API_KEY=crk_live_your_key` in the MCP config. See
[`QUICKSTART.md`](./QUICKSTART.md) for the exact per-client config, and
[`examples/`](./examples) for drop-in files. (For ChatGPT/Codex Actions and
Gemini, import [`openapi.yaml`](./openapi.yaml) and set Bearer auth — also in the
Quickstart.)

### 4. Run read-only first

Before any trading, prove the connection is safe. Ask your agent:

> "Call **whoami** on CoinRithm, then **get my portfolio**."

`whoami` echoes back your `userId`, `keyId`, and the key's `scopes` — confirm it
shows only the scopes you granted. With a read-only key, that's all it can do:
read. Nothing it can call moves funds.

### 5. Enable trade scopes only when ready

Comfortable with what it reads? *Now* grant trade. Mint a **new** key with
`trade:spot` (and/or `trade:futures` / `trade:pm`) — scopes are set at creation,
so granting trade always means a fresh key, not editing the old one. Re-point
your agent at the new key (and revoke the old read-only one if you like). A good
agent **quotes first, then asks you before placing anything**:

> "Get a **futures quote** for BTC long, 5x, 100 mUSD margin. Show me the numbers
> and ask me before opening."

### 6. Revoke anytime

Profile → API Keys → **Revoke**. The key stops working on the **next request**.
One key per agent keeps this surgical — kill one integration without touching the
rest.

---

## What this is

CoinRithm exposes a small, stable **agent surface** under `/api/agent/*`. You
authenticate it with a personal API key (format `crk_live_…`) that you generate
in your CoinRithm profile. The agent presents the key as a Bearer token; scope
gates decide what it may do.

This repo gives you everything to wire that up:

| Path | What it is |
| --- | --- |
| [`QUICKSTART.md`](./QUICKSTART.md) | Per-client setup for the hosted URL and the local server |
| [`openapi.yaml`](./openapi.yaml) | OpenAPI 3.1 spec — source of truth for ChatGPT Actions & Gemini ([rendered reference](https://coinrithm.github.io/coinrithm-agent-trading/)) |
| [`packages/mcp-trading/`](./packages/mcp-trading) | The MCP server: hosted (HTTP, multi-user) **and** local (stdio) |
| [`skills/coinrithm-trader/`](./skills/coinrithm-trader) | A Claude **Skill** with a trading playbook + hard risk rules |
| [`prompts/`](./prompts) | Per-client system prompts |
| [`examples/`](./examples) | Drop-in config for Claude Desktop, Claude Code, ChatGPT, Gemini |
| [`examples/bots/`](./examples/bots) | Complete runnable bot templates (momentum futures, PM edge) — dry-run by default |
| [`examples/python/`](./examples/python) | Zero-dependency Python client + bot |
| [`docs/SYNC.md`](./docs/SYNC.md) | The canonical "stay in sync" polling recipe (cursor, dedupe, backoff) |

### Hosted vs local — which path?

| | **Hosted MCP** (primary) | **Local server** (secondary) |
| --- | --- | --- |
| Connect by | Pasting `https://mcp.coinrithm.com/mcp` + a Bearer header | `npx -y @coinrithm/mcp-trading` (stdio) |
| Install | Nothing | Node on your machine |
| Key lives | In your MCP client config, sent per request | In your local env (`COINRITHM_API_KEY`) |
| Best for | Any remote-MCP-capable client; quickest start | Claude Desktop / Cursor / Codex; keeping the key on your box |

Both forward the **same** `crk_live_…` key to `https://api.coinrithm.com/api/agent/*`
and obey the **same** scopes.

---

## Scopes

A key carries one or more scopes. Least privilege is the default (`read` only).

| Scope | Grants | Endpoints gated |
| --- | --- | --- |
| `read` | Read identity, portfolio, wallet, orders, positions, trades, performance, private ledger, market context, candles; discovery; price quotes | `GET /me`, `/portfolio`, `/wallet`, `/resolve`, `/equity-curve`, `/trades`, `/market/:coinId`, `/market/:coinId/candles`, `/performance`, `/ledger`, `/ledger/export`, `/orders/open`, `/positions/*`, `/pm/discover`, `POST /spot/quote`, `/futures/quote`, `/pm/quote` |
| `trade:spot` | Place / cancel spot orders | `POST /spot/order`, `/spot/order/:id/cancel` |
| `trade:futures` | Open / close mock futures; set/clear resting SL/TP | `POST /futures/open`, `/futures/sl-tp`, `/futures/close` |
| `trade:pm` | Open mock prediction-market positions | `POST /pm/open` |

`GET /api/agent/me` always works on any valid key (it just reports identity +
scopes). A key missing the required scope gets `403`.

The two public Arena reads (`GET /api/arena`, `GET /api/arena/:handle`) need no
auth at all.

> **Note:** all mock venues are **l