Skip to main content
Every instrument on the Polymarket Exchange follows a hierarchical structure that organizes markets from broad categories down to specific tradable outcomes.

​
Ontology Overview

The structure is: Category → Subcategory → Series → Event → Product → Instrument(s)
  • Category, Subcategory, Series classify events (e.g., Sports → Soccer → MLS)
  • Events represent real-world occurrences (games, elections, price movements)
  • Products are templates that define different ways to trade those events
  • Instruments are the specific tradable outcomes
A single event can have multiple products applied to it, creating different groups of instruments. Example:
  • Event: mls-atl-clt-2026-03-22 (Atlanta United vs Charlotte FC)
  • Products applied: ATC (3-way outcome), ASC (spreads), TSC (totals)
  • Each product creates its own set of instruments for the same underlying event

​
Complete Example

Here’s a real CBB moneyline instrument as returned by the POST /v1/refdata/instruments API, showing the complete structure with all metadata: 
{
  "symbol": "aec-cbb-char-hamp-2026-02-26",
  "tickSize": 0.01,
  "baseCurrency": "USD",
  "multiplier": 1,
  "minimumTradeQty": "1",
  "startDate": { "year": 2026, "month": 2, "day": 5 },
  "expirationDate": { "year": 2026, "month": 3, "day": 12 },
  "terminationDate": null,
  "tradingSchedule": [],
  "description": "Who will win the college basketball event, scheduled for 2026-02-26, Charleston or Hampton?",
  "clearingHouse": "QCC",
  "minimumUnaffiliatedFirms": "0",
  "nonTradable": false,
  "jsonAttributes": "",
  "productId": "aec-cbb-char-hamp-2026-02-26",
  "priceLimit": {
    "low": "1",
    "high": "99",
    "lowSet": true,
    "highSet": true,
    "relativeLow": 0,
    "relativeHigh": 0,
    "relativeLowSet": false,
    "relativeHighSet": false
  },
  "orderSizeLimit": null,
  "expirationTime": { "hours": 12, "minutes": 0, "seconds": 0 },
  "tradeSettlementPeriod": "0",
  "state": "INSTRUMENT_STATE_OPEN",
  "priceScale": "100",
  "fractionalQtyScale": "0",
  "settlementCurrency": "",
  "settlementPriceScale": "0",
  "metadata": {
    "cftc_instrument_id": "aec-cbb-char-hamp-2026-02-26",
    "clearing_sym": "AEC-NCAA",
    "event_category": "SPR",
    "event_subcategory": "BASKETBALL",
    "event_series": "cbb",
    "event_id": "cbb-char-hamp-2026-02-26",
    "event_start_time": "2026-02-26 16:00:00+00",
    "instrument_product": "aec",
    "instrument_product_series": "aec-cbb",
    "product_id": "aec-cbb-char-hamp-2026-02-26",
    "instrument_rules": "Who will win the upcoming college basketball event, scheduled for February 26 at 11:00AM ET, Charleston or Hampton? ...",
    "participant_type": "team",
    "long_participant_id": "cbb-char",
    "long_participant_name": "Charleston",
    "short_participant_id": "cbb-hamp",
    "short_participant_name": "Hampton",
    "outcome_type": "moneyline",
    "outcome_strike": "char",
    "event_external_id_sportsdataio": "60068117",
    "event_external_id_sportradar": "5c486835-c9a3-423a-b47a-c3fc48fda799"
  },
  "eventAttributes": {
    "positionAccountabilityValue": "50000",
    "payoutValue": "100",
    "question": "CBB 2026 Moneyline Game - Charleston vs Hampton 2026-02-26",
    "eventDisplayName": "Charleston vs. Hampton 2026-02-26",
    "eventId": "aec-cbb-char-hamp-2026-02-26",
    "strikeValue": "0.0",
    "evaluationType": "==",
    "strikeUnit": "decimal",
    "calculationMethod": "CALCULATION_METHOD_VALUE",
    "timeSpecifier": "2026-02-26"
  },
  "createTime": "2026-02-05T12:00:00.000000000Z",
  "updateTime": "2026-02-05T12:00:00.000000000Z"
}
This example shows how all levels (Category → Subcategory → Series → Event → Product → Instrument → Participants → Outcome) come together in a single instrument returned by the API.

​
Event

Events represent specific real-world occurrences (games, elections, price movements). Each event is classified by category, subcategory, and series, and can have multiple products applied to create different groups of instruments. Event ID Format: {series}-{descriptors}-{date/time} Where descriptors vary by event type:
  • Sports: mls-atl-clt-2026-03-22
  • Politics: uspres-2028-11-05
  • Crypto: btc-hit-2026-12-31
  • Culture: oscars-2027-03-28
Metadata Fields:
  • event_id - Unique event identifier (e.g., nfl-hou-mia-2025-12-16)
  • event_start_time - Event start timestamp (UTC)
  • event_category - Category code (e.g., SPR, POL, CRY, FIN)
  • event_subcategory - Subcategory code (e.g., BASKETBALL, football, soccer, coin, uspres)
  • event_series - Series code (e.g., nfl, mls, btc, uspres)
  • event_external_id_sportsdataio - External data provider ID (SportsDataIO)
  • event_external_id_sportradar - External data provider ID (Sportradar)
Example: Event mls-atl-clt-2026-03-22 with multiple products applied:
  • ATC → 3 instruments (atl, draw, clt)
  • ASC → multiple instruments (various spreads)
  • TSC → multiple instruments (various totals)

​
Classification Reference

Categories:
  • SPR - Sports
  • POL - Politics
  • CRY - Crypto
  • CUL - Culture
  • FIN - Finance
  • MAC - Macro
  • CLI - Climate
  • GEO - Geopolitics
  • TECH - Technology
  • MEN - Mentions
Subcategories by Category:
  • SPR: soccer, football, basketball, baseball, combat, tennis, icehockey, ncaa, cricket, esports, golf, motorsport, olympics, rugby
  • POL: uspres, ushse, usstate, ussen, intlpol, legislate, cabinet, fedagency, uscrt
  • CRY: coin, cryptomkt, nft
  • CUL: movies, music, tv, video, awd, people, entertain
  • FIN: indices, forex, treasuries, bankruptcy, corpaction, earnings, ipo, commod
  • CLI: weather, climate, geological, health, space
  • GEO: namer, eur, apac, mena, latam, ssa, conflict, unitednat
  • MAC: growth, inflation, monetary, employment, fiscal
  • TECH: ai, autonom, mobile, platforms, social, compute, cybersec, industry, wear
  • MEN: statement, pressconf, earncall
Series by Subcategory:
  • soccer: epl, laliga, seriea, bund, ligue1, ucl, uel, facup, cara, wcup
  • football: nfl
  • basketball: nba
  • baseball: mlb
  • ncaa: cfb, cbb
  • coin: btc, eth, sol, xrp, bnb, doge, usdc, usdt
  • uspres: usp, prm, pres

​
Product

Products are templates that define types of tradable outcomes. The same product can be applied to events across different series — products define how you trade an event, not what event you’re trading. Metadata Fields:
  • instrument_product - Product code (e.g., aec, asc, atc, tsc)
  • instrument_product_series - Combined product and series (e.g., aec-nfl, atc-mls)
Market Structures:
  • Single (Binary) - One instrument representing yes and no outcomes
  • Group (Exclusive) - Multiple instruments, where only one outcome can be true
  • Group (Directional) - Multiple instruments, where multiple can be true, and the outcomes sit in directional relation
  • Group (Independent) - Multiple instruments, where multiple can be true, but the outcomes do not sit in directional relation

​
Example Products

ProductCodeTypeExampleDescription
Athletic EventAECSingle (Binary)aec-nfl-buf-nyj-2025-01-15Moneyline: Will team A win?
Athletic TieATCGroup (Exclusive)atc-mls-atl-clt-2026-03-22-draw3-way: Team A, Draw, or Team B wins
Athletic SpreadASCGroup (Directional)asc-nfl-hou-mia-2025-12-16-pos-4pt5Will team A win by more than X points?
Total ScoreTSCGroup (Directional)tsc-nfl-ne-den-2026-01-25-47-5Will combined score be over X?
Title EventTECGroup (Exclusive)tec-ggb-bmpd-2026-01-11Will participant win title?
Title AwardTACGroup (Exclusive)tac-ggb-bmpd-2026-01-11-sinnersWhich nominee will win award?
Election WinnerEWCGroup (Exclusive)ewc-usp-pres-2028-11-07Which candidate will win election?
Crypto PriceCPCSingle (Binary)cpc-btc-2026-12-31Price movement in period?

​
Product Reusability

The same product can create instruments across different series: ATC (Athletic Tie Contract) - 3-way match outcome:
  • atc-mls-atl-clt-2026-03-22-draw (MLS)
  • atc-epl-liv-mci-2026-01-15-draw (EPL)
  • atc-ucl-bar-psg-2026-04-20-draw (UCL)
ASC (Athletic Spread Contract) - Point spreads:
  • asc-nfl-hou-mia-2025-12-16-pos-4pt5
  • asc-nba-bos-lal-2026-01-20-pos-6pt5
  • asc-cbb-duke-unc-2026-02-15-pos-3pt5

​
Instrument

Instruments are specific tradable outcomes created by applying a Product to an Event. Each instrument has a globally unique ID that combines the product code, event details, and specific outcome/strike. Instrument ID Format: {product_code}-{event_id}-{strike/outcome} Metadata Fields:
  • instrument_rules - Resolution rules specific to this instrument
Examples:
  • aec-nfl-buf-nyj-2025-01-15 - Moneyline (no additional outcome specified)
  • atc-mls-atl-clt-2026-03-22-draw - 3-way outcome: draw
  • asc-nfl-hou-mia-2025-12-16-pos-4pt5 - Spread: 4.5 points
  • tsc-nfl-ne-den-2026-01-25-47-5 - Total: 47.5 points

​
Participants and Outcome

Each instrument has participants representing the possible outcomes. The long participant represents the “Yes” outcome that traders buy and sell. This is surfaced in instrument metadata:
  • participant_type - Type of participant (team, player, nominee, candidate, etc.)
  • long_participant_id - Globally unique ID for the long side (e.g., cbb-akron, nfl-buf)
  • long_participant_name - Full display name for the long side (e.g., “Akron”, “Buffalo Bills”)
  • short_participant_id - Globally unique ID for the opposing outcome (e.g., cbb-murst, nfl-nyj)
  • short_participant_name - Full display name for the opposing outcome (e.g., “Murray State”, “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.

​
Outcome

  • outcome_type - Type of outcome (e.g., moneyline, spread, total, winner)
  • outcome_strike - Strike value (e.g., 4.5 for a 4.5-point spread, participant abbreviation like ne for moneyline)