Reference Data

Reference data provides information about available instruments and symbols on the Polymarket Exchange.

Overview

The Reference Data API provides three endpoints:

List Instruments - Returns complete instrument definitions including symbol, trading rules, state, dates, price limits, and market-specific metadata
List Symbols - Returns just the symbol identifiers (trading symbols) without full instrument details
Get Metadata - Returns server-level metadata about the exchange (not instrument-specific)

Required Scope

Scope	Data Access
`read:instruments`	All reference data endpoints

Asset Master Structure

Every instrument on the Polymarket Exchange follows a hierarchical structure that organizes markets by category, series, event, and product type.

Series

A more specific classification within each category, such as sports leagues, specific topics, or individual assets. Examples include:

National Hockey League (NHL)
National Basketball Association (NBA)
National Football League (NFL)
College Basketball (CBB)
College Football (CFB)
Golden Globes (GGB)
US Presidential (USP)
US Midterms (USM)
Bitcoin (BTC)
Ethereum (ETH)

Event

Events represent specific occurrences with multiple possible outcomes. Each event consists of one or more instruments representing the complete set of outcomes traders can speculate on. Examples include:

SPR: nfl-hou-mia-2025-12-16
POL: usp-pres-2028-11-07
CRY: btc-15min-updown-1765593600

Product

The type of contract structure used to format instruments associated with an event. Each product is documented in full on polymarketexchange.com. Examples include:

Athletic Event Contract (AEC) - Game winner instruments
Athletic Spread Contract (ASC) - Game point spread instruments
Total Score Contract (TSC) - Game point total instruments
Title Event Contract (TEC) - Sport title winner instruments
Title Award Contract (TAC) - Culture title winner instruments
Election Winner Contract (EWC) - Election winner instruments

Instrument

The tradable symbol, which follows consistent naming conventions and metadata practices to allow for easy identification and sorting. Examples include:

SPR-AEC-NFL: aec-nfl-buf-nyj-2025-01-15
SPR-ASC-NFL: asc-nfl-hou-mia-2025-12-16-4-5
CUL-TAC-GGB: tac-ggb-bmpd-2026-01-11-sinners

Participants

Each instrument has participants representing the possible outcomes. In instrument metadata, participants are identified with these fields:

participant_type - Type of participant (team, player, nominee, candidate, etc.)
long_participant_id - Globally unique ID (series-abbreviation format, e.g., nfl-buf)
short_participant_id - Globally unique ID for the other outcome (e.g., nfl-nyj)
long_participant_name - Full display name (e.g., “Buffalo Bills”)
short_participant_name - Full display name for the other outcome (e.g., “New York Jets”)

Instruments are traded by buying and selling the long participant (the “Yes” outcome). For example, in an NFL moneyline contract like nfl-hou-mia-2025-12-16, traders buy and sell HOU. Buying HOU means taking a long position on Houston winning, while selling HOU creates a synthetic long position on Miami. There is no direct way to trade the short participant - all positions on the opposing outcome are achieved synthetically by selling the long participant. When you sell (short) an instrument, the cash flows differ from buying. Selling 10 contracts at

0.60 means you receive

6 from the buyer, but a margin requirement equal to the maximum payout (

10 in this case) is imposed on your account. Therefore, you need

4 in available funds to enter this short position (

10 margin requirement minus

6 received). This margin requirement ensures you can cover the full payout if the outcome occurs.

REST API Endpoints

List Instruments

Retrieve all available instruments:

curl -X POST "https://api.preprod.polymarketexchange.com/v1/refdata/instruments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "instruments": [
    {
      "symbol": "aec-nfl-buf-nyj-2025-01-15",
      "description": "Who will win the upcoming NFL game scheduled for January 15 2025 at 1:00PM ET, Buffalo Bills or New York Jets?",
      "state": "INSTRUMENT_STATE_OPEN",
      "tickSize": 0.001,
      "minimumTradeQty": "1",
      "baseCurrency": "USD",
      "settlementCurrency": "USD",
      "multiplier": 1,
      "productId": "aec-nfl-buf-nyj-2025-01-15",
      "startDate": {
        "year": 2025,
        "month": 1,
        "day": 8
      },
      "expirationDate": {
        "year": 2025,
        "month": 1,
        "day": 16
      },
      "priceLimit": {
        "low": "1",
        "high": "999",
        "lowSet": true,
        "highSet": true
      },
      "metadata": {
        "event_category": "spr",
        "event_series": "nfl",
        "product_id": "aec-nfl-buf-nyj-2025-01-15",
        "instrument_product": "aec",
        "instrument_product_series": "aec-nfl",
        "participant_type": "team",
        "long_participant_id": "nfl-buf",
        "short_participant_id": "nfl-nyj",
        "long_participant_name": "Buffalo Bills",
        "short_participant_name": "New York Jets",
        "outcome_type": "moneyline",
        "outcome_strike": "0.0",
        "clearing_sym": "AEC-NFL",
        "cftc_instrument_id": "aec-nfl-buf-nyj-2025-01-15"
      }
    }
  ]
}

