Get Settled Positions
Get Settled Positions
POSThttps://api.gemini.com/v1/prediction-markets/positions/settled
Returns historically settled positions for the authenticated user. Each entry represents a position in a contract that has resolved, including payout and resolutionSide. Differs from Get Positions in that it returns closed positions from settled contracts rather than current open positions.
POSTv1/prediction-markets/positions/settled
curl --request POST \
--url 'https://api.gemini.com/v1/prediction-markets/positions/settled?eventTicker=FEDJAN26' \
--header 'X-GEMINI-APIKEY: <string>' \
--header 'X-GEMINI-PAYLOAD: <string>' \
--header 'X-GEMINI-SIGNATURE: <string>'Roles
The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.
Headers
X-GEMINI-APIKEYstring·required
Your API keyX-GEMINI-SIGNATUREstring·required
HEX-encoded HMAC-SHA384 of payload signed with API secretX-GEMINI-PAYLOADstring·required
Base64-encoded JSON payloadContent-Typestring
Default: text/plainContent-Lengthstring
Default: 0Cache-Controlstring
Default: no-cacheQuery Parameters
eventTickerstring
Optional event ticker to filter settled positions to a single event (e.g. FEDJAN26). If omitted, all settled positions for the account are returned.limitinteger
Maximum number of settled positions to return.Default: 1000offsetinteger
Number of settled positions to skip for pagination.Default: 0sortstring·enum
Sort order. Accepts date or payout, optionally prefixed with + (ascending) or - (descending). A bare field name defaults to descending. date ascending is rejected and silently falls back to the default order — settled positions are conceptually ordered most-recent-first. A malformed sort value also falls back silently; no 400 is returned.Enum values: date-datepayout+payout-payoutsearchstring
Case-insensitive substring filter. Matches against the event name, contract name, event ticker, or any ancestor category name in the contract's category subtree (up to four levels). Whitespace is trimmed; inputs under 3 characters are dropped (GIN trigram lookup floor); inputs over 64 characters are truncated.categorystring
Filter to settled positions whose contract's event belongs to the named category (or any of its descendants in the category tree). Whitespace is trimmed; empty values are ignored.withCashOutsboolean
Opt-in flag. When true, the response carries new sibling fields (cashOuts, totalCashOutProceeds, totalCashOutCostBasis, totalCashOutNetProfit) populated with the qualifying cash-outs in the same account-scoped time window as the returned page's settled positions. When false (default) the response shape is byte-identical to the pre-withCashOuts contract: the positions[] element schema is unchanged regardless of the flag.Default: falseResponses
Successful response
positionsarray
positions[].accountIdinteger (int64)
Account that held the positionpositions[].instrumentIdinteger (int64)
Unique instrument identifier for the contractpositions[].instrumentSymbolstring
Contract instrument symbolExample: GEMI-FEDJAN26-DN25positions[].positionstring
Signed position held at settlement. Positive values represent a `yes` position; negative values represent a `no` position.Example: 125positions[].positionQuantitystring
Absolute quantity held at settlement (unsigned)Example: 125positions[].outcomestring·enum
The outcome being traded (Yes or No)Enum values: yesnopositions[].payoutstring
Payout received from settlement. `0` when the position lost.Example: 125.00positions[].resolutionSidestring·enum
The winning outcome of the contractEnum values: yesnopositions[].settledAtstring (date-time)
Settlement timestamp (ISO 8601)positions[].contractMetadataobject
positions[].contractMetadata.contractIdstring
positions[].contractMetadata.contractNamestring
positions[].contractMetadata.contractTickerstring
positions[].contractMetadata.eventTickerstring
positions[].contractMetadata.eventNamestring
positions[].contractMetadata.categorystring
positions[].contractMetadata.contractStatusstring
positions[].contractMetadata.eventTypestring
Event type ("binary" or "categorical")positions[].contractMetadata.expiryDatestring (date-time)
positions[].contractMetadata.resolvedAtstring (date-time)
positions[].contractMetadata.resolutionSidestring
Winning outcome if resolved ("yes" or "no")positions[].contractMetadata.parentEventTickerstring
Parent event ticker for sub-eventspositions[].contractMetadata.startTimestring (date-time)
Start datetime (ISO 8601)positions[].costBasisstring
Total amount spent to enter the position, net of any prior realized P&L from partial sells. Omitted when cost-basis data is not available.Example: 78.75positions[].realizedPnlstring
Realized profit or loss recorded from sells prior to settlement. Omitted when not available.Example: 0positions[].netProfitstring
Net profit for the position, computed as `payout - costBasis + realizedPnl`. Omitted when `costBasis` is not available.Example: 46.25totalinteger
Total number of settled positions across all pages for the current filter set.totalPayoutstring
Sum of `payout` across all settled positions in the filter set. Retained for binary back-compat with the legacy response shape; **field is absent (not `null`) on the unified backend** because computing a roll-up over the full filtered set would require a separate aggregate query (deferred until a partner asks). Play's default `OptionHandlers` omits absent `Option` fields rather than emitting `null`.totalCostBasisstring
Sum of `costBasis` across all settled positions in the filter set. Retained for binary back-compat; **field is absent (not `null`) on the unified backend** (see `totalPayout`).totalNetProfitstring
Sum of `netProfit` across all settled positions in the filter set. Retained for binary back-compat; **field is absent (not `null`) on the unified backend** (see `totalPayout`).cashOutsarray
Cash-outs (early sells before contract resolution) in the same account-scoped time window as the returned page's settled positions. Field is absent (not `null`) when `withCashOuts=true` is not passed on the request. `positions[]` pagination is unaffected — `limit`/`offset` continue to scope `positions[]` only.cashOuts[].accountIdinteger (int64)·required
Account that held the position.Example: 456cashOuts[].instrumentIdinteger (int64)·required
Contract instrument ID.Example: 16789219cashOuts[].instrumentSymbolstring·required
Contract instrument symbol.Example: GEMI-BTC100K-YEScashOuts[].timestampstring (date-time)·required
Wall-clock timestamp when the cash-out order closed (ISO 8601).Example: 2026-05-15T14:30:00.000ZcashOuts[].filledQuantitystring·required
Quantity sold (cumulative filled quantity on the cash-out order).Example: 10cashOuts[].sidestring·enum·required
Always `sell` for cash-outs.Enum values: sellExample: sellcashOuts[].proceedsstring·required
Amount received from the sale in USD. For prediction sells, proceeds flow through `cash_balance` rather than `closed_orders.total_spend`, so the value is derived from position-balance snapshots before/after the fill.Example: 10.50cashOuts[].costBasisstring·required
Cost basis allocated proportionally to the filled quantity (`(costBasisSpend / costBasisPositionBalance) * filledQuantity`).Example: 10.00cashOuts[].netProfitstring·required
Realized P&L from this cash-out fill (`proceeds - costBasis`). Equals the ledger `realized_pl` delta on the position-balance row pair around the fill; falls back to `0` under transient market-data lag so a missing post-fill snapshot can't poison the page.Example: 0.50cashOuts[].contractMetadataobject
cashOuts[].contractMetadata.contractIdstring
cashOuts[].contractMetadata.contractNamestring
cashOuts[].contractMetadata.contractTickerstring
cashOuts[].contractMetadata.eventTickerstring
cashOuts[].contractMetadata.eventNamestring
cashOuts[].contractMetadata.categorystring
cashOuts[].contractMetadata.contractStatusstring
cashOuts[].contractMetadata.eventTypestring
Event type ("binary" or "categorical")cashOuts[].contractMetadata.expiryDatestring (date-time)
cashOuts[].contractMetadata.resolvedAtstring (date-time)
cashOuts[].contractMetadata.resolutionSidestring
Winning outcome if resolved ("yes" or "no")cashOuts[].contractMetadata.parentEventTickerstring
Parent event ticker for sub-eventscashOuts[].contractMetadata.startTimestring (date-time)
Start datetime (ISO 8601)totalCashOutProceedsstring
Sum of `cashOuts[].proceeds` over the returned cash-outs. Field is absent (not `null`) when `withCashOuts=true` is not passed on the request.Example: 120.00totalCashOutCostBasisstring
Sum of `cashOuts[].costBasis` over the returned cash-outs. Field is absent (not `null`) when `withCashOuts=true` is not passed on the request.Example: 100.00totalCashOutNetProfitstring
Sum of `cashOuts[].netProfit` over the returned cash-outs. Field is absent (not `null`) when `withCashOuts=true` is not passed on the request.Example: 20.00Example Responses
{
"positions": [
{
"accountId": 12345,
"instrumentId": 1001,
"instrumentSymbol": "GEMI-FEDJAN26-DN25",
"position": "125",
"positionQuantity": "125",
"outcome": "yes",
"payout": "125.00",
"resolutionSide": "yes",
"settledAt": "2026-01-31T23:59:59.000Z",
"contractMetadata": {
"contractId": "contract_123",
"contractName": "FEDJAN26-DN25",
"contractTicker": "FEDJAN26-DN25",
"eventTicker": "FEDJAN26",
"eventName": "Will Fed Funds Rate drop at least 0.25% at January 2026 meeting?",
"category": "economics",
"contractStatus": "resolved",
"imageUrl": "https://example.com/fed.png",
"eventImageUrl": "https://example.com/fed-event.png",
"eventType": "binary",
"expiryDate": "2026-01-31T23:59:59.000Z",
"resolvedAt": "2026-01-31T23:59:59.000Z",
"resolutionSide": "yes",
"description": "Resolves YES if Federal Reserve lowers the target rate by 0.25% or more at the January 2026 FOMC meeting",
"sortOrder": null,
"parentEventTicker": null,
"template": "binary",
"color": null,
"startTime": null
},
"costBasis": "78.75",
"realizedPnl": "0",
"netProfit": "46.25"
},
{
"accountId": 12345,
"instrumentId": 1002,
"instrumentSymbol": "GEMI-FEDJAN26-NOCUT",
"position": "-200",
"positionQuantity": "200",
"outcome": "no",
"payout": "0",
"resolutionSide": "yes",
"settledAt": "2026-01-31T23:59:59.000Z",
"contractMetadata": {
"contractId": "contract_124",
"contractName": "FEDJAN26-NOCUT",
"contractTicker": "FEDJAN26-NOCUT",
"eventTicker": "FEDJAN26",
"eventName": "Will Fed Funds Rate drop at least 0.25% at January 2026 meeting?",
"category": "economics",
"contractStatus": "resolved",
"imageUrl": "https://example.com/fed.png",
"eventImageUrl": "https://example.com/fed-event.png",
"eventType": "binary",
"expiryDate": "2026-01-31T23:59:59.000Z",
"resolvedAt": "2026-01-31T23:59:59.000Z",
"resolutionSide": "yes",
"description": "Resolves YES if Federal Reserve lowers the target rate by 0.25% or more at the January 2026 FOMC meeting",
"sortOrder": null,
"parentEventTicker": null,
"template": "binary",
"color": null,
"startTime": null
},
"costBasis": "72.00",
"realizedPnl": "0",
"netProfit": "-72.00"
}
],
"total": 2
}Last modified on