{ "openapi": "3.0.3", "x-docs-sync": "GENERATED FILE — rebuilt by scripts/generate-institutional.sh from the upstream protos pinned in scripts/sync/manifest.json; CI (regen-drift) rejects bare hand edits. Quick prose fix: edit this file, then run scripts/sync/capture-overrides.sh and commit it together with the scripts/sync/overrides/ file it writes. Structural changes (fields, types, constraints) belong in scripts/sync/overlays/*.jq or the upstream protos. See README.md, section: Hand edits that survive regeneration.", "info": { "title": "Refdata API", "version": "v1.0.0" }, "servers": [ { "url": "https://api.prod.polymarketexchange.com", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "RefDataAPI" } ], "paths": { "/v1/refdata/instruments": { "post": { "summary": "List instruments", "description": "Returns a list of instruments matching the request", "operationId": "RefDataAPI_ListInstruments", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1ListInstrumentsResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1ListInstrumentsRequest" } } }, "description": "Request for listing instruments.", "required": true }, "tags": [ "ReferenceData" ] } }, "/v1/refdata/metadata": { "post": { "summary": "Get instrument metadata", "description": "Returns miscellaneous instrument metadata", "operationId": "RefDataAPI_GetInstrumentMetadata", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1GetInstrumentMetadataResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1GetInstrumentMetadataRequest" } } }, "description": "Request for getting instrument metadata.", "required": true }, "tags": [ "ReferenceData" ] } }, "/v1/refdata/symbols": { "post": { "summary": "List symbols", "description": "Returns a list of symbols on the exchange", "operationId": "RefDataAPI_ListSymbols", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1ListSymbolsResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1ListSymbolsRequest" } } }, "description": "Request for listing symbols.", "required": true }, "tags": [ "ReferenceData" ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "v1Date": { "type": "object", "properties": { "year": { "type": "integer", "format": "int32" }, "month": { "type": "integer", "format": "int32" }, "day": { "type": "integer", "format": "int32" } }, "description": "Date represents a calendar date." }, "v1EventAttributes": { "type": "object", "properties": { "question": { "type": "string", "description": "The question or description of the event outcome." }, "payoutValue": { "type": "string", "description": "The payout value when the event resolves (e.g., \"1000\")." }, "evaluationType": { "type": "string", "description": "The evaluation type for resolution (e.g., \">\", \"<\", \"=\")." }, "eventId": { "type": "string", "description": "Unique event identifier." }, "eventDisplayName": { "type": "string", "description": "Human-readable display name for the event." }, "strikeValue": { "type": "string", "description": "Strike value for evaluation." }, "strikeUnit": { "type": "string", "description": "Unit for strike value (e.g., \"decimal\", \"percentage\")." }, "calculationMethod": { "type": "string", "description": "Calculation method for settlement." }, "positionAccountabilityValue": { "type": "string", "description": "Position accountability limit value." }, "timeSpecifier": { "$ref": "#/components/schemas/v1Date", "description": "Time specifier for the event" }, "eventOutcome": { "type": "string", "description": "The relationship of instrument outcomes within the event:\n\"EVENT_OUTCOME_MUTUALLY_EXCLUSIVE\" (exactly one instrument in the event resolves YES),\n\"EVENT_OUTCOME_DIRECTIONAL\" (instruments are strike-ranked; YES at one strike implies\nYES for in-the-money strikes), or \"EVENT_OUTCOME_INDEPENDENT\" (each instrument resolves\non its own; also the default when the exchange has not set an outcome type)." } }, "description": "EventAttributes contains event-specific instrument attributes." }, "v1FieldFilter": { "type": "object", "properties": { "field": { "type": "string", "description": "Column name to filter on." }, "operator": { "$ref": "#/components/schemas/v1FilterOperator", "description": "Comparison operator" }, "stringValue": { "type": "string", "description": "String value to compare against (for EQ, LIKE)" }, "intValue": { "type": "string", "format": "int64" }, "doubleValue": { "type": "number", "format": "double" }, "stringList": { "$ref": "#/components/schemas/v1StringList", "description": "List of string values (for IN operator)" } }, "description": "FieldFilter for structured filtering." }, "v1FilterOperator": { "type": "string", "enum": [ "FILTER_OPERATOR_EQ", "FILTER_OPERATOR_NE", "FILTER_OPERATOR_LT", "FILTER_OPERATOR_LE", "FILTER_OPERATOR_GT", "FILTER_OPERATOR_GE", "FILTER_OPERATOR_LIKE", "FILTER_OPERATOR_IN", "FILTER_OPERATOR_NOT_IN" ], "description": "FilterOperator defines comparison operators for FieldFilter.\n\n - FILTER_OPERATOR_EQ: =\n - FILTER_OPERATOR_NE: !=\n - FILTER_OPERATOR_LT: <\n - FILTER_OPERATOR_LE: <=\n - FILTER_OPERATOR_GT: >\n - FILTER_OPERATOR_GE: >=\n - FILTER_OPERATOR_LIKE: LIKE (SQL pattern with % and _ wildcards)\n - FILTER_OPERATOR_IN: IN (list)\n - FILTER_OPERATOR_NOT_IN: NOT IN (list)" }, "v1GetInstrumentMetadataRequest": { "type": "object", "description": "Request for getting instrument metadata." }, "v1GetInstrumentMetadataResponse": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Response with instrument metadata." }, "v1Instrument": { "type": "object", "properties": { "symbol": { "type": "string" }, "tickSize": { "type": "number", "format": "double" }, "baseCurrency": { "type": "string" }, "multiplier": { "type": "number", "format": "double" }, "minimumTradeQty": { "type": "string", "format": "int64" }, "startDate": { "$ref": "#/components/schemas/v1Date" }, "expirationDate": { "$ref": "#/components/schemas/v1Date" }, "terminationDate": { "$ref": "#/components/schemas/v1Date" }, "tradingSchedule": { "type": "array", "items": { "$ref": "#/components/schemas/v1TradingHours" } }, "description": { "type": "string" }, "clearingHouse": { "type": "string" }, "minimumUnaffiliatedFirms": { "type": "string", "format": "int64" }, "nonTradable": { "type": "boolean", "title": "type_attributes omitted - complex oneof with many swap types" }, "jsonAttributes": { "type": "string" }, "productId": { "type": "string" }, "priceLimit": { "$ref": "#/components/schemas/v1PriceLimit" }, "orderSizeLimit": { "$ref": "#/components/schemas/v1OrderSizeLimit" }, "expirationTime": { "$ref": "#/components/schemas/v1TimeOfDay" }, "tradeSettlementPeriod": { "type": "string", "format": "int64" }, "state": { "$ref": "#/components/schemas/v1InstrumentState" }, "priceScale": { "type": "string", "format": "int64" }, "fractionalQtyScale": { "type": "string", "format": "int64" }, "settlementCurrency": { "type": "string" }, "settlementPriceScale": { "type": "string", "format": "int64" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-instrument metadata from the exchange Attributes.Metadata map.\nContains sports metadata like game_id, team abbreviations, league, etc." }, "eventAttributes": { "$ref": "#/components/schemas/v1EventAttributes" }, "createTime": { "type": "string", "format": "date-time", "description": "Creation timestamp of the instrument." }, "updateTime": { "type": "string", "format": "date-time", "description": "Last update timestamp of the instrument." } }, "description": "Instrument represents a tradable instrument." }, "v1InstrumentFilter": { "type": "object", "properties": { "whereClause": { "type": "string", "title": "SQL WHERE clause fragment (without the WHERE keyword).\nAllowed operators: =, !=, <, <=, >, >=, LIKE, IN, AND, OR, NOT\nAllowed columns: symbol, state, product_id, event_series, event_category, market_category,\n market_type, game_id, clearing_sym, start_date, expiration_date,\n event_id, event_question, event_outcome, non_tradable, tick_size\nExample: \"symbol LIKE 'aec-nfl-%' AND state = 'INSTRUMENT_STATE_OPEN'\"", "description": "SQL-like string expression. Supported operators: =, LIKE (with % wildcard), AND. Supported columns: state, symbol, event_series, event_category, clearing_sym, clearing_house, product_id. Do NOT use instrument_product, outcome_type, or event_subcategory (causes HTTP 500)." }, "fieldFilters": { "type": "array", "items": { "$ref": "#/components/schemas/v1FieldFilter" }, "description": "Structured type-safe filters (ANDed with where_clause if both provided)." } }, "description": "InstrumentFilter for advanced queries." }, "v1InstrumentState": { "type": "string", "enum": [ "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" ], "description": "**PENDING**: Initial state for a newly created instrument which has not yet begun trading.\n\n**CLOSED**: No order entry, modification, cancellation, or matching. Day orders expired.\n\n**OPEN**: Continuous order entry and matching.\n\n**PREOPEN**: Orders accepted, no matching. Dutch Auction on transition to OPEN.\n\n**MATCH_AND_CLOSE_AUCTION**: Like PREOPEN, matches on transition out.\n\n**SUSPENDED**: Cancel only. No entry, modification, or matching.\n\n**HALTED**: Like SUSPENDED, no cancels allowed.\n\n**EXPIRED**: All resting orders expired, no new orders.\n\n**TERMINATED**: Order book removed, all orders and positions closed." }, "v1InstrumentType": { "type": "string", "enum": [ "INSTRUMENT_TYPE_DEFAULT", "INSTRUMENT_TYPE_FUTURE", "INSTRUMENT_TYPE_OPTION", "INSTRUMENT_TYPE_MULTILEG", "INSTRUMENT_TYPE_IRS", "INSTRUMENT_TYPE_FRA", "INSTRUMENT_TYPE_FSIRS", "INSTRUMENT_TYPE_BASIS", "INSTRUMENT_TYPE_EVENT", "INSTRUMENT_TYPE_OIS", "INSTRUMENT_TYPE_SPS", "INSTRUMENT_TYPE_NDF", "INSTRUMENT_TYPE_FOREX", "INSTRUMENT_TYPE_ZCIS", "INSTRUMENT_TYPE_XCCY" ], "description": "InstrumentType represents the type of instrument." }, "v1ListInstrumentsRequest": { "type": "object", "properties": { "pageSize": { "type": "integer", "format": "int32", "title": "=== Pagination ===", "description": "Results per page (default: 50, max: 1000)" }, "pageToken": { "type": "string", "description": "Pagination cursor from previous response" }, "symbols": { "type": "array", "items": { "type": "string" }, "title": "=== Existing filters (backwards compatible) ===", "description": "Filter by specific instrument symbols" }, "productId": { "type": "string", "description": "Filter by product ID" }, "tradableFilter": { "$ref": "#/components/schemas/v1TradableFilter", "description": "Filter tradable vs non-tradable instruments" }, "states": { "type": "array", "items": { "$ref": "#/components/schemas/v1InstrumentState" }, "description": "Filter by instrument states (e.g., INSTRUMENT_STATE_OPEN)" }, "type": { "$ref": "#/components/schemas/v1InstrumentType" }, "eventSeries": { "type": "string", "description": "Filter by event series (e.g., \"cbb\", \"nfl\", \"nba\").\nMatches instruments where metadata[\"event_series\"] equals this value." }, "marketCategory": { "type": "string", "description": "Filter by market category (e.g., \"sports\", \"politics\", \"crypto\")." }, "marketType": { "type": "string", "description": "Filter by market type (e.g., \"moneyline\", \"spread\", \"over_under\")." }, "gameId": { "type": "string", "description": "Filter by game ID (provider-specific game identifier)." }, "clearingSym": { "type": "string", "description": "Filter by clearing symbol prefix (e.g., \"AEC-NFL\", \"AEC-NBA\")." }, "eventCategory": { "type": "string", "description": "Filter by event category (e.g., \"SPR\" for sports, \"POL\" for politics).\nMatches instruments where metadata[\"event_category\"] equals this value." }, "startTimeGte": { "type": "string", "description": "Filter instruments with start_date >= this value (format: \"2025-01-01\" or timestamp).\nReturns instruments that start on or after this date." }, "startTimeLte": { "type": "string", "description": "Filter instruments with start_date <= this value (format: \"2025-01-01\" or timestamp).\nReturns instruments that start on or before this date." }, "endTimeGte": { "type": "string", "description": "Filter instruments with expiration_date >= this value (format: \"2025-01-01\" or timestamp).\nReturns instruments that expire on or after this date." }, "endTimeLte": { "type": "string", "description": "Filter instruments with expiration_date <= this value (format: \"2025-01-01\" or timestamp).\nReturns instruments that expire on or before this date." }, "filter": { "$ref": "#/components/schemas/v1InstrumentFilter", "description": "Advanced filter with whereClause and/or fieldFilters (ANDed together if both provided)" } }, "description": "Request for listing instruments." }, "v1ListInstrumentsResponse": { "type": "object", "properties": { "instruments": { "type": "array", "items": { "$ref": "#/components/schemas/v1Instrument" }, "description": "List of matching instruments" }, "nextPageToken": { "type": "string", "description": "Token for fetching next page (empty if no more results)" }, "eof": { "type": "boolean", "description": "True when no more results available" } }, "description": "Response with list of instruments." }, "v1ListSymbolsRequest": { "type": "object", "description": "Request for listing symbols." }, "v1ListSymbolsResponse": { "type": "object", "properties": { "symbols": { "type": "array", "items": { "type": "string" } } }, "description": "Response with list of symbols." }, "v1OrderSizeLimit": { "type": "object", "properties": { "low": { "type": "string", "format": "int64" }, "high": { "type": "string", "format": "int64" }, "lowSet": { "type": "boolean" }, "highSet": { "type": "boolean" }, "totalNotionalLow": { "type": "string", "format": "int64" }, "totalNotionalHigh": { "type": "string", "format": "int64" }, "totalNotionalLowSet": { "type": "boolean" }, "totalNotionalHighSet": { "type": "boolean" } }, "description": "OrderSizeLimit describes optional order size limits on an instrument." }, "v1PriceLimit": { "type": "object", "properties": { "low": { "type": "string", "format": "int64" }, "high": { "type": "string", "format": "int64" }, "lowSet": { "type": "boolean" }, "highSet": { "type": "boolean" }, "relativeLow": { "type": "number", "format": "double" }, "relativeHigh": { "type": "number", "format": "double" }, "relativeLowSet": { "type": "boolean" }, "relativeHighSet": { "type": "boolean" } }, "description": "PriceLimit describes optional price limits on an instrument." }, "v1StringList": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" }, "description": "List of string values" } }, "description": "StringList for IN/NOT IN operators." }, "v1TimeOfDay": { "type": "object", "properties": { "hours": { "type": "integer", "format": "int32" }, "minutes": { "type": "integer", "format": "int32" }, "seconds": { "type": "integer", "format": "int32" } }, "description": "TimeOfDay represents a time of day." }, "v1TradableFilter": { "type": "string", "enum": [ "TRADABLE_FILTER_NON_TRADABLE", "TRADABLE_FILTER_TRADABLE" ], "description": "TradableFilter for filtering instruments by tradability." }, "v1TradingHours": { "type": "object", "properties": { "daysOfWeek": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "timeOfDay": { "$ref": "#/components/schemas/v1TimeOfDay" }, "duration": { "type": "string" }, "state": { "$ref": "#/components/schemas/v1InstrumentState" }, "hideMarketData": { "type": "boolean" }, "expireAllOrders": { "type": "boolean" } }, "description": "TradingHours describes an instrument trading schedule segment." } } } }