List Symbols

Retrieve all trading symbols:

curl -X POST "https://api.preprod.polymarketexchange.com/v1/refdata/symbols" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "symbols": [
    "aec-nfl-buf-nyj-2025-01-15",
    "aec-nba-bos-lal-2025-01-20",
    "aec-nhl-tor-mtl-2025-01-18"
  ]
}

Get Exchange Metadata

Retrieve server-level metadata about the exchange:

curl -X POST "https://api.preprod.polymarketexchange.com/v1/refdata/metadata" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "metadata": {
    "exchange_name": "Polymarket Exchange",
    "server_version": "v1.0.0",
    "timezone": "America/New_York"
  }
}

Note: For instrument-specific metadata (participant names, event details, etc.), use the /v1/refdata/instruments endpoint which includes a metadata field in each instrument object.

Instrument Lifecycle

Instruments go through the following states:

State	Description
`INSTRUMENT_STATE_PENDING`	Instrument created but not yet active
`INSTRUMENT_STATE_CLOSED`	No trading can occur
`INSTRUMENT_STATE_OPEN`	Available for full trading
`INSTRUMENT_STATE_PREOPEN`	Can place/modify orders before opening, no matching
`INSTRUMENT_STATE_SUSPENDED`	Trading temporarily suspended, can cancel but not place/modify
`INSTRUMENT_STATE_EXPIRED`	Instrument has expired
`INSTRUMENT_STATE_TERMINATED`	Instrument has been terminated
`INSTRUMENT_STATE_HALTED`	Trading halted, no orders can be placed, modified, or cancelled
`INSTRUMENT_STATE_MATCH_AND_CLOSE_AUCTION`	Can place/modify orders, no matching until state exits

Best Practices

Caching

Reference data changes infrequently. Cache locally and refresh periodically:

import time

class ReferenceDataCache:
    def __init__(self, api_client, refresh_interval=300):
        self.api_client = api_client
        self.refresh_interval = refresh_interval
        self.instruments = {}
        self.last_refresh = 0

    def get_instruments(self):
        if time.time() - self.last_refresh > self.refresh_interval:
            self._refresh()
        return self.instruments

    def _refresh(self):
        response = self.api_client.list_instruments()
        self.instruments = {i['symbol']: i for i in response['instruments']}
        self.last_refresh = time.time()

Filtering

Filter by instrument state:

curl -X POST "https://api.preprod.polymarketexchange.com/v1/refdata/instruments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "states": ["INSTRUMENT_STATE_OPEN"]
  }'

Filter by metadata (e.g., specific sports series):

curl -X POST "https://api.preprod.polymarketexchange.com/v1/refdata/instruments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "event_series": "nfl"
    }
  }'

Handling Updates

Subscribe to instrument updates for real-time changes
Check instrument status before placing orders
Monitor for new instruments being listed

Next Steps

Market Data

Access real-time and historical market data

REST API Reference

Full reference data API documentation

Data Guide

Reference Data

Reference Data

Overview

Required Scope

Asset Master Structure

Category

Series

Event

Product

Instrument

Participants

REST API Endpoints

List Instruments

List Symbols

Get Exchange Metadata

Instrument Lifecycle

Best Practices

Caching

Filtering

Handling Updates

Next Steps

Market Data

REST API Reference

Data Guide

​Reference Data

​Overview

​Required Scope

​Asset Master Structure

​Category

​Series

​Event

​Product

​Instrument

​Participants

​REST API Endpoints

​List Instruments

​List Symbols

​Get Exchange Metadata

​Instrument Lifecycle

​Best Practices

​Caching

​Filtering

​Handling Updates

​Next Steps

Market Data

REST API Reference

Reference Data

Overview

Required Scope

Asset Master Structure

Category

Series

Event

Product

Instrument

Participants

REST API Endpoints

List Instruments

List Symbols

Get Exchange Metadata

Instrument Lifecycle

Best Practices

Caching

Filtering

Handling Updates

Next Steps