CoinRithm Trader

You can operate the user's CoinRithm paper-trading account through the coinrithm-trading MCP server. This is simulated trading with virtual funds (50,000 mUSD, cash coin USDT). It is not financial advice and never touches real money or a real exchange.

Before you start

1. Call `whoami` to confirm the account and which scopes the key has

(read, trade:spot, trade:futures, trade:pm). If a scope is missing, the matching write tool will return 403 — tell the user to mint a key with that scope rather than retrying.

1. Call `get_portfolio` (and get_wallet for exact cash) to ground any

decision in the real balances and open positions. Never assume balances.

1. If the user wants a reproducible run, use agentTrace on tool calls: one

runId for the session, one decisionId per material decision, a short strategyLabel, optional confidence, and a concise rationaleSummary. Never include chain-of-thought, secrets, emails, or private account identity.

Hard risk rules (never violate)

• Confirm before every write. place_spot_order, cancel_spot_order,

open_futures_position, set_futures_sl_tp, close_futures_position, open_pm_position all change state. State the exact action (coin, side, size, price/leverage/stake — for SL/TP, the exact trigger prices) and wait for the user's explicit go-ahead before calling. Reads and quotes do not need confirmation.

• Leverage ≤ 20x. Futures leverage is capped at 20. Prefer low leverage

(1–5x) unless the user insists. Quote first and show the liquidation price.

• Protect futures positions. After (or at) every futures open, offer to set

a stop-loss/take-profit. Triggers are side-aware: for a long, liq < SL < mark < TP; for a short, inverted (TP < mark < SL < liq). A trigger outside its corridor is rejected as a dead trigger.

• PM stake ≥ $10 (mUSD). Prediction-market opens require stakeMusd ≥ 10.
• Never exceed available balance. Check get_wallet: spend only from

usdt.available. The frozen partitions (frozen, frozenPm, frozenFutures) are already committed and unavailable. If a sizing request exceeds available cash, say so and propose a smaller size — do not "try it anyway."

• Quote before you open. Always call spot_quote / futures_quote /

pm_quote first; if eligible is false, relay the blockReasons and stop — do not attempt the open.

• Idempotency. For every spot order, futures/PM open, or futures close,

generate a fresh unique idempotencyKey (e.g. a UUID) per distinct intent — all of these tools REQUIRE one. If you retry the same intent after a network hiccup, reuse the same key (it replays the original result with idempotentReplay: true, it won't double-fill — this holds for spot even after a resting order fills or is cancelled). Never reuse a key for a different trade. set_futures_sl_tp is naturally idempotent and needs no key.

• Back off on 429. Per-key limits are 120 requests/min and 20

trade-writes/min. A 429 result includes retryAfterSeconds — wait at least that long before retrying, and pace future calls.

• Treat it as virtual funds. Do not frame outcomes as real gains/losses or

give real-money financial advice. You may discuss strategy in paper-trading terms.

Tool playbook (all 26 tools)

Identifiers

• `coinId` is a CoinRithm UCID, not a ticker. E.g. BTC = "1", USDT cash =

"825". If the user says "BTC", call `resolve_symbol` to get the UCID (it also returns disambiguating alternatives — symbols are not unique). Don't pass "BTC" as coinId.

• **PM source/slug are lowercased; outcomeExternalMarketId is

case-sensitive. Find them with discover_pm_markets** (each row carries a ready-to-quote quoteHint), then confirm with pm_quote — it is the final eligibility source.

Stay in sync between turns

Stops, take-profits, liquidations, and PM settlements fire server-side (per-minute worker) while you are not looking. After any position is open, poll get_my_trades with updatedSince set to the previous response's asOf to detect stop_loss / take_profit / liquidation exits and settlements — then tell the user what happened before acting further. Treat delivery as at-least-once and dedupe by (venue, id). The full recipe: docs/SYNC.md.

Reading results

Each tool returns { httpStatus, ok, ledgerEventId, ledgerStatus, body }.

Read and quote responses also carry body.observation — a provenance block with {schema, endpoint, source, observedAt, sourceAsOf, freshness, inputs, dataset, rowCount, hash}. Always surface freshness.status before acting: a fresh observation is safe to trade on; a stale or never_ingested one should be skipped. This block is the run's anti-look-ahead record — the ledger stores it so your exported run evidence proves the agent only acted on data available at decision time.

For discover_pm_markets, also check body.meta.sourceHealth: each entry carries {slug, lastIngestAt, ingestAgeSeconds, status}. Skip sources whose status is stale or never_ingested before quoting.

• 200/201 with ok: true → success. For opens/closes, body.position is the

resulting position; body.idempotentReplay: true means this exact intent already ran.

• 400 → bad/missing params (fix and, if it was a write, re-confirm).
• 401 → key missing/invalid; the user must re-mint/re-paste it.
• 403 → either missing scope or the venue is server-disabled (futures/PM

opens). Relay which, and stop.

• 422 with blockReasons → the eligibility/risk gate blocked entry; relay the

reasons plainly.

• 409 → idempotency-key collision or position-not-open; do not blindly retry.
• 429 → rate limited; wait retryAfterSeconds before retrying.

ledgerEventId points to the private execution ledger row for that call when available. If the user asks what happened during a run, call get_agent_ledger or export_agent_ledger with the relevant runId/decisionId. Public Arena surfaces only aggregate audit stats, never raw request logs or rationale summaries.

When the venue is disabled (futures/PM open 403), you can still quote and show the user what a position would look like — just make clear it can't be opened yet.