Skip to main content
POST
/
v1
/
refdata
/
instruments
List instruments
curl --request POST \
  --url https://api.polymarketexchange.com/v1/refdata/instruments \
  --header 'Content-Type: application/json' \
  --data '
{
  "pageSize": 123,
  "pageToken": "<string>",
  "symbols": [
    "<string>"
  ],
  "productId": "<string>",
  "tradableFilter": "TRADABLE_FILTER_TRADABLE",
  "states": [
    "INSTRUMENT_STATE_CLOSED"
  ],
  "eventSeries": "<string>",
  "eventCategory": "<string>",
  "clearingSym": "<string>",
  "startTimeGte": "<string>",
  "startTimeLte": "<string>",
  "endTimeGte": "<string>",
  "endTimeLte": "<string>",
  "filter": {
    "whereClause": "<string>",
    "fieldFilters": [
      {
        "field": "<string>",
        "operator": "FILTER_OPERATOR_UNSPECIFIED",
        "stringValue": "<string>",
        "stringList": {
          "values": [
            "<string>"
          ]
        }
      }
    ]
  }
}
'
{
  "instruments": [
    {
      "symbol": "<string>",
      "tickSize": 123,
      "baseCurrency": "<string>",
      "multiplier": 123,
      "minimumTradeQty": "<string>",
      "startDate": {
        "year": 123,
        "month": 123,
        "day": 123
      },
      "expirationDate": {
        "year": 123,
        "month": 123,
        "day": 123
      },
      "terminationDate": {
        "year": 123,
        "month": 123,
        "day": 123
      },
      "tradingSchedule": [
        {
          "daysOfWeek": [
            123
          ],
          "timeOfDay": {
            "hours": 123,
            "minutes": 123,
            "seconds": 123
          },
          "duration": "<string>",
          "state": "INSTRUMENT_STATE_CLOSED",
          "hideMarketData": true,
          "expireAllOrders": true
        }
      ],
      "description": "<string>",
      "clearingHouse": "<string>",
      "minimumUnaffiliatedFirms": "<string>",
      "nonTradable": true,
      "jsonAttributes": "<string>",
      "productId": "<string>",
      "priceLimit": {
        "low": "<string>",
        "high": "<string>",
        "lowSet": true,
        "highSet": true,
        "relativeLow": 123,
        "relativeHigh": 123,
        "relativeLowSet": true,
        "relativeHighSet": true
      },
      "orderSizeLimit": {
        "low": "<string>",
        "high": "<string>",
        "lowSet": true,
        "highSet": true,
        "totalNotionalLow": "<string>",
        "totalNotionalHigh": "<string>",
        "totalNotionalLowSet": true,
        "totalNotionalHighSet": true
      },
      "expirationTime": {
        "hours": 123,
        "minutes": 123,
        "seconds": 123
      },
      "tradeSettlementPeriod": "<string>",
      "state": "INSTRUMENT_STATE_CLOSED",
      "priceScale": "<string>",
      "fractionalQtyScale": "<string>",
      "settlementCurrency": "<string>",
      "settlementPriceScale": "<string>",
      "metadata": {},
      "eventAttributes": {
        "question": "<string>",
        "payoutValue": "<string>",
        "eventDisplayName": "<string>",
        "eventId": "<string>",
        "strikeValue": "<string>",
        "evaluationType": "<string>",
        "strikeUnit": "<string>",
        "calculationMethod": "<string>",
        "timeSpecifier": "<string>",
        "positionAccountabilityValue": "<string>"
      },
      "createTime": "2023-11-07T05:31:56Z",
      "updateTime": "2023-11-07T05:31:56Z"
    }
  ],
  "nextPageToken": "<string>",
  "eof": true
}

Body

application/json

Request for listing instruments with optional filters and pagination.

pageSize
integer<int32>

Results per page (default: 50, max: 1000)

pageToken
string

Pagination cursor from previous response

symbols
string[]

Filter by specific instrument symbols

productId
string

Filter by product ID

tradableFilter
enum<string>

Filter tradable vs non-tradable instruments

Available options:
TRADABLE_FILTER_TRADABLE,
TRADABLE_FILTER_NON_TRADABLE,
TRADABLE_FILTER_ALL
states
enum<string>[]

Filter by instrument states (e.g., INSTRUMENT_STATE_OPEN)

CLOSED: No order entry, modification, cancellation, or matching. Day orders expired.

OPEN: Continuous order entry and matching.

PREOPEN: Orders accepted, no matching. Dutch Auction on transition to OPEN.

MATCH_AND_CLOSE_AUCTION: Like PREOPEN, matches on transition out.

SUSPENDED: Cancel only. No entry, modification, or matching.

HALTED: Like SUSPENDED, no cancels allowed.

EXPIRED: All resting orders expired, no new orders.

TERMINATED: Order book removed, all orders and positions closed.

Available options:
INSTRUMENT_STATE_CLOSED,
INSTRUMENT_STATE_OPEN,
INSTRUMENT_STATE_PREOPEN,
INSTRUMENT_STATE_SUSPENDED,
INSTRUMENT_STATE_EXPIRED,
INSTRUMENT_STATE_TERMINATED,
INSTRUMENT_STATE_HALTED,
INSTRUMENT_STATE_MATCH_AND_CLOSE_AUCTION
eventSeries
string

Filter by event series (e.g., 'nfl', 'nba', 'cbb')

eventCategory
string

Filter by event category (e.g., 'SPR', 'POL', 'CRY')

clearingSym
string

Filter by clearing symbol prefix (e.g., 'AEC-NFL')

startTimeGte
string

Filter instruments starting on or after this date (format: 'YYYY-MM-DD')

startTimeLte
string

Filter instruments starting on or before this date

endTimeGte
string

Filter instruments expiring on or after this date

endTimeLte
string

Filter instruments expiring on or before this date

filter
object

Advanced filter with whereClause and/or fieldFilters (ANDed together if both provided)

Response

200 - application/json

A successful response.

Response with list of instruments and pagination info.

instruments
object[]

List of matching instruments

nextPageToken
string

Token for fetching next page (empty if no more results)

eof
boolean

True when no more results available