Skip to main content
Participants may download a list of the instruments available (or reference data about them) to trade on Polymarket US by submitting a SecurityListRequest [x] message.

​
Table 23: SecurityListRequest (x) message

TagNameReqTypeDescription
< Standard Header >Y35 = x
320SecurityReqIDYStringUnique ID associated with this request.
336TradingSessionIDNStringUsed to filter for instruments by market state (CLOSED, OPEN, PREOPEN, SUSPENDED, EXPIRED, TERMINATED, HALTED, MATCH_AND_CLOSE_AUCTION). Recommended with SecurityListRequestType (559) = 4: without it the reply includes every expired instrument and is an order of magnitude larger than the OPEN set.
559SecurityListRequestTypeYintThe type of request being made (0=Individual symbol, 4=All Securities)
55SymbolCStringRequired if SecurityListRequestType (559) = 0 (individual security)
263SubscriptionRequestTypeNcharOmitted or 0 = snapshot only. 1 = Snapshot + Updates: after the full list, the exchange sends a SecurityDefinitionUpdateReport [BP] (Table 25) for each instrument that is added (SecurityUpdateAction (980) = A) or terminated (980 = D); other state changes are not sent on this subscription. Supported for SecurityListRequestType (559) = 4 only; a single-symbol subscription is rejected with SecurityRequestResult (560) = 1. The subscription ends at logout. 2 = cancel a Snapshot + Updates subscription.
< Standard Trailer >Y
Example 21: Request for information on all open securities
Upon receipt, Polymarket US responds with one or more SecurityList [y] messages containing the requested information. The content of each instrument entry does not differ depending on whether an individual symbol was requested or all securities. Fragmented replies. A reply that matches more instruments than fit in one message is split into fragments of up to 1000 instruments. Every fragment carries the SecurityReqID (320) of the request, its own SecurityResponseID (322), the result in SecurityRequestResult (560), the number of instruments in that fragment in NoRelatedSym (146), and LastFragment (893) = N. The final message carries LastFragment (893) = Y. Accumulate the entries across messages for the same SecurityReqID (320) until a message with LastFragment (893) = Y arrives; the exchange does not send a total count. A request for an individual symbol is always answered in a single message with LastFragment (893) = Y. If the exchange cannot complete a reply, the final message carries SecurityRequestResult (560) = 4 (temporary: retry later) or 1 (the request matched more instruments than the session may receive in one reply: request individual symbols or filter with asset attributes) and no instrument entries; anything already delivered for that request is still valid, but the list is incomplete. One all-securities request is served per session at a time; a second one sent before the first reaches LastFragment (893) = Y is answered with SecurityRequestResult (560) = 4.

​
Table 24: SecurityList (y) message

TagNameReqTypeDescription
< Standard Header >Y35 = y
320SecurityReqIDYStringThe unique SecurityReqID (320) sent on the request.
322SecurityResponseIDYStringUnique ID for this response. Typically a 13 character alphanumeric string.
560SecurityRequestResultYintThe status of the request (0=Valid; 1=Invalid/unsupported, also when the request matched more instruments than the session may receive in one reply, so the same request will not succeed; 2=No instruments found that match selection criteria; 3=Not authorized; 4=Instrument data temporarily unavailable, also while another all-securities reply for the session is still in progress, in which case retry after that reply’s LastFragment (893) = Y; see Text (58))
893LastFragmentYBooleanN = more SecurityList [y] messages follow for this SecurityReqID (320); Y = this is the last one. See “Fragmented replies” above.
58TextNStringExplanation when SecurityRequestResult (560) is not 0, for example why a request was not completed and how to narrow it.
146NoRelatedSymCNumInGroupNumber of instruments in this message (not the total across fragments). 0 when no instruments are returned.
→ 55SymbolYStringInstrument symbol
→ 48SecurityIDYStringWill always equal Symbol (55)
→ 22SecurityIDSourceYint8 = Exchange symbol
→ 167SecurityTypeNStringEVENT=Event contract. Currently, Polymarket only offers EVENT instruments.
→ 231ContractMultiplierNfloatThe ratio or multiplier to convert from “nominal” units (e.g. contracts) to total units (e.g. shares). Applicable for Fixed Income, Derivatives, etc.
→ 864NoEventsYNumInGroupNumber of repeating EventType entries. Will always be 1.
→→ 865EventTypeYintCode to represent the type of event (5=Activation)
→→ 866EventDateYLocalMktDateDate that the instrument first started (or will start) trading on the exchange in YYYYMMDD format.
→→ 868EventTextYStringEvent string. Always ‘StartDate’.
→ 969MinPriceIncrementYfloatMinimum price increment (tick size)
→ 1151SecurityGroupYStringThe name of the group of securities to which this instrument belongs.
→ 562MinTradeVolYQtyThe minimum quantity allowed on an order. This field can be a decimal, indicating the ability to trade fractional shares of this instrument.
→ 15CurrencyYCurrencyCurrency for the instrument.
< Standard Trailer >Y
Example 22: SecurityList [y] reply in two fragments (color-coded) First fragment, more to follow (LastFragment (893) = N):
Final fragment (LastFragment (893) = Y):
In production a request for all open securities is answered in many fragments of 1000 instruments each; the shape is the same.

​
Table 25: SecurityDefinitionUpdateReport (BP) message

Sent on a Snapshot + Updates subscription (SubscriptionRequestType (263) = 1) after the full SecurityList [y] reply, once for each instrument added to or terminated on the exchange. Added instruments carry the same reference fields as a SecurityList [y] entry; a termination carries only the instrument’s identifiers. Instruments filtered out by the request’s asset attributes are not sent.
TagNameReqTypeDescription
< Standard Header >Y35 = BP
320SecurityReqIDYStringThe SecurityReqID (320) of the SecurityListRequest [x] that opened the subscription.
322SecurityResponseIDYStringUnique ID for this message.
980SecurityUpdateActionYcharA = Add (a new instrument is available); D = Delete (the instrument is terminated).
55SymbolCStringInstrument symbol. Present when SecurityUpdateAction (980) = A.
48SecurityIDYStringEquals Symbol (55).
22SecurityIDSourceYint8 = Exchange symbol
167SecurityTypeCStringEVENT = Event contract. Present when 980 = A.
231ContractMultiplierCfloatPresent when 980 = A.
864NoEventsCNumInGroupNumber of instrument dates that follow. Present when 980 = A.
→ 865EventTypeCint5 = Activation (EventText StartDate); 7 = Last eligible trade date (EventText LastTradeDate or ExpirationDate); 6 = Inactivation (EventText TerminationDate).
→ 866EventDateCLocalMktDateDate in YYYYMMDD format.
→ 1145EventTimeNUTCTimestampTime of day for LastTradeDate and ExpirationDate, when set.
→ 868EventTextCStringStartDate, LastTradeDate, ExpirationDate or TerminationDate.
969MinPriceIncrementCfloatMinimum price increment (tick size). Present when 980 = A.
562MinTradeVolCQtyThe minimum quantity allowed on an order. Present when 980 = A.
1306PriceLimitTypeNint0 = Price; 2 = Percentage. Present when the instrument has price limits.
1148LowLimitPriceNPriceLower price limit, when set.
1149HighLimitPriceNPriceUpper price limit, when set.
1150TradingReferencePriceNPriceReference price for percentage limits.
15CurrencyCCurrencyCurrency for the instrument. Present when 980 = A.
< Standard Trailer >Y
Example 23: SecurityDefinitionUpdateReport [BP] for an added and a terminated instrument Instrument added (SecurityUpdateAction (980) = A):
Instrument terminated (980 = D):

​
Figure 16: Request form security reference data