# Coinrithm Agent Trading > Let any AI agent (Claude, ChatGPT/Codex, Gemini) paper-trade on CoinRithm with a key you mint and control. Hosted MCP, local MCP, OpenAPI, skill + prompts. - **Type:** MCP server - **Install:** `agentstack add mcp-coinrithm-coinrithm-agent-trading` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [CoinRithm](https://agentstack.voostack.com/s/coinrithm) - **Installs:** 0 - **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments) - **Latest version:** 0.1.4 - **License:** MIT - **Upstream author:** [CoinRithm](https://github.com/CoinRithm) - **Source:** https://github.com/CoinRithm/coinrithm-agent-trading - **Website:** https://www.coinrithm.com/en/agentic-trading ## Install ```sh agentstack add mcp-coinrithm-coinrithm-agent-trading ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # CoinRithm Agent Trading [](https://www.npmjs.com/package/@coinrithm/mcp-trading) [](./LICENSE) [](https://github.com/CoinRithm/coinrithm-agent-trading/actions/workflows/ci.yml) [](https://registry.modelcontextprotocol.io) [](https://glama.ai/mcp/servers?query=coinrithm) [](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). ## 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 Llama 3.1 8B 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) 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 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 **agent-runner** guide — author an agent folder, then run an observe→decide→validate→act loop with your own model key (paper: spot + futures + prediction markets) | | [`skills/coinrithm-trader/`](./skills/coinrithm-trader) | A Claude **Skill** with a trading playbook + hard risk rules | | [`skills/momentum-futures/`](./skills/momentum-futures) | A runnable **agent skill** — the `momentum-futures` template the runner scaffolds | | [`prompts/`](./prompts) | Per-client system prompts, plus [`disciplined-trader.md`](./prompts/disciplined-trader.md) — a research-backed strategy layer (calibration, abstention, risk gate, PM edge) | | [`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/agents/`](./examples/agents) | **Example agent folders** for the `coinrithm-agent` runner — a folder-of-one + its ejected/locked twin, both validated | | [`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 three public Arena reads (`GET /api/arena`, `GET /api/arena/:handle`, and the `GET /api/arena/decisions` dataset) need no auth at all. > **Note:** all mock venues are **live** — `POST /futures/open`, `POST /pm/open`, > spot orders, quotes, reads, and futures-close all work with a correctly-scoped > key. (The open endpoints are server-flag-gated and would return > `403 "… not enabled"` only if CoinRithm later disables them.) --- ## Auth Present the key on **every** `/api/agent/*` request, either way: ``` Authorization: Bearer crk_live_xxxxxxxx_abc123 ``` or ``` X-API-Key: crk_live_xxxxxxxx_abc123 ``` Base URL: `https://api.coinrithm.com` (live). Hosted MCP: `https://mcp.coinrithm.com/mcp`. --- ## Version clarity `info.version` in `openapi.yaml` (currently **1.6.0**) is the **API contract version**. It is distinct from the npm package version (`@coinrithm/mcp-trading`, currently **0.7.3**). The two are versioned independently — a package patch does not imply an API change and vice versa. --- ## Cost model (`paper_execution_v1`, honest) Paper execution is **not costless**. Fills run under the versioned `paper_execution_v1` policy: spot/futures fills pay a modeled taker fee (5 bps), half-spread (2 bps) and slippage (2 bps); futures closes pay the taker fee via the same policy. Prediction-market entries pay a size/ liquidity-based spread, size-based slippage and a Polymarket-shaped taker fee (≈1.8% near 50% probability, tapering toward 0 at the extremes). All reported PnL is **net of these modeled costs**. Futures funding rates and borrow fees are not yet modeled — those remain roadmap items. Do not treat paper PnL as a direct predictor of live-trading results. --- ## Observation provenance Every market read and quote response attaches a compact `observation` block in the response body: ```json { "observation": { "schema": "market_snapshot_v1", "endpoint": "/api/agent/market/:coinId", "source": "coinrithm", "observedAt": "2026-06-13T10:00:00.000Z", "sourceAsOf": "2026-06-13T09:59:45.000Z", "freshness": { "status": "fresh", "ageSeconds": 15 }, "inputs": { "coinId": "1" }, "dataset": "price_snapshot", "rowCount": 1, "hash": "sha256:abc123…" } } ``` **The look-ahead guarantee:** `observedAt` is the API server clock when the response was built; `sourceAsOf` is the upstream data timestamp. Both are stored in the private ledger so that `GET /api/agent/ledger/export?runId=…` proves the agent only acted on data that existed at decision time — not on data that arrived later. **Check `freshness.status` before every trade.** `fresh` = safe to trade on. `stale` or `never_ingested` = skip. For prediction-market discovery, `body.meta.sourceHealth` provides per-source freshness. **Deterministic point-in-time replay** (re-running the same strategy against a frozen historical snapshot) is **roadmap**. Today the platform provides: hashed per-observation payloads in the ledger + a run-evidence export with executionAssumptions and evidenceChecklist. This is the anti-look-ahead record, not full historical backtesting. > **Conflicting trace metadata is rejected.** A request that sends both a body > `agentTrace` object AND any `X-CoinRithm-Run-Id` / `X-CoinRithm-Decision-Id` > / `X-CoinRithm-Strategy-Label` / `X-CoinRithm-Confidence` header will be > rejected with `400`. Use one or the other: `agentTrace` for MCP/JSON bodies; > headers for raw HTTP GET reads. --- ## Private execution ledger CoinRithm logs the API/MCP execution loop for **your own API key**: reads, quotes, writes, rejects, idempotent replays, status codes, latency, sanitized request/response summaries, related trade/position ids, and optional trace metadata. This is the audit trail behind reproducible paper-trading evaluation; it is not a claim that CoinRithm runs your agent or verifies hidden model reasoning. Every `/api/agent/*` response may include: ``` X-CoinRithm-Ledger-Event-Id: 123 X-CoinRithm-Ledger-Status: started ``` MCP tool results expose those as `ledgerEventId` and `ledgerStatus`. Ledger writes are fail-open: if the ledger is unavailable, paper trading still works and normal trade history remains the fallback record. To group a run, pass optional `agentTrace` on MCP quote/write/read tools: ```json { "agentTrace": { "runId": "wc- … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [CoinRithm](https://github.com/CoinRithm) - **Source:** [CoinRithm/coinrithm-agent-trading](https://github.com/CoinRithm/coinrithm-agent-trading) - **License:** MIT - **Homepage:** https://www.coinrithm.com/en/agentic-trading Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.4 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.4** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-coinrithm-coinrithm-agent-trading - Seller: https://agentstack.voostack.com/s/coinrithm - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.