---
title: "Close (or partially reduce) a mock futures position"
method: POST
path: "/api/agent/futures/close"
tags: ["futures"]
---

# Close (or partially reduce) a mock futures position

`POST /api/agent/futures/close`

## Request

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

Requires scope `trade:futures`. `idempotencyKey` is REQUIRED. `fraction`
in (0,1] reduces partially; omit (or 1) for a full close. If the mark has
crossed liquidation, the whole position settles as a liquidation
regardless of `fraction`.

## Request body

- FuturesCloseRequest
  - `positionId` integer, required
  - `fraction` number: (0,1] portion to close. Omit or 1 = full close.
  - `idempotencyKey` string, required
  - `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`

Closed / reduced / liquidated (or idempotent replay)

- FuturesPositionEnvelope
  - `position` FuturesPosition: Mock futures position. Live-mark fields (markPrice, unrealizedPnlMusd, liquidationDistancePct, atLiquidation) are added only on OPEN positions in the list endpoint; they may be null when no live mark is available.
    - `id` integer
    - `status` 'open' | 'closed' | 'liquidated'
    - `coin` object
      - `ucid` string
      - `symbol` string
      - `name` string
    - `side` 'long' | 'short'
    - `leverage` number
    - `entryPrice` number
    - `marginMusd` number
    - `notionalMusd` number
    - `sizeCoin` number
    - `maintenanceMarginRate` number
    - `liquidationPrice` number
    - `freshnessAtEntry` 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.
    - `stopLossPrice` number, nullable: Resting stop-loss trigger (null = none).
    - `takeProfitPrice` number, nullable: Resting take-profit trigger (null = none).
    - `exitPrice` number, nullable
    - `exitReason` string, nullable: user_close | liquidation | stop_loss | take_profit
    - `realizedPnlMusd` number, nullable
    - `fillModel` string, nullable: Fill model pinned when the position opened; null for legacy mark fills.
    - `openedAt` string, date-time, nullable
    - `closedAt` string, date-time, nullable
    - `createdAt` string, date-time
    - `markPrice` number, nullable: list endpoint, open positions only
    - `unrealizedPnlMusd` number, nullable
    - `fundingPaidMusd` number, nullable: Signed cumulative funding applied in mUSD (positive = paid, negative = received); omitted or null when unavailable. Zero is a meaningful value.
    - `fundingAppliedThrough` string, date-time, nullable: Latest timestamp through which cumulative funding was applied; omitted or null when unavailable.
    - `currentFundingReference` FuturesFundingSource: Current venue/contract funding reference. Historical charges are represented by funding events.
      - `venue` string, required: Current funding venue identifier.
      - `symbol` string, required: Current venue perpetual symbol.
      - `fundingIntervalHours` integer, required: Current venue funding interval in hours.
    - `liquidationDistancePct` number, nullable
    - `atLiquidation` boolean, nullable
  - `idempotentReplay` boolean: present (true) on a replay

## 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`: Position not found
- `409`: Position is not open, or idempotencyKey already used
- `422`: No live mark / wallet asset / frozen shortfall
- `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)