Skip to main content
POST
/
v1
/
refdata
/
instruments
List instruments
curl --request POST \
  --url https://api.prod.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
}

Documentation Index

Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt

Use this file to discover all available pages before exploring further.

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)

PENDING: Initial state for a newly created instrument which has not yet begun trading.

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,
INSTRUMENT_STATE_PENDING
​
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