Get Positions

REST APIs Prediction Markets PositionsGet Positions

Get Positions

POSThttps://api.gemini.com/v1/prediction-markets/positions

Returns current filled positions for the authenticated user. Use positions@account for live trading state; use this REST endpoint after startup, reconnects, missed messages, audit checks, or settlement windows.

POSTv1/prediction-markets/positions

curl --request POST \
  --url https://api.gemini.com/v1/prediction-markets/positions \
  --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 key

X-GEMINI-SIGNATUREstring·required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOADstring·required

Base64-encoded JSON payload

Content-Typestring

Default: text/plain

Content-Lengthstring

Default: 0

Cache-Controlstring

Default: no-cache

Responses

Successful response

positionsarray

positions[].symbolstring

positions[].instrumentIdinteger (int64)

positions[].totalQuantitystring

Total position size

positions[].quantityOnHoldstring

Quantity currently on hold from open orders

positions[].avgPricestring

Average entry price

positions[].outcomestring·enum

The outcome being traded (Yes or No)Enum values: yesno

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-events

positions[].contractMetadata.startTimestring (date-time)

Start datetime (ISO 8601)

positions[].pricesobject

Current bid/ask/last-trade prices for the contract

positions[].resolutionSidestring

Winning outcome ("yes" or "no") if the contract has resolved

positions[].isAboveAutoStartThresholdboolean

Whether the position is above the auto-start threshold

positions[].isLiveboolean

Whether the market is currently live/active

positions[].realizedPlstring

Realized profit/loss from sells

positions[].marketValuestring

Mark-to-market value of the position in USD at the current sell price (bestBid for YES, bestAsk for NO). **Absent** from the response when the held outcome has no live sell quote (no liquidity to sell into) — surface a no-liquidity state rather than a price the user cannot transact at. `lastTradePrice` is still returned for display. Treat as `Optional<T>`.Example: 65.00

positions[].unrealizedPnlstring

Unrealized P&L in USD (`marketValue - costBasis`). **Absent** whenever `marketValue` is absent. Treat as `Optional<T>`.Example: 12.50

positions[].unrealizedPctnumber (double)

Unrealized P&L as a percentage of cost basis. Expressed as a percent (e.g. `12.5` represents 12.5%, **not** `0.125`); rounded to 4 decimal places. **Absent** when there is no live sell quote, or when cost basis is zero. Treat as `Optional<T>`.Example: 23.81

totalinteger

Total number of positions (for pagination)

Example Responses

{
  "positions": [
    {
      "symbol": "GEMI-FEDJAN26-DN25",
      "instrumentId": 1001,
      "totalQuantity": "125",
      "quantityOnHold": "10",
      "avgPrice": "0.63",
      "outcome": "yes",
      "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": "active",
        "imageUrl": "https://example.com/fed.png",
        "eventImageUrl": "https://example.com/fed-event.png",
        "eventType": "binary",
        "expiryDate": "2026-01-31T23:59:59.000Z",
        "resolvedAt": null,
        "resolutionSide": null,
        "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
      },
      "prices": {
        "buy": {
          "yes": "0.63",
          "no": "0.37"
        },
        "sell": {
          "yes": "0.61",
          "no": "0.35"
        },
        "bestBid": "0.61",
        "bestAsk": "0.63",
        "lastTradePrice": "0.62"
      },
      "resolutionSide": null,
      "isAboveAutoStartThreshold": false,
      "isLive": true,
      "realizedPl": "0",
      "marketValue": "78.75",
      "unrealizedPnl": "0",
      "unrealizedPct": 0
    },
    {
      "symbol": "GEMI-FEDJAN26-DN25",
      "instrumentId": 1001,
      "totalQuantity": "200",
      "quantityOnHold": "0",
      "avgPrice": "0.36",
      "outcome": "no",
      "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": "active",
        "imageUrl": "https://example.com/fed.png",
        "eventImageUrl": "https://example.com/fed-event.png",
        "eventType": "binary",
        "expiryDate": "2026-01-31T23:59:59.000Z",
        "resolvedAt": null,
        "resolutionSide": null,
        "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
      },
      "prices": {
        "buy": {
          "yes": "0.37",
          "no": "0.63"
        },
        "sell": {
          "yes": "0.35",
          "no": "0.61"
        },
        "bestBid": "0.35",
        "bestAsk": "0.37",
        "lastTradePrice": "0.36"
      },
      "resolutionSide": null,
      "isAboveAutoStartThreshold": false,
      "isLive": true,
      "realizedPl": "0",
      "marketValue": "72.00",
      "unrealizedPnl": "0",
      "unrealizedPct": 0
    }
  ],
  "total": 2
}

PreviousPositions NextGet Settled Positions

curl --request POST \ --url https://api.gemini.com/v1/prediction-markets/positions \ --header 'X-GEMINI-APIKEY: <string>' \ --header 'X-GEMINI-PAYLOAD: <string>' \ --header 'X-GEMINI-SIGNATURE: <string>'