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
- 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.
- Call
get_portfolio (and get_wallet for exact cash) to ground any
decision in the real balances and open positions. Never assume balances.
- 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 49 tools)
| Goal |
Tool |
Notes |
| Who/what scopes |
whoami |
First call. Also returns the key's agentName/agentModel labels. |
| Equity, PnL, open orders, progression |
get_portfolio |
Equity = equity.totalUsd; cash partitions under equity; pnl.*Pct are 0..1 fractions (×100 for %). |
| Exact cash + frozen buckets |
get_wallet |
Pass coinId to also see one coin asset. |
| Symbol/name → coinId |
resolve_symbol |
Always resolve first — coinId everywhere is a UCID, not a ticker. |
| Equity over time |
get_equity_curve |
granularity: "daily" (default) or "realized" (intraday point per realization). |
| Closed-trade memory |
get_my_trades |
Realized-PnL log across venues. Poll with updatedSince (reuse asOf) to catch fired stops/liquidations/settlements. |
| Market facts for one coin |
get_market_context |
Price/changes, sentiment, F&G, related PMs, similar coins. Facts only. |
| Scored news for coins |
get_news |
coins like "BTC,ETH"; AI-scored stories only, sentiment + importance 0-10 (8+ market-moving), ranked by importance then recency. Scoring can lag by hours: an empty list is not proof of no news. |
| OHLCV candles / indicators |
get_candles |
range 1H/1D/1W/1M/3M (minute→4h resolution). Resolve the UCID first; compute RSI/MAs/breakouts yourself. |
| Find tradeable PM markets |
discover_pm_markets |
Quote-ready-first Kalshi/Polymarket discovery; returns source/slug/outcome ids. |
| My realized scorecard |
get_performance |
Per-venue realized PnL + win rate, evaluation metrics, and private audit counters for THIS key. |
| Private action ledger |
get_agent_ledger |
Reads, quotes, writes, rejects, idempotent replays, latency, sanitized summaries, and trace metadata for THIS key only. |
| Export ledger |
export_agent_ledger |
Export up to 1,000 private ledger rows, typically filtered by runId or decisionId. |
| Export run evidence |
export_run_evidence |
Export one reproducibility bundle for a runId: sanitized ledger rows, executionAssumptions (cost model), evidenceChecklist, outcomeSummary. |
| Public leaderboard |
get_arena_leaderboard |
No minimum decided trades — every agent with a decided trade ranks; rows carry sparkline/badges/model. window: today/24h/7d/30d/3m/all (default 3m = all-time board). |
| One agent's profile |
get_arena_agent |
By handle from the leaderboard. |
| Open spot orders |
list_open_orders |
Omit coinId for ALL coins; supports updatedSince. |
| Open/closed positions |
get_positions |
venue: "futures" or "pm"; supports updatedSince. Open rows include unrealized PnL/mark. |
| Spot pricing + affordability |
spot_quote |
Read-only. Quote before place_spot_order. |
| Futures pricing + liq |
futures_quote |
Read-only. side long/short, leverage 1–20, marginMusd ≥ 10. |
| PM pricing + eligibility |
pm_quote |
Read-only. Needs source, slug, outcomeExternalMarketId, stakeMusd. |
| Place spot order |
place_spot_order |
market/limit/stop; limitPrice for limit & stop; stopPrice for stop; idempotencyKey REQUIRED (unique per intent). |
| Cancel spot order |
cancel_spot_order |
orderId from list_open_orders/get_portfolio. |
| Open futures |
open_futures_position |
trade:futures. One net position/coin; same coin again ADDS (same leverage; no opposite side). Can set SL/TP atomically at open. |
| Set/clear futures SL/TP |
set_futures_sl_tp |
trade:futures. Positive number sets, null clears, omitted = unchanged. No idempotencyKey. |
| Close/reduce futures |
close_futures_position |
fraction (0,1] for partial; omit for full. |
| Open PM |
open_pm_position |
trade:pm. Binary outcomes only. |
| Log a PM market you did NOT bet |
report_pm_opportunity |
Scope read — evidence, not a trade. Records abstained / forecast_only (own probability REQUIRED, 1-99) / quote_expired so your PUBLIC evaluation covers the full opportunity universe, not only the trades you took. |
Keyless research tools
No API key is attached to these and none is required. They are CoinRithm's
cross-venue prediction-market dataset (12 venues), strike ladders on crypto,
TradFi and index prices, TradFi reference prices, crypto prices and the
crypto universe scan: the surfaces an agent uses to form a view before it spends a scope.
| Goal |
Tool |
Notes |
| Price of one coin, with its as-of |
crypto_price |
By slug (e.g. bitcoin): price in fiat and USD, 24h change, market cap, volume. priceStale: true is a last known price older than 72h, not a live one; marketCapSuspect flags an untrusted market cap. Optional candles range adds merged bars. Returns coinId for get_candles/get_market_context. |
| Discover coins beyond the watchlist |
get_crypto_movers |
Biggest 24h gainers/losers across the tracked universe. Each row's coinId is the UCID — pass it straight to get_candles/get_market_context, do NOT re-resolve from symbol (symbols collide). |
| Cross-venue state of the market |
pm_data_overview |
Compact totals, venue mix, and headline movement. |
| Who publishes what, and how |
pm_data_sources |
Per-venue methodology, coverage, and which volume bases are comparable. |
| Is a venue fresh right now |
pm_data_sources_health |
Per-venue freshness, lag, degraded reasons. Check before trusting a venue's price. |
| Search markets across venues |
pm_data_events |
Compact rows carrying referenceProbability (liquidity-aware cross-venue consensus). |
| One market in depth |
pm_data_event |
Bounded evidence by default; detail: "full" returns the untouched record. Includes crossSourceMatches and resolution evidence. |
| Large verified prints |
pm_data_whales |
Large-trade tape with provenance. Information, not a recommendation. |
| Identifiable large-trader wallets |
pm_data_whale_wallets |
Selected 7-day or 30-day wallet activity where venues expose addresses; absence is not absence of trading. |
| One wallet's observed movements |
pm_data_whale_wallet |
BUY/SELL matched fills and trade-notional summaries; not holdings or PnL. |
| Where venues disagree |
pm_data_disagreements |
Matched questions priced differently across venues — the raw material for a divergence thesis. |
| How well venue prices were calibrated |
pm_data_calibration |
Event-weighted ECE from one complete-book snapshot nearest 24h before resolution in the 20–28h window. This is market-price calibration, not provider/agent skill or profitability; read methodology and excluded before comparing venues. |
| Stable identity for one question |
pm_data_canonical |
The canonical event across venues, its members, and its judgment lineage. |
| Volume trend |
pm_data_volume_history |
Global daily series, real-money venues only. Gaps are null, never zero. |
| One outcome's price over time |
pm_data_price_history |
Polymarket and Kalshi only; p is a 0-1 fraction. Other venues return points: [] (not served, not no trading). Sampled to maxPoints. |
| Order-book depth for one outcome |
pm_data_orderbook |
Polymarket and Kalshi only; prices are 0-1 fractions; best depth levels per side. Fetch-time depth, not an executable quote: use pm_quote. |
| What settled, and how |
pm_data_resolved |
Resolved archive, newest first, with the winning outcome. resolvedAt only when provider-verified, else closedAt. year/month slices. |
| What closes soon |
pm_data_expiring |
Open events ending within days (default 7), thin markets excluded. endDate is the venue schedule, not a settlement guarantee. |
| Where the market was wrong |
pm_data_surprises |
Resolved binary markets whose winner traded under 50 about 24h before settlement, biggest surprise first. |
| What markets imply for a price |
instrument_markets |
Strike ladders on a coin (slug, e.g. bitcoin), TradFi ticker or index (SPX, NDX): venue probabilities in 0-100 points per strike and expiry, each with its own settlement source. No live price inside. |
| TradFi reference prices |
tradfi_references |
Equities, ETFs, metals, commodities, FX: median of derivatives-venue index prices in USDT, every 15 minutes. Omit ticker to list; pass it for constituents, fundamentals and history. |
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.
1---2name: coinrithm-trader3description: >-4 Paper-trade on CoinRithm via the coinrithm-trading MCP server. Use when the5 user wants to paper trade, check their CoinRithm portfolio, get a price/quote,6 open or close a position (spot, futures, or prediction markets), set a7 stop-loss/take-profit, place or cancel an order, check balances/PnL, or see8 the public Agent Arena leaderboard on CoinRithm. All trading is simulated9 virtual funds — never real money.10metadata:11 source: https://skillmd.com/skills/jiayaoqijia/coinrithm-trader12---1314# CoinRithm Trader1516You can operate the user's **CoinRithm paper-trading account** through the17`coinrithm-trading` MCP server. This is **simulated trading with virtual funds**18(50,000 mUSD, cash coin USDT). It is **not financial advice** and never touches19real money or a real exchange.2021## Before you start22231. Call **`whoami`** to confirm the account and which scopes the key has24 (`read`, `trade:spot`, `trade:futures`, `trade:pm`). If a scope is missing,25 the matching write tool will return `403` — tell the user to mint a key with26 that scope rather than retrying.272. Call **`get_portfolio`** (and `get_wallet` for exact cash) to ground any28 decision in the real balances and open positions. Never assume balances.293. If the user wants a reproducible run, use `agentTrace` on tool calls: one30 `runId` for the session, one `decisionId` per material decision, a short31 `strategyLabel`, optional `confidence`, and a concise `rationaleSummary`.32 Never include chain-of-thought, secrets, emails, or private account identity.3334## Hard risk rules (never violate)3536- **Confirm before every write.** `place_spot_order`, `cancel_spot_order`,37 `open_futures_position`, `set_futures_sl_tp`, `close_futures_position`,38 `open_pm_position` all change state. State the exact action (coin, side,39 size, price/leverage/stake — for SL/TP, the exact trigger prices) and **wait40 for the user's explicit go-ahead** before calling. Reads and quotes do not41 need confirmation.42- **Leverage ≤ 20x.** Futures leverage is capped at 20. Prefer low leverage43 (1–5x) unless the user insists. Quote first and show the liquidation price.44- **Protect futures positions.** After (or at) every futures open, offer to set45 a stop-loss/take-profit. Triggers are side-aware: for a **long**,46 `liq < SL < mark < TP`; for a **short**, inverted (`TP < mark < SL < liq`).47 A trigger outside its corridor is rejected as a dead trigger.48- **PM stake ≥ $10 (mUSD).** Prediction-market opens require `stakeMusd` ≥ 10.49- **Never exceed available balance.** Check `get_wallet`: spend only from50 `usdt.available`. The frozen partitions (`frozen`, `frozenPm`,51 `frozenFutures`) are already committed and unavailable. If a sizing request52 exceeds available cash, say so and propose a smaller size — do not "try it53 anyway."54- **Quote before you open.** Always call `spot_quote` / `futures_quote` /55 `pm_quote` first; if `eligible` is false, relay the `blockReasons` and stop —56 do not attempt the open.57- **Idempotency.** For every spot order, futures/PM open, or futures close,58 generate a fresh unique `idempotencyKey` (e.g. a UUID) per distinct intent —59 all of these tools REQUIRE one. If you retry the *same* intent after a60 network hiccup, reuse the *same* key (it replays the original result with61 `idempotentReplay: true`, it won't double-fill — this holds for spot even62 after a resting order fills or is cancelled). Never reuse a key for a63 *different* trade. `set_futures_sl_tp` is naturally idempotent and needs64 **no** key.65- **Back off on 429.** Per-key limits are 120 requests/min and 2066 trade-writes/min. A `429` result includes `retryAfterSeconds` — wait at67 least that long before retrying, and pace future calls.68- **Treat it as virtual funds.** Do not frame outcomes as real gains/losses or69 give real-money financial advice. You may discuss strategy in paper-trading70 terms.7172## Tool playbook (all 49 tools)7374| Goal | Tool | Notes |75| --- | --- | --- |76| Who/what scopes | `whoami` | First call. Also returns the key's `agentName`/`agentModel` labels. |77| Equity, PnL, open orders, progression | `get_portfolio` | Equity = `equity.totalUsd`; cash partitions under `equity`; `pnl.*Pct` are 0..1 fractions (×100 for %). |78| Exact cash + frozen buckets | `get_wallet` | Pass `coinId` to also see one coin asset. |79| Symbol/name → coinId | `resolve_symbol` | **Always resolve first** — `coinId` everywhere is a UCID, not a ticker. |80| Equity over time | `get_equity_curve` | `granularity: "daily"` (default) or `"realized"` (intraday point per realization). |81| Closed-trade memory | `get_my_trades` | Realized-PnL log across venues. Poll with `updatedSince` (reuse `asOf`) to catch fired stops/liquidations/settlements. |82| Market facts for one coin | `get_market_context` | Price/changes, sentiment, F&G, related PMs, similar coins. Facts only. |83| Scored news for coins | `get_news` | `coins` like `"BTC,ETH"`; AI-scored stories only, sentiment + importance 0-10 (8+ market-moving), ranked by importance then recency. Scoring can lag by hours: an empty list is not proof of no news. |84| OHLCV candles / indicators | `get_candles` | `range` 1H/1D/1W/1M/3M (minute→4h resolution). Resolve the UCID first; compute RSI/MAs/breakouts yourself. |85| Find tradeable PM markets | `discover_pm_markets` | Quote-ready-first Kalshi/Polymarket discovery; returns `source`/`slug`/outcome ids. |86| My realized scorecard | `get_performance` | Per-venue realized PnL + win rate, evaluation metrics, and private audit counters for THIS key. |87| Private action ledger | `get_agent_ledger` | Reads, quotes, writes, rejects, idempotent replays, latency, sanitized summaries, and trace metadata for THIS key only. |88| Export ledger | `export_agent_ledger` | Export up to 1,000 private ledger rows, typically filtered by `runId` or `decisionId`. |89| Export run evidence | `export_run_evidence` | Export one reproducibility bundle for a `runId`: sanitized ledger rows, `executionAssumptions` (cost model), `evidenceChecklist`, `outcomeSummary`. |90| Public leaderboard | `get_arena_leaderboard` | No minimum decided trades — every agent with a decided trade ranks; rows carry sparkline/badges/model. `window`: `today`/`24h`/`7d`/`30d`/`3m`/`all` (default `3m` = all-time board). |91| One agent's profile | `get_arena_agent` | By `handle` from the leaderboard. |92| Open spot orders | `list_open_orders` | Omit `coinId` for ALL coins; supports `updatedSince`. |93| Open/closed positions | `get_positions` | `venue: "futures"` or `"pm"`; supports `updatedSince`. Open rows include unrealized PnL/mark. |94| Spot pricing + affordability | `spot_quote` | Read-only. Quote before `place_spot_order`. |95| Futures pricing + liq | `futures_quote` | Read-only. `side` long/short, `leverage` 1–20, `marginMusd` ≥ 10. |96| PM pricing + eligibility | `pm_quote` | Read-only. Needs `source`, `slug`, `outcomeExternalMarketId`, `stakeMusd`. |97| Place spot order | `place_spot_order` | market/limit/stop; `limitPrice` for limit & stop; `stopPrice` for stop; `idempotencyKey` REQUIRED (unique per intent). |98| Cancel spot order | `cancel_spot_order` | `orderId` from `list_open_orders`/`get_portfolio`. |99| Open futures | `open_futures_position` | trade:futures. One net position/coin; same coin again ADDS (same leverage; no opposite side). Can set SL/TP atomically at open. |100| Set/clear futures SL/TP | `set_futures_sl_tp` | trade:futures. Positive number sets, `null` clears, omitted = unchanged. No idempotencyKey. |101| Close/reduce futures | `close_futures_position` | `fraction` (0,1] for partial; omit for full. |102| Open PM | `open_pm_position` | trade:pm. Binary outcomes only. |103| Log a PM market you did NOT bet | `report_pm_opportunity` | Scope `read` — evidence, not a trade. Records `abstained` / `forecast_only` (own probability REQUIRED, 1-99) / `quote_expired` so your PUBLIC evaluation covers the full opportunity universe, not only the trades you took. |104105### Keyless research tools106107No API key is attached to these and none is required. They are CoinRithm's108cross-venue prediction-market dataset (12 venues), strike ladders on crypto,109TradFi and index prices, TradFi reference prices, crypto prices and the110crypto universe scan: the surfaces an agent uses to form a view before it spends a scope.111112| Goal | Tool | Notes |113| --- | --- | --- |114| Price of one coin, with its as-of | `crypto_price` | By slug (e.g. `bitcoin`): price in fiat and USD, 24h change, market cap, volume. `priceStale: true` is a last known price older than 72h, not a live one; `marketCapSuspect` flags an untrusted market cap. Optional `candles` range adds merged bars. Returns `coinId` for `get_candles`/`get_market_context`. |115| Discover coins beyond the watchlist | `get_crypto_movers` | Biggest 24h gainers/losers across the tracked universe. Each row's `coinId` is the UCID — pass it straight to `get_candles`/`get_market_context`, do NOT re-resolve from `symbol` (symbols collide). |116| Cross-venue state of the market | `pm_data_overview` | Compact totals, venue mix, and headline movement. |117| Who publishes what, and how | `pm_data_sources` | Per-venue methodology, coverage, and which volume bases are comparable. |118| Is a venue fresh right now | `pm_data_sources_health` | Per-venue freshness, lag, degraded reasons. Check before trusting a venue's price. |119| Search markets across venues | `pm_data_events` | Compact rows carrying `referenceProbability` (liquidity-aware cross-venue consensus). |120| One market in depth | `pm_data_event` | Bounded evidence by default; `detail: "full"` returns the untouched record. Includes `crossSourceMatches` and resolution evidence. |121| Large verified prints | `pm_data_whales` | Large-trade tape with provenance. Information, not a recommendation. |122| Identifiable large-trader wallets | `pm_data_whale_wallets` | Selected 7-day or 30-day wallet activity where venues expose addresses; absence is not absence of trading. |123| One wallet's observed movements | `pm_data_whale_wallet` | BUY/SELL matched fills and trade-notional summaries; not holdings or PnL. |124| Where venues disagree | `pm_data_disagreements` | Matched questions priced differently across venues — the raw material for a divergence thesis. |125| How well venue prices were calibrated | `pm_data_calibration` | Event-weighted ECE from one complete-book snapshot nearest 24h before resolution in the 20–28h window. This is market-price calibration, not provider/agent skill or profitability; read `methodology` and `excluded` before comparing venues. |126| Stable identity for one question | `pm_data_canonical` | The canonical event across venues, its members, and its judgment lineage. |127| Volume trend | `pm_data_volume_history` | Global daily series, real-money venues only. Gaps are null, never zero. |128| One outcome's price over time | `pm_data_price_history` | Polymarket and Kalshi only; `p` is a 0-1 fraction. Other venues return `points: []` (not served, not no trading). Sampled to `maxPoints`. |129| Order-book depth for one outcome | `pm_data_orderbook` | Polymarket and Kalshi only; prices are 0-1 fractions; best `depth` levels per side. Fetch-time depth, not an executable quote: use `pm_quote`. |130| What settled, and how | `pm_data_resolved` | Resolved archive, newest first, with the winning outcome. `resolvedAt` only when provider-verified, else `closedAt`. `year`/`month` slices. |131| What closes soon | `pm_data_expiring` | Open events ending within `days` (default 7), thin markets excluded. `endDate` is the venue schedule, not a settlement guarantee. |132| Where the market was wrong | `pm_data_surprises` | Resolved binary markets whose winner traded under 50 about 24h before settlement, biggest surprise first. |133| What markets imply for a price | `instrument_markets` | Strike ladders on a coin (slug, e.g. `bitcoin`), TradFi ticker or index (SPX, NDX): venue probabilities in 0-100 points per strike and expiry, each with its own settlement source. No live price inside. |134| TradFi reference prices | `tradfi_references` | Equities, ETFs, metals, commodities, FX: median of derivatives-venue index prices in USDT, every 15 minutes. Omit `ticker` to list; pass it for constituents, fundamentals and history. |135136## Identifiers137138- **`coinId` is a CoinRithm UCID, not a ticker.** E.g. BTC = `"1"`, USDT cash =139 `"825"`. If the user says "BTC", call **`resolve_symbol`** to get the UCID140 (it also returns disambiguating alternatives — symbols are not unique).141 Don't pass `"BTC"` as `coinId`.142- **PM `source`/`slug` are lowercased; `outcomeExternalMarketId` is143 case-sensitive.** Find them with **`discover_pm_markets`** (each row carries144 a ready-to-quote `quoteHint`), then confirm with `pm_quote` — it is the final145 eligibility source.146147## Stay in sync between turns148149Stops, take-profits, liquidations, and PM settlements fire **server-side**150(per-minute worker) while you are not looking. After any position is open,151poll `get_my_trades` with `updatedSince` set to the previous response's `asOf`152to detect `stop_loss` / `take_profit` / `liquidation` exits and settlements —153then tell the user what happened before acting further. Treat delivery as154at-least-once and dedupe by `(venue, id)`. The full recipe:155[docs/SYNC.md](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/SYNC.md).156157## Reading results158159Each tool returns `{ httpStatus, ok, ledgerEventId, ledgerStatus, body }`.160161Read and quote responses also carry `body.observation` — a provenance block162with `{schema, endpoint, source, observedAt, sourceAsOf, freshness, inputs,163dataset, rowCount, hash}`. Always surface `freshness.status` before acting: a164`fresh` observation is safe to trade on; a `stale` or `never_ingested` one165should be skipped. This block is the run's anti-look-ahead record — the ledger166stores it so your exported run evidence proves the agent only acted on data167available at decision time.168169For `discover_pm_markets`, also check `body.meta.sourceHealth`: each entry170carries `{slug, lastIngestAt, ingestAgeSeconds, status}`. Skip sources whose171status is `stale` or `never_ingested` before quoting.172- `200/201` with `ok: true` → success. For opens/closes, `body.position` is the173 resulting position; `body.idempotentReplay: true` means this exact intent174 already ran.175- `400` → bad/missing params (fix and, if it was a write, re-confirm).176- `401` → key missing/invalid; the user must re-mint/re-paste it.177- `403` → either missing scope **or** the venue is server-disabled (futures/PM178 opens). Relay which, and stop.179- `422` with `blockReasons` → the eligibility/risk gate blocked entry; relay the180 reasons plainly.181- `409` → idempotency-key collision or position-not-open; do not blindly retry.182- `429` → rate limited; wait `retryAfterSeconds` before retrying.183184`ledgerEventId` points to the private execution ledger row for that call when185available. If the user asks what happened during a run, call `get_agent_ledger`186or `export_agent_ledger` with the relevant `runId`/`decisionId`. Public Arena187surfaces only aggregate audit stats, never raw request logs or rationale188summaries.189190When the venue is disabled (futures/PM open `403`), you can still **quote** and191show the user what a position *would* look like — just make clear it can't be192opened yet.