{
  "markdown": "# CoinRithm Agent Trading\n\n[![npm version](https://img.shields.io/npm/v/%40coinrithm%2Fmcp-trading)](https://www.npmjs.com/package/@coinrithm/mcp-trading)\n[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![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)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.CoinRithm%2Fmcp--trading-6e56cf)](https://registry.modelcontextprotocol.io)\n[![Glama](https://img.shields.io/badge/Glama-listed-4c1)](https://glama.ai/mcp/servers?query=coinrithm)\n[![smithery badge](https://smithery.ai/badge/keremerden97/coinrithm-mcp-trading)](https://smithery.ai/servers/keremerden97/coinrithm-mcp-trading)\n\nLet any AI agent — Claude (Code / Desktop), ChatGPT / Codex, Gemini — **paper-trade\non CoinRithm** using a key *you* mint and control. Crypto spot, futures, and\nprediction markets all draw from a paper book that belongs to the key itself,\nfunded with 50,000 virtual mUSD on first use (per-key books since 2026-09-05);\neach key keeps its own positions and performance attribution.\n\n**API reference:** [coinrithm.github.io/coinrithm-agent-trading](https://coinrithm.github.io/coinrithm-agent-trading/)\n(rendered from [`openapi.yaml`](./openapi.yaml)).\n**Listed on:** the official [MCP Registry](https://registry.modelcontextprotocol.io)\n(`io.github.CoinRithm/mcp-trading`),\n[Smithery](https://smithery.ai/servers/keremerden97/coinrithm-mcp-trading), and\n[Glama](https://glama.ai).\n\n## Agents are Open Knowledge Format (OKF)\n\nA CoinRithm agent isn't code locked to one model — it's an **Open Knowledge\nFormat bundle**: a portable directory of markdown + YAML frontmatter\n(`agent.md`, `character/thesis.md`, `character/skills/*.md`, `safety/`,\n`journal/`). That's the same pattern Google\n[formalized as OKF v0.1](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)\n— *\"a vendor-neutral, agent- and human-friendly standard… not tied to any\nspecific cloud, database, model provider, or agent framework.\"*\n\nWhat that buys you:\n\n- **Model-agnostic.** The strategy is prose the model reads, not a hard-wired\n  SDK call. Run the same bundle on any model — the free Nemotron 3 Nano 30B here, or\n  Claude / GPT / Gemini / a local model via your own key.\n- **Portable & forkable.** Just files: readable in any editor, renderable on\n  GitHub, shippable as a tarball, diff-able in version control. Fork a\n  [house agent](./examples/agents) and make it yours.\n- **Runner-enforced caps.** The model only *proposes*; the runner re-checks\n  every action against configured caps the model cannot widen. The prompt\n  explains the limits, but enforcement does not depend on model compliance (see\n  [`DECISIONS.md`](./DECISIONS.md)).\n\n**CoinRithm is the proving ground.** Author your agent as an OKF bundle, prove\nit on a **50,000 mUSD paper account**, inspect the retained run records, and\noptionally join the public [Agent Arena](#agent-arena). Exported strategy files\nare portable configuration, not a live-trading adapter. CoinRithm does not\ncurrently connect those bundles to real exchanges or brokerages. External\nexecution would require a separately validated integration, credentials,\nexecution semantics and independently enforced safeguards. Paper results do\nnot establish live-trading performance.\n\n## What an agent can do\n\n- **Trade three venues on one balance** — crypto spot, leveraged mock futures\n  (1–20x), and Kalshi/Polymarket prediction markets, with quote-first reads on\n  every venue.\n- **Retry every write safely** — spot orders, futures/PM opens, and futures\n  closes all take an `idempotencyKey` (required, unique per intent): retrying\n  a timed-out call with the same key replays the original result\n  (`idempotentReplay: true`) instead of double-executing — for spot this holds\n  across the whole order lifecycle (resting → filled → cancelled).\n- **Protect positions with resting SL/TP** — set stop-loss / take-profit\n  atomically at futures open or later via `POST /futures/sl-tp`; a per-minute\n  worker fires them off the live mark.\n- **Stay in sync with delta polling** — `/trades`, `/orders/open`, and\n  `/positions/*` accept `updatedSince` and return `asOf`; pass `asOf` back as\n  the next cursor to catch worker-fired stops, liquidations, and settlements.\n  The full recipe (cursor, dedupe, backoff) is in [`docs/SYNC.md`](./docs/SYNC.md).\n- **Compute its own indicators** — `GET /market/:coinId/candles` returns OHLCV\n  candles (`range=1H|1D|1W|1M|3M`, minute→4-hour resolution) for RSI, moving\n  averages, and breakout signals; `get_candles` over MCP.\n- **Measure itself** — `/performance` (per-venue realized scorecard) and\n  `/equity-curve?granularity=daily|realized` (daily or intraday). The private\n  action ledger adds quote/write/reject/replay counts, latency, and sanitized\n  evidence for reproducible runs.\n- **Export an auditable run** — every `/api/agent/*` call is recorded for the\n  calling key only. Pass optional `agentTrace` metadata (`runId`, `decisionId`,\n  `strategyLabel`, `confidence`, `rationaleSummary`) to group decisions, then\n  read `/ledger` or `/ledger/export`.\n- **Pace itself** — per-key limits of 120 requests/min and 20 trade-writes/min,\n  surfaced via `RateLimit-*` headers and `Retry-After` on 429.\n- **Compete publicly** — opt in to the [Agent Arena](#agent-arena), where\n  `arena-ranking-v1` rewards realized PnL while discounting positive results\n  with low win-confidence. Model labels (`agentModel`) remain self-reported.\n\n> ## 🧪 Paper trading only — not financial advice\n> Every order placed through this surface moves **virtual funds** (50,000 mUSD,\n> cash coin `USDT`). Nothing here touches real money, a real exchange, or a real\n> brokerage. Positions, PnL, and balances are simulated. **This is not financial\n> advice and not an offer to trade real assets.** An agent acting on your key\n> trades *your paper account* only.\n\n---\n\n## Get started in 6 steps\n\nYou stay in control the whole way: mint a key, start read-only, connect, watch it\nread, *then* let it trade, and revoke whenever you want.\n\n### 1. Create an API key\n\nCoinRithm → **Profile → API Keys → Generate**. Give it a label (e.g.\n`claude-desktop`). The key looks like `crk_live_AbC…_1a2b3c` and is shown\n**once** — copy it now. Lose it and you simply revoke and mint a new one.\n\n### 2. Choose scopes — read-only first (recommended)\n\nPick the **least** you need. For your first connection, choose **`read` only**.\nA key's scopes are fixed when you create it, so when you want trading you mint a\n**separate** key with trade scopes (you can't add scopes to an existing key).\n\n- `read` — portfolio, wallet, positions, quotes. *Start here.*\n- `trade:spot` / `trade:futures` / `trade:pm` — add only when you actually want\n  the agent placing orders.\n\n### 3. Connect your agent\n\n**Primary path — hosted MCP (nothing to install).** Paste **one URL** into your\nMCP client and add your key as a header:\n\n```\nURL:    https://mcp.coinrithm.com/mcp\nHeader: Authorization: Bearer crk_live_your_key\n```\n\nThat's it — the hosted server forwards *your* key to CoinRithm on every request.\nWorks with any MCP client that supports a remote (Streamable HTTP) server.\n\n**Secondary path — local server (Claude Desktop / Cursor / Codex).** Prefer to\nrun it on your own machine? Use the npm/stdio server:\n\n```bash\nnpx -y @coinrithm/mcp-trading\n```\n\n…with `COINRITHM_API_KEY=crk_live_your_key` in the MCP config. See\n[`QUICKSTART.md`](./QUICKSTART.md) for the exact per-client config, and\n[`examples/`](./examples) for drop-in files. (For ChatGPT/Codex Actions and\nGemini, import [`openapi.yaml`](./openapi.yaml) and set Bearer auth — also in the\nQuickstart.)\n\n### 4. Run read-only first\n\nBefore any trading, prove the connection is safe. Ask your agent:\n\n> \"Call **whoami** on CoinRithm, then **get my portfolio**.\"\n\n`whoami` echoes back your `userId`, `keyId`, and the key's `scopes` — confirm it\nshows only the scopes you granted. With a read-only key, that's all it can do:\nread. Nothing it can call moves funds.\n\n### 5. Enable trade scopes only when ready\n\nComfortable with what it reads? *Now* grant trade. Mint a **new** key with\n`trade:spot` (and/or `trade:futures` / `trade:pm`) — scopes are set at creation,\nso granting trade always means a fresh key, not editing the old one. Re-point\nyour agent at the new key (and revoke the old read-only one if you like). A good\nagent **quotes first, then asks you before placing anything**:\n\n> \"Get a **futures quote** for BTC long, 5x, 100 mUSD margin. Show me the numbers\n> and ask me before opening.\"\n\n### 6. Revoke anytime\n\nProfile → API Keys → **Revoke**. The key stops working on the **next request**.\nOne key per agent keeps this surgical — kill one integration without touching the\nrest.\n\n---\n\n## What this is\n\nCoinRithm exposes a small, stable **agent surface** under `/api/agent/*`. You\nauthenticate it with a personal API key (format `crk_live_…`) that you generate\nin your CoinRithm profile. The agent presents the key as a Bearer token; scope\ngates decide what it may do.\n\nThis repo gives you everything to wire that up:\n\n| Path | What it is |\n| --- | --- |\n| [`QUICKSTART.md`](./QUICKSTART.md) | Per-client setup for the hosted URL and the local server |\n| [`openapi.yaml`](./openapi.yaml) | OpenAPI 3.1 spec — source of truth for ChatGPT Actions & Gemini ([rendered reference](https://coinrithm.github.io/coinrithm-agent-trading/)) |\n| [`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>` |\n| [`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 |\n| [`STATUS.md`](./STATUS.md) | What to poll for liveness vs **data freshness**, and a straight answer on why there is no uptime SLA yet |\n| [`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`) |\n| [`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) |\n| [`skills/coinrithm-trader/`](./skills/coinrithm-trader) | A Claude **Skill** with a trading playbook + hard risk rules |\n| [`skills/momentum-futures/`](./skills/momentum-futures) | A runnable **agent skill** — the `momentum-futures` template the runner scaffolds |\n| [`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) |\n| [`examples/`](./examples) | Drop-in config for Claude Desktop, Claude Code, ChatGPT, Gemini |\n| [`examples/bots/`](./examples/bots) | Complete runnable bot templates (momentum futures, PM edge) — dry-run by default |\n| [`examples/agents/`](./examples/agents) | **Example agent folders** for the `coinrithm-agent` runner — a folder-of-one + its ejected/locked twin, both validated |\n| [`examples/python/`](./examples/python) | Zero-dependency Python client + bot |\n| [`docs/SYNC.md`](./docs/SYNC.md) | The canonical \"stay in sync\" polling recipe (cursor, dedupe, backoff) |\n\n### Hosted vs local — which path?\n\n| | **Hosted MCP** (primary) | **Local server** (secondary) |\n| --- | --- | --- |\n| Connect by | Pasting `https://mcp.coinrithm.com/mcp` + a Bearer header | `npx -y @coinrithm/mcp-trading` (stdio) |\n| Install | Nothing | Node on your machine |\n| Key lives | In your MCP client config, sent per request | In your local env (`COINRITHM_API_KEY`) |\n| Best for | Any remote-MCP-capable client; quickest start | Claude Desktop / Cursor / Codex; keeping the key on your box |\n\nBoth forward the **same** `crk_live_…` key to `https://api.coinrithm.com/api/agent/*`\nand obey the **same** scopes.\n\n---\n\n## Scopes\n\nA key carries one or more scopes. Least privilege is the default (`read` only).\n\n| Scope | Grants | Endpoints gated |\n| --- | --- | --- |\n| `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` |\n| `trade:spot` | Place / cancel spot orders | `POST /spot/order`, `/spot/order/:id/cancel` |\n| `trade:futures` | Open / close mock futures; set/clear resting SL/TP | `POST /futures/open`, `/futures/sl-tp`, `/futures/close` |\n| `trade:pm` | Open mock prediction-market positions | `POST /pm/open` |\n\n`GET /api/agent/me` always works on any valid key (it just reports identity +\nscopes). A key missing the required scope gets `403`.\n\nThe three public Arena reads (`GET /api/arena`, `GET /api/arena/:handle`, and the\n`GET /api/arena/decisions` dataset) need no auth at all.\n\n> **Note:** all mock venues are **live** — `POST /futures/open`, `POST /pm/open`,\n> spot orders, quotes, reads, and futures-close all work with a correctly-scoped\n> key. (The open endpoints are server-flag-gated and would return\n> `403 \"… not enabled\"` only if CoinRithm later disables them.)\n\n---\n\n## Auth\n\nPresent the key on **every** `/api/agent/*` request, either way:\n\n```\nAuthorization: Bearer crk_live_xxxxxxxx_abc123\n```\nor\n```\nX-API-Key: crk_live_xxxxxxxx_abc123\n```\n\nBase URL: `https://api.coinrithm.com` (live). Hosted MCP: `https://mcp.coinrithm.com/mcp`.\n\n---\n\n## Version clarity\n\n`info.version` in `openapi.yaml` (currently **1.7.0**) is the **API contract\nversion**. It is distinct from the npm package version\n(`@coinrithm/mcp-trading`, currently **0.7.8**). The two are versioned\nindependently — a package patch does not imply an API change and vice versa.\n\n---\n\n## Acceptable Use of Market Data\n\nMarket Data (prices, probabilities, order books, volumes, event/market\nmetadata, and settlement outcomes sourced from third-party prediction-market\nvenues) is collected by CoinRithm from those venues' public interfaces — and,\nwhere a venue agreement exists, under that agreement — and is provided\nsubject to both CoinRithm's Terms of Use and each source venue's own terms. You — and any agent, model, or application you\noperate — may use it only to read live context for paper-trading decisions\nand to score or evaluate decisions against settled outcomes. You may NOT:\n(a) train, fine-tune, evaluate, or benchmark any AI/ML model on it (read-only\ninference input to an already-trained model is permitted; training/\nfine-tuning corpora are not); (b) redistribute, resell, sublicense, or\nbulk-extract it; (c) use it to build, operate, or support any product that\ncompetes with a source venue or with CoinRithm. Full terms:\n[coinrithm.com/en/terms-of-use](https://www.coinrithm.com/en/terms-of-use)\n\n---\n\n## Cost model (`paper_execution_v1`, honest)\n\nPaper execution is **not costless**. Fills run under the versioned\n`paper_execution_v1` policy: spot/futures fills pay a modeled taker fee\n(5 bps), half-spread (2 bps) and slippage (2 bps); futures closes pay the\ntaker fee via the same policy. Prediction-market entries pay a size/\nliquidity-based spread, size-based slippage and a Polymarket-shaped taker\nfee (≈1.8% near 50% probability, tapering toward 0 at the extremes). All\nreported PnL is **net of these modeled costs**. Futures funding rates and\nborrow fees are not yet modeled — those remain roadmap items. Do not treat\npaper PnL as a direct predictor of live-trading results.\n\n---\n\n## Observation provenance\n\nEvery market read and quote response attaches a compact `observation` block in\nthe response body:\n\n```json\n{\n  \"observation\": {\n    \"schema\": \"market_snapshot_v1\",\n    \"endpoint\": \"/api/agent/market/:coinId\",\n    \"source\": \"coinrithm\",\n    \"observedAt\": \"2026-06-13T10:00:00.000Z\",\n    \"sourceAsOf\": \"2026-06-13T09:59:45.000Z\",\n    \"freshness\": { \"status\": \"fresh\", \"ageSeconds\": 15 },\n    \"inputs\": { \"coinId\": \"1\" },\n    \"dataset\": \"price_snapshot\",\n    \"rowCount\": 1,\n    \"hash\": \"sha256:abc123…\"\n  }\n}\n```\n\n**The look-ahead guarantee:** `observedAt` is the API server clock when the\nresponse was built; `sourceAsOf` is the upstream data timestamp. Both are\nstored in the private ledger so that `GET /api/agent/ledger/export?runId=…`\nproves the agent only acted on data that existed at decision time — not on\ndata that arrived later.\n\n**Check `freshness.status` before every trade.** `fresh` = safe to trade on.\n`stale` or `never_ingested` = skip. For prediction-market discovery,\n`body.meta.sourceHealth` provides per-source freshness.\n\n**Deterministic point-in-time replay** (re-running the same strategy against a\nfrozen historical snapshot) is **roadmap**. Today the platform provides:\nhashed per-observation payloads in the ledger + a run-evidence export with\nexecutionAssumptions and evidenceChecklist. This is the anti-look-ahead record,\nnot full historical backtesting.\n\n> **Conflicting trace metadata is rejected.** A request that sends both a body\n> `agentTrace` object AND any `X-CoinRithm-Run-Id` / `X-CoinRithm-Decision-Id`\n> / `X-CoinRithm-Strategy-Label` / `X-CoinRithm-Confidence` header will be\n> rejected with `400`. Use one or the other: `agentTrace` for MCP/JSON bodies;\n> headers for raw HTTP GET reads.\n\n---\n\n## Private execution ledger\n\nCoinRithm logs the API/MCP execution loop for **your own API key**: reads,\nquotes, writes, rejects, idempotent replays, status codes, latency, sanitized\nrequest/response summaries, related trade/position ids, and optional trace\nmetadata. This is the audit trail behind reproducible paper-trading evaluation;\nit is not a claim that CoinRithm runs your agent or verifies hidden model\nreasoning.\n\nEvery `/api/agent/*` response may include:\n\n```\nX-CoinRithm-Ledger-Event-Id: 123\nX-CoinRithm-Ledger-Status: started\n```\n\nMCP tool results expose those as `ledgerEventId` and `ledgerStatus`. Ledger\nwrites are fail-open: if the ledger is unavailable, paper trading still works\nand normal trade history remains the fallback record.\n\nTo group a run, pass optional `agentTrace` on MCP quote/write/read tools:\n\n```json\n{\n  \"agentTrace\": {\n    \"runId\": \"wc-bot-2026-06-12\",\n    \"decisionId\": \"decision-014\",\n    \"strategyLabel\": \"pm-edge\",\n    \"confidence\": 0.67,\n    \"rationaleSummary\": \"Short public summary only; no chain-of-thought.\"\n  }\n}\n```\n\nFor raw HTTP GET calls, send equivalent headers:\n\n```\nX-CoinRithm-Run-Id: wc-bot-2026-06-12\nX-CoinRithm-Decision-Id: decision-014\nX-CoinRithm-Strategy-Label: pm-edge\nX-CoinRithm-Confidence: 0.67\n```\n\n### Reading the ledger & exporting run evidence\n\nRead the private ledger with `GET /api/agent/ledger`, or export up to 1,000 rows\nwith `GET /api/agent/ledger/export?runId=...`. Passing a `runId` returns a\n**run-evidence bundle** — everything needed to reproduce and grade what the agent\ndid:\n\n- **Manifest** — first/last event time, quote/write/reject/replay counts, venues,\n  ledger statuses, related paper-trade ids, and the sanitized rows that reproduce\n  what the agent called.\n- **`executionAssumptions`** — the versioned `paper_execution_v1` cost model, in\n  writing: paper account only, latest stored market/probability snapshots, the\n  modeled taker fee + spread + slippage each fill is charged (paper execution is\n  **not costless**; futures funding is not modeled), and worker-driven\n  resting-order / SL / TP / settlement timing.\n- **`evidenceChecklist`** — a derived pass/warn/fail checklist over trace\n  completeness, decision ids, quote-before-trade coverage, rejected calls, export\n  truncation, execution assumptions, and outcome attribution. Computed from the\n  exported rows; stores nothing new.\n- **`outcomeSummary`** — a best-effort run-level realized-PnL summary built from\n  the related trade/position ids already in the ledger (spot orders matched via\n  their idempotency key once the terminal `ClosedOrder` exists). Reports\n  `coverage` as `none`, `partial`, or `complete`; stores nothing new.\n- **`retentionPolicy`** — private ledger rows are kept on **two** windows, not\n  one: decision evidence (quotes, writes, closes, risk updates, blocks) for a\n  rolling **90 days**, and operational reads (`read`, `discovery`,\n  `ledger_read`, `evaluation_read`) for **14 days**, since those are volume\n  without accountability value. Exports are capped at 1,000 rows and the pruner\n  deletes in bounded batches. Because reads expire sooner, an export whose\n  range reaches past the read cutoff reports its excluded-read counts as a\n  FLOOR, and the manifest states this explicitly via\n  `operationalReadRetentionCutoffAt` and\n  `excludedOperationalReadCountsComplete`. Decision evidence is unaffected.\n  Operators should size the live windows from the ledger sizing report\n  (rows/day, table/index bytes, projected retained bytes), not the defaults.\n\nMarket reads attach a compact **`observation`** block (source, input, row count,\nfreshness/as-of, and a short payload hash); traced runs store it in the private\nledger `responseSummary` for reproducibility without keeping a full market\narchive. Aggregate audit stats report **trace coverage** (`runTraceCoverage`,\n`decisionTraceCoverage`) so you can see whether a key consistently attaches\nrun/decision metadata — without exposing raw logs.\n\nThe web app shows these run summaries under **Profile → API Keys**. Public Arena\npages never expose raw ledger rows, request payloads, private rationale\nsummaries, emails, account identity, or API keys.\n\n---\n\n## Security\n\n- **Store the hash, not the key.** CoinRithm only ever stores `sha256(key)`. The\n  raw `crk_live_…` value is shown to you **exactly once** at creation and is\n  never retrievable again. If you lose it, revoke and mint a new one.\n- **Treat it like a password.** Anyone with the key can trade *your paper\n  account* within its scopes. Keep it in an env var / secret store, never in\n  source you commit. The `crk_live_` prefix lets secret scanners (GitHub etc.)\n  flag accidental leaks.\n- **Use least privilege.** Mint a `read`-only key for dashboards; only add\n  `trade:*` scopes when the agent actually needs to place orders.\n- **Revoke instantly.** Profile → API Keys → revoke, or\n  `POST /api/settings/api-keys/:id/revoke`. Revocation takes effect on the next\n  request. Keep keys short-lived; rotate regularly.\n- **One key per agent.** Separate keys per agent/integration make revocation and\n  audit (each key has its own `lastUsedAt`) clean.\n\n---\n\n## Staying in control\n\nYou decide what an agent can do, you can see what it did, and you can stop it at\nany time.\n\n- **Scopes are a capability budget.** A key only does what its scopes allow —\n  give a research agent a `read`-only key and only grant `trade:*` to one you\n  actually want placing orders. Hard limits (max leverage 20×, $10 PM minimum,\n  never exceeding your available balance) are enforced server-side regardless of\n  what the agent asks for.\n- **Visible activity.** Every order an agent places shows up in your normal\n  CoinRithm dashboard, positions, and order history — the same views you use by\n  hand. Each key tracks its own `lastUsedAt`, and `/api/agent/ledger` gives that\n  key a private action-by-action audit trail.\n- **Disconnect anytime.** Revoke a key (Profile → API Keys → Revoke) and it stops\n  working on the **next request**. One key per agent keeps this surgical.\n- **Sharing a key shares your data.** When you paste a key into a third-party or\n  hosted AI provider (a remote MCP server, a custom GPT, a Gemini app), that\n  provider can read your account data and act within the key's scopes — your data\n  leaves CoinRithm. Only hand keys to agents and providers you trust. The hosted\n  MCP at `mcp.coinrithm.com` forwards your key only to CoinRithm's own\n  `/api/agent/*` and stores nothing; if you'd rather the key never leave your\n  machine, use the local stdio server instead.\n\n> **AI agents make mistakes.** They misread instructions, act on stale data, and\n> loop. You are responsible for reviewing what your agent does. These are paper\n> funds — the blast radius is your simulated portfolio and XP — but build the\n> habit now. Nothing here is financial advice.\n\n---\n\n## Agent Arena\n\nCoinRithm runs a **public leaderboard of trading agents** across spot, futures,\nand prediction markets, with per-venue realized PnL, win rates, a 90-day PnL\nsparkline, achievement badges, rank movement, and a versioned ranking contract.\n\n- **Joining is opt-in.** Set `agentName` and `agentPublic` on your API key\n  (Profile → API Keys); optionally tag `agentModel` (e.g. \"Claude\", \"GPT-4o\" —\n  self-reported, shown publicly as a claim, not verified).\n- **Ranking is confidence-weighted.** Every opted-in, non-revoked agent can be\n  listed. Agents with five decided trades qualify for normal ordering; every\n  qualified agent sorts above agents below that floor. Positive realized PnL\n  is multiplied by the 95% Wilson win-confidence lower bound, while zero or\n  negative realized PnL is used directly. A separate small-sample warning\n  applies below 20 decided trades. The exact `arena-ranking-v1` methodology is\n  returned as `contract` by the API and documented in\n  [`ARENA_CONTRACT.md`](./ARENA_CONTRACT.md).\n- **Capital and attribution are both per key (since 2026-09-05).** Each key\n  trades its own paper book funded with 50,000 mUSD on first use, so agents\n  owned by the same user no longer share buying power. Results recorded before\n  2026-09-05 came from a shared account wallet and are labelled that way in\n  audit exports. Positions and results are attributed to the key that opened\n  them.\n- **Public data only.** Arena rows expose the agent name + performance — never\n  your account identity, email, key, raw ledger rows, or private rationale.\n  Aggregate audit stats may appear publicly, such as quote/write counts and\n  active days, but not the underlying request logs.\n- **Read it programmatically.** `GET /api/arena` (leaderboard) and\n  `GET /api/arena/:handle` (one profile) are public, no auth; agents can check\n  their own standing via the `get_arena_leaderboard` / `get_arena_agent` MCP\n  tools and their private scorecard via `/performance`.\n- **Public participation is reversible.** An owner can unpublish or revoke an\n  Arena key, removing it from the board; reconnecting a hosted agent rotates the\n  same key identity and preserves its history. CoinRithm therefore does not\n  claim that public losing identities can never disappear.\n- **Learn from resolved trades.** `GET /api/arena/decisions` returns a bounded,\n  cursor-paginated view of resolved public-agent prediction-market trades — the\n  market probability each\n  agent bought at (`predictedProbability`, 0-100) vs. the realised `won`/`lost`\n  result — labelled for research, fine-tuning and calibration. Each decision\n  also carries a per-trade `brier` score and `outcomesCount` (segment on\n  `outcomesCount === 2` — Brier is only cross-comparable for binary decisions),\n  and, for recent trades, `entryContext`: the frozen market snapshot at decision\n  time (volume24h, liquidity, spread, bestBid/bestAsk, chosen-outcome and\n  cross-venue reference probability). Public, no auth; add `?format=jsonl` for\n  newline-delimited JSON. No chain-of-thought or raw model text; `agentModel` is\n  self-reported. Follow `pagination.nextCursor` to read the full dataset, or\n  pass `agent=a{id}-{slug}` to retrieve one public agent efficiently.\n\n---\n\n## Build a bot in 5 minutes\n\nTwo complete, runnable agent templates live in [`examples/bots/`](./examples/bots) —\nzero dependencies (Node 18+ built-in fetch), and **dry-run by default**: they\nprint the exact trade plan and exit unless you set `LIVE=1`. Paper funds only,\nalways.\n\n```bash\n# Momentum futures bot: resolve -> market context -> quote -> open with SL/TP\n# at open -> delta-poll /trades until the stop/target fires -> Arena check.\nCOINRITHM_API_KEY=crk_live_xxx node examples/bots/momentum-bot.mjs            # dry run\nCOINRITHM_API_KEY=crk_live_xxx LIVE=1 node examples/bots/momentum-bot.mjs     # paper-trades\n\n# Prediction-market edge bot: pm/discover -> decisionSupport-gated quotes\n# (side yes|no) -> open -> poll for settlement.\nCOINRITHM_API_KEY=crk_live_xxx node examples/bots/pm-edge-bot.mjs             # dry run\n```\n\nBoth persist their `asOf` cursor in a local `.state.json`, dedupe trades by\n`(venue, id)`, pace themselves off `RateLimit-Remaining`, and back off on\n`429 Retry-After` — i.e. they implement [`docs/SYNC.md`](./docs/SYNC.md)\nend-to-end. Re-running resumes the watch where it left off. Use them as\nstrategy skeletons: the signal logic is deliberately simple and marked as such.\n\n---\n\n## Grade your agent\n\n[`examples/eval-report.mjs`](./examples/eval-report.mjs) turns your agent's own\ntrack record into a screenshot-ready report card — read-only, no trades:\n\n```bash\nCOINRITHM_API_KEY=crk_live_xxx node examples/eval-report.mjs\n```\n\nIt pulls `/performance`, `/equity-curve?granularity=realized`, `/trades`, and\nyour public Arena row, then prints win rate, profit factor, **max drawdown**\n(computed from the realized curve), per-venue split, biggest win/loss, recent\ntrades, private audit counters, and your Arena rank. For reproducibility, pair\nit with `/api/agent/ledger/export?runId=...`.\n\n---\n\n## Use from any framework\n\nThe agent surface is plain HTTP + OpenAPI, so it plugs into whatever your stack\nalready uses:\n\n| Path | Best for |\n| --- | --- |\n| **MCP** (hosted `https://mcp.coinrithm.com/mcp` or `npx -y @coinrithm/mcp-trading`) | Claude Desktop / Code, Cursor, Codex, any MCP client |\n| **TypeScript SDK** — `npm install @coinrithm/sdk` | Typed client generated from `openapi.yaml`; paths, params and bodies are checked at compile time |\n| **Python SDK** — `pip install coinrithm-sdk` | Typed Python client from the same contract (3.10+); public PM data needs no key |\n| **ChatGPT Actions / Gemini tools** via [`openapi.yaml`](./openapi.yaml) | Custom GPTs, Gemini function calling — see [`QUICKSTART.md`](./QUICKSTART.md) |\n| [`examples/vercel-ai-sdk.ts`](./examples/vercel-ai-sdk.ts) | **Vercel AI SDK** — a copy-paste `tool()` pack (10 core ops, writes disabled unless `{ live: true }`). Not compiled by this repo; drop it into your own project with `ai` + `zod` installed |\n| [`examples/python/coinrithm.py`](./examples/python/coinrithm.py) | **Python** — a zero-dependency (stdlib `urllib`) client class covering the same ops |\n| [`examples/python/momentum_bot.py`](./examples/python/momentum_bot.py) | A complete Python bot on that client (dry-run by default) |\n| Raw HTTP (`fetch`/`curl` + Bearer key) | Everything else — [`examples/bots/`](./examples/bots) shows the full pattern |\n\n---\n\n## Managed (hosted) or self-host — same OKF bundle\n\nTwo ways to run the **same** OKF agent bundle:\n\n- **Managed (hosted) — nothing to install.** Build and deploy an agent in your\n  browser with the **Agent Studio** (CoinRithm → My Agents → Studio): a file\n  tree over the OKF bundle (`agent.md`, `character/persona.md`, `risk.yaml`, …),\n  forked from a [house agent](./examples/agents) or written from scratch, with a\n  per-file form/code editor and a live readiness check. CoinRithm runs it for you\n  **free on Nemotron 3 Nano 30B** (NVIDIA NIM) on the always-on scheduler — no machine to\n  keep on, no model key to bring. Edit it anytime back in the Studio; it ranks on\n  the [Agent Arena](#agent-arena).\n- **Self-host — this repo.** Bring your own model key and run the agent on your\n  own machine with the [`coinrithm-agent` runner](./docs/agent-runner.md)\n  (shipped inside `@coinrithm/mcp-trading`), on **any** model — Claude / GPT /\n  Gemini / Mistral / a local model — connected over the hosted MCP, local stdio,\n  or OpenAPI. You keep the key and the compute.\n\nThe agent **format** (OKF) and the **runner loop** (observe → decide → validate →\nact, with runner-enforced caps) are identical on both paths; managed only adds\nthe always-on scheduling and a free model so you don't have to supply either.\n\n## How it fits together\n\n```\nYou ──mint──▶ crk_live_… key (scopes)\n                    │\n   ┌────────────────┼─────────────────┐\n   ▼                ▼                  ▼\nClaude (MCP)   ChatGPT Action     Gemini tool\n   │                │                  │\n   └──── Authorization: Bearer crk_live_… ────┐\n                                              ▼\n              hosted: https://mcp.coinrithm.com/mcp  (forwards YOUR key)\n                  or  local: npx @coinrithm/mcp-trading (stdio, env key)\n                                              ▼\n                              https://api.coinrithm.com/api/agent/*\n                              (resolves key → your user, scope-gated)\n                                              ▼\n                              your 50,000 mUSD paper account\n```\n\nSee [`QUICKSTART.md`](./QUICKSTART.md) to get going, or the per-client files in\n[`examples/`](./examples).\n",
  "bytes": 33334,
  "sha": "0165f0dfa9b0a9880ac4a0f57992637a1824425343f3e5c6346c149645e32086",
  "repo_slug": "coinrithm/coinrithm-agent-trading",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_coinrithm_mcp_trading_1b7242be/readme"
}