---
title: "Read-only futures quote (price, liq estimate, eligibility)"
method: POST
path: "/api/agent/futures/quote"
tags: ["futures"]
---

# Read-only futures quote (price, liq estimate, eligibility)

`POST /api/agent/futures/quote`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/agent/futures/quote`
- Auth: HTTP bearer

Never mutates state. Use it before `futures/open` to see entry price,
notional, liquidation price, and whether entry is eligible. Requires
scope `read`. Leverage must be 1..20; margin >= 10 mUSD.

## Request body

- FuturesQuoteRequest
  - `coinId` string, required: Coin UCID
  - `side` 'long' | 'short', required
  - `leverage` number, required
  - `marginMusd` number, required: Isolated margin in mUSD
  - `agentTrace` AgentTraceMetadata: Optional private trace metadata supplied by a user-run agent. CoinRithm stores only this structured summary; do not send chain-of-thought, secrets, emails, or private account identity.
    - `runId` string, nullable
    - `decisionId` string, nullable
    - `strategyLabel` string, nullable
    - `confidence` number, nullable
    - `rationaleSummary` string, nullable

## Response `200`

OK

- FuturesQuoteResponse
  - `eligible` boolean
  - `blockReasons` string[]
  - `coin` object
    - `ucid` string
    - `symbol` string
    - `name` string
  - `side` string, nullable
  - `leverage` number, nullable
  - `marginMusd` number, nullable
  - `minMargin` number
  - `maxLeverage` number
  - `referenceMark` number, nullable: Mark price the quote was priced from; executable entryPrice may include the fill model.
  - `entryPrice` number, nullable
  - `notionalMusd` number, nullable
  - `sizeCoin` number, nullable
  - `liquidationPrice` number, nullable
  - `maintenanceMarginRate` number, nullable
  - `executionModel` ExecutionModel: Paper Execution Realism v1 cost disclosure. Paper fills apply a deterministic, fully-disclosed cost so simulated PnL reflects real trading friction (a flat round-trip is a small loss, not a free breakeven). This is a rehearsal cost model, NOT an exchange fill guarantee. Per venue: - spot: a taker fee (`feeBps`) on notional, with market orders also filling at an adverse price (half-spread + slippage). Futures use the default-off legacy mark fill unless `futures_fill_v1` is pinned; that model applies deterministic half-spread, slippage, and square-root size-scaled impact, with adverse cost embedded in the executed price. - PM: fills at the ask (mid + half the ingested bid-ask spread) with size/liquidity-based slippage and a Polymarket-shaped taker fee (~1.8% near 50%, ~0 at the extremes), folded into `sharesMusd`. `feeBps`/`spreadBps` are positive and `slippageBps` scales with order size; `entryProbability` stays the mid for calibration. Futures quote funding is estimated from the latest venue rate when available and may change before settlement. Covered futures charges are applied from recorded settled venue history; `fundingMode` is a venue-specific mode such as `binance_perp_rate_v1`, `bybit_perp_rate_v1`, or `gateio_perp_rate_v1`, and is `not_modeled` when no latest rate is available. Funding does not apply to spot or PM. Futures liquidation forfeits margin without adverse fill cost, and fixed-price SL/TP triggers fill at their set price. Order-book depth, latency, and partial fills are not modeled.
    - `version` string
    - `feeBps` number: taker fee, basis points of notional
    - `spreadBps` number: modeled bid/ask spread (bps)
    - `slippageBps` number: modeled slippage (bps)
    - `fillModel` string, nullable: Futures fill model pinned for this execution, or null for legacy mark fills.
    - `estimatedFeeMusd` number: estimated fee for this trade (mUSD)
    - `estimatedSlippageMusd` number: estimated slippage cost for this trade (mUSD)
    - `fundingMode` string: Venue-specific current funding reference mode, or not_modeled when no latest rate is available.
    - `assumptions` string[]: human-readable list of what is and isn't modeled
  - `fill` object, nullable: Estimated executable fill; null when the futures fill model is disabled.
    - `model` string
    - `referenceMark` number
    - `execPrice` number
    - `sizeCoin` number
    - `adverseBps` number
    - `adverseCostMusd` number
    - `impactBps` number
    - `impactBasis` 'volume' | 'cap_fallback'
    - `volumeCoverage` 'complete' | 'partial' | 'unknown'
    - `unavailable` string, nullable
  - `funding` FuturesFundingQuote: Latest funding rate used by the futures quote. The rate is signed as provided by the venue: for a long, a positive rate produces a positive estimated payment; a negative rate produces a receipt. The estimate is for the quoted position at the next settlement and is signed the same way (positive = paid, negative = received). `estimatedPerIntervalMusd` is null when the quote cannot price a position; zero remains a real estimate.
    - `venue` string, required: Funding-rate venue identifier.
    - `symbol` string, required: Venue perpetual symbol.
    - `rate` number, required: Signed venue funding rate for the next settlement.
    - `intervalHours` integer, required: Funding settlement interval in hours.
    - `nextFundingTime` string, date-time, required: Next expected funding settlement.
    - `asOf` string, date-time, required: When this venue rate was fetched.
    - `estimatedPerIntervalMusd` number, nullable, required: Signed estimated payment for the quoted position in mUSD (positive = paid, negative = received); null when unavailable. Zero is meaningful.
    - `annualizedRate` number, required: Signed simple annualized rate (rate multiplied by intervals per year; not compounded).
    - `stale` boolean: Whether this latest venue rate exceeds the freshness policy.
  - `perpetual` FuturesPerpetualReference: Current venue/contract reference for a coin. Historical funding charges remain on funding ledger events.
    - `listed` boolean, required: Whether a covered venue reference is currently known.
    - `venue` string, nullable, required: Current funding venue identifier, such as binance, bybit, or gateio.
    - `symbol` string, nullable, required: Current venue perpetual symbol.
    - `fundingIntervalHours` integer, nullable, required: Current venue funding interval in hours.
    - `fetchedAt` string, date-time, nullable, required: When the current venue reference was fetched; null when unavailable.
    - `stale` boolean, required: Whether the current venue reference exceeds the freshness policy.
  - `freshness` Freshness: Data-freshness descriptor. Futures + spot use ageSeconds; PM uses ageMinutes. `status` is a freshness label; `basis` (PM only) names which timestamp the age was measured against.
    - `asOf` string, date-time, nullable
    - `ageSeconds` number, nullable: futures / spot
    - `ageMinutes` number, nullable: PM
    - `status` 'fresh' | 'lagging' | 'stale' | 'unknown' | 'null', nullable: fresh | lagging (PM only) | stale | unknown. PM lagging>=45m & stale>=2h; spot/futures stale>120s.
    - `basis` 'latest_snapshot' | 'source_update' | 'processed' | 'event_update' | 'unknown', nullable: PM only — which timestamp the age was measured against.
  - `observation` AgentObservation: Compact provenance block for an agent-facing market observation. It is also stored in the private ledger responseSummary when the request uses agentTrace/run headers, giving run exports a verifiable snapshot of what the agent observed without creating a full market archive.
    - `schema` string
    - `endpoint` string
    - `source` string
    - `observedAt` string, date-time
    - `sourceAsOf` string, date-time, nullable
    - `freshness` Freshness: Data-freshness descriptor. Futures + spot use ageSeconds; PM uses ageMinutes. `status` is a freshness label; `basis` (PM only) names which timestamp the age was measured against.
      - `asOf` string, date-time, nullable
      - `ageSeconds` number, nullable: futures / spot
      - `ageMinutes` number, nullable: PM
      - `status` 'fresh' | 'lagging' | 'stale' | 'unknown' | 'null', nullable: fresh | lagging (PM only) | stale | unknown. PM lagging>=45m & stale>=2h; spot/futures stale>120s.
      - `basis` 'latest_snapshot' | 'source_update' | 'processed' | 'event_update' | 'unknown', nullable: PM only — which timestamp the age was measured against.
    - `inputs` object
    - `dataset` object
    - `rowCount` integer, nullable
    - `hash` string: Short SHA-256 digest of the observed payload metadata.

## Other responses

- `400`: Invalid or missing parameters. On a route with a query allowlist, an undocumented query parameter returns `{"error": "unsupported_query_parameter", "message": "Unsupported query parameter: <key>. Supported: <keys>."}`.
- `401`: Missing/malformed or invalid/revoked API key
- `403`: API key missing the required scope
- `404`: Coin not found
- `429`: Rate limit exceeded for this API key (120 req/min baseline, 20 trade-writes/min). Honor `Retry-After`, then resume; the `RateLimit-*` headers on every response let you pace proactively. (The platform also runs a per-IP limiter; its 429 body is `{"error": "rate_limited", "message": "..."}`.)

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)