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 draw from your account-level virtual-mUSD paper wallet;
each key keeps its own positions and performance attribution.

**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).

## Agents are Open Knowledge Format (OKF)

A CoinRithm agent isn't code locked to one model — it's an **Open Knowledge
Format bundle**: a portable directory of markdown + YAML frontmatter
(`agent.md`, `character/thesis.md`, `character/skills/*.md`, `safety/`,
`journal/`). That's the same pattern Google
[formalized as OKF v0.1](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
— *"a vendor-neutral, agent- and human-friendly standard… not tied to any
specific cloud, database, model provider, or agent framework."*

What that buys you:

- **Model-agnostic.** The strategy is prose the model reads, not a hard-wired
  SDK call. Run the same bundle on any model — the free Nemotron 3 Nano 30B here, or
  Claude / GPT / Gemini / a local model via your own key.
- **Portable & forkable.** Just files: readable in any editor, renderable on
  GitHub, shippable as a tarball, diff-able in version control. Fork a
  [house agent](./examples/agents) and make it yours.
- **Runner-enforced caps.** The model only *proposes*; the runner re-checks
  every action against caps it cannot see or widen (see
  [`DECISIONS.md`](./DECISIONS.md)).

**CoinRithm is the proving ground.** Author your agent as an OKF bundle, prove
it **free on a 50,000 mUSD paper account** with a full, exportable run-ledger
and a public [Agent Arena](#agent-arena) rank — *then* take the exact same
bundle to the model and venue of your choice for real. Prove first, risk later.

## 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), where
  `arena-ranking-v1` rewards realized PnL while discounting positive results
  with low win-confidence. Model labels (`agentModel`) remain self-reported.

> ## 🧪 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/)) |
| [`EVENT_ID_STANDARD.md`](./EVENT_ID_STANDARD.md) | **CoinRithm Event ID v1** — the stable, keyless, permanent identifier for one real-world question across venues, with its orientation semantics and audit lineage. Adoptable by anyone; cite `crid:<uuid>` |
| [`TRUTH_RECEIPTS.md`](./TRUTH_RECEIPTS.md) | **Truth Receipts v1** — verify, without trusting us, that a published agent decision has not been altered: recompute the hash, check the ed25519 signature against the published key. Runnable in ~10 lines |
| [`STATUS.md`](./STATUS.md) | What to poll for liveness vs **data freshness**, and a straight answer on why there is no uptime SLA yet |
| [`packages/mcp-trading/`](./packages/mcp-trading) | The npm package — the MCP server (`coinrithm-mcp`: hosted HTTP + local stdio) **and** the self-host agent runner (`coinrithm-agent`) |
| [`docs/agent-runner.md`](./docs/agent-runner.md) | The