Looking for Polymarket International documentation?
Visit International Docs →
# What is Polymarket US?
Source: https://docs.polymarket.us/getting-started/what-is-polymarket-us
Polymarket US is a CFTC-regulated exchange for trading event contracts on real-world outcomes. Each market asks a clear yes/no question about something that might happen, and prices reflect how likely traders think the outcome is.
## Polymarket vs Polymarket US
**Polymarket** is our international, crypto-based product that operates on blockchain technology.
**Polymarket US** is a fiat-based, US-regulated platform operating as a designated contract market (DCM) and derivatives clearing organization (DCO) under CFTC oversight. All trading is conducted in US dollars with full regulatory compliance.
# Polymarket US ![US flag]()
Documentation
```typescript TypeScript theme={null}
import { PolymarketUS } from 'polymarket-us';
const client = new PolymarketUS({
keyId: process.env.POLYMARKET_KEY_ID,
secretKey: process.env.POLYMARKET_SECRET_KEY,
});
const order = await client.orders.create({
marketSlug: 'chiefs-super-bowl-lx',
intent: 'ORDER_INTENT_BUY_LONG',
type: 'ORDER_TYPE_LIMIT',
price: { value: '0.55', currency: 'USD' },
quantity: 100,
tif: 'TIME_IN_FORCE_GOOD_TILL_CANCEL',
});
```
```python Python theme={null}
import os
from polymarket_us import PolymarketUS
client = PolymarketUS(
key_id=os.environ["POLYMARKET_KEY_ID"],
secret_key=os.environ["POLYMARKET_SECRET_KEY"],
)
order = client.orders.create({
"marketSlug": "chiefs-super-bowl-lx",
"intent": "ORDER_INTENT_BUY_LONG",
"type": "ORDER_TYPE_LIMIT",
"price": {"value": "0.55", "currency": "USD"},
"quantity": 100,
"tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL",
})
```
Build on the world's largest prediction market.
## Developer Quickstart
Make your first API request in minutes. Learn the basics of the Polymarket US platform, fetch market data, place orders, and redeem winning positions.
## Get Familiar with Polymarket US
Set up your environment and make your first API call in minutes.
Understand markets, events, and how trading works.
Explore REST endpoints, WebSocket streams, and authentication.
Official Python and TypeScript libraries for faster development.
Learn the fundamentals, explore our APIs, and start building on the world's largest prediction market.
| Program | Access | Description |
|---|---|---|
| User Incentive Programs | ||
| Deposit Incentive Program | Open | Earn incentive credits for making a qualifying deposit |
| Refer-A-Friend Incentive Program | Open | Earn incentive credits for referring your friends |
| Daily Trading Incentive Program | Coming Soon | Earn incentive credits for daily trading activity |
| Deposit and Trading Incentive Program | Coming Soon | Earn incentive credits for qualifying deposit and trading activity |
| Institutional Incentive Programs | ||
| Volume Incentive Program | Open | Rewards for taker trading volume |
| Liquidity Incentive Program | Open | Rewards for placing resting orders, whether they fill or not — see the live rewards schedule |
| Market Maker Program | Application | Strong incentives for providing stable liquidity across a variety of markets |
| Affiliate Incentive Programs | ||
| Referral Incentive Program | Application | Rewards for referring new traders to Polymarket US |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = x | ||
| 320 | SecurityReqID | Y | String | Unique ID associated with this request. |
| 336 | TradingSessionID | N | String | Used to filter for instruments by market state (CLOSED, OPEN, PREOPEN, SUSPENDED, EXPIRED, TERMINATED, HALTED, MATCH\_AND\_CLOSE\_AUCTION) |
| 559 | SecurityListRequestType | Y | int | The type of request being made (0=Individual symbol, 4=All Securities) |
| 55 | Symbol | C | String | Required if SecurityListRequestType (559) = 0 (individual security) |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = y | ||
| 320 | SecurityReqID | Y | String | The unique SecurityReqID (320) sent on the request. |
| 322 | SecurityResponseID | Y | String | Unique ID for this response. Typically a 13 character alphanumeric string. |
| 560 | SecurityRequestResult | Y | int | The status of the request (0=Valid, 1=Invalid/unsupported, 3=Not authorized) |
| 146 | NoRelatedSym | C | NumInGroup | Number of instruments to be returned. Only present for valid requests. |
| → 55 | Symbol | Y | String | Instrument symbol |
| → 48 | SecurityID | Y | String | Will always equal Symbol (55) |
| → 22 | SecurityIDSource | Y | int | 8 = Exchange symbol |
| → 167 | SecurityType | N | String | EVENT=Event contract. Currently, Polymarket only offers EVENT instruments. |
| → 231 | ContractMultiplier | N | float | The ratio or multiplier to convert from "nominal" units (e.g. contracts) to total units (e.g. shares). Applicable for Fixed Income, Derivatives, etc. |
| → 864 | NoEvents | Y | NumInGroup | Number of repeating EventType entries. Will always be 1. |
| →→ 865 | EventType | Y | int | Code to represent the type of event (5=Activation) |
| →→ 866 | EventDate | Y | LocalMktDate | Date that the instrument first started (or will start) trading on the exchange in YYYYMMDD format. |
| →→ 868 | EventText | Y | String | Event string. Always 'StartDate'. |
| → 969 | MinPriceIncrement | Y | float | Minimum price increment (tick size) |
| → 1151 | SecurityGroup | Y | String | The name of the group of securities to which this instrument belongs. |
| → 562 | MinTradeVol | Y | Qty | The minimum quantity allowed on an order. This field can be a decimal, indicating the ability to trade fractional shares of this instrument. |
| → 15 | Currency | Y | Currency | Currency for the instrument. |
| \< Standard Trailer > | Y |
'N' = False/No | char field containing one of two possible values. | | String | Case-sensitive, alphanumeric string. | Can include any character or punctuation except the delimiter. All String fields are case sensitive (i.e. morstatt != Morstatt). | | MultipleCharValue | Space-delimited sequence of single character values | string field containing one or more space-delimited values (e.g. \| 18=G c \| ). | | Currency | Three character string. | string field representing a currency type using ISO 4217 Currency code (3 character) values. | | UTCTimestamp | Formatted UTC timestamp (date and time) | string field representing time/date combination represented in UTC in either:
YYYYMMDD-HH:MM:SS (whole seconds) or
YYYYMMDD-HH:MM:SS.sss\_format
Where:
SS can be 60 seconds in the rare case of UTC leap second, and
sss\_ represents fractions of seconds, either
3 digits to represent milliseconds,
6 digits to convey microseconds,
9 digits to convey nanoseconds, or
12 digits to convey picoseconds. | | UTCTimeOnly | Formatted UTC timestamp (time only) | string field representing a time represented in UTC in either:
HH:MM:SS (whole seconds) or
HH:MM:SS.sss\* format | | UTCDateOnly | Formatted UTC timestamp (date only) | string field representing Date represented in UTC in YYYYMMDD format. | | LocalMktDate | Date in the timezone local to the sender | string field representing Date represented in sender's timezone in YYYYMMDD format. | ## Additional Time/Date Field Details **UTCTimeOnly** * Formatted UTC timestamp (time only) * string field representing a time represented in UTC in either: * HH:MM:SS (whole seconds) or * HH:MM:SS.sss\* format **UTCDateOnly** * Formatted UTC timestamp (date only) * string field representing Date represented in UTC in YYYYMMDD format. **LocalMktDate** * Date in the timezone local to the sender * string field representing Date represented in sender's timezone in YYYYMMDD format. # FIX Components Source: https://docs.polymarket.us/institutional/fix-api/fix-component-definitions ## Standard Header & Trailer Each FIX message sent to and received from the Polymarket US must start and end with a message header and trailer components. ## Standard Header Component
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| 8 | BeginString | Y | String | FIXT.1.1 |
| 9 | BodyLength | Y | Length | Standard FIX message body length |
| 35 | MsgType | Y | String | The message type. See relevant section. |
| 49 | SenderCompID | Y | String | Sender identity as agreed with the exchange operator. |
| 56 | TargetCompID | Y | String | Intended target identity as agreed with the exchange operator. |
| 50 | SenderSubID | C | String | Sender sub-identifier representing an individual user (as previously agreed with the exchange operator). Required on all application messages related to the entry or management of orders. |
| 57 | TargetSubID | N | String | Target sub-identifier representing an individual user (as previously agreed with the exchange operator) |
| 34 | MsgSeqNum | Y | SeqNum | FIX Message sequence number |
| 43 | PossDupFlag | N | Boolean | Always required for retransmitted messages as the result of a resend request |
| 52 | SendingTime | Y | UTCTime | Sending time in UTC |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| 10 | Checksum | Y | String | Standard FIX checksum |
The ExecutionReport \[8] message is used to acknowledge various order lifecycle events including the acceptance, rejection, and expiry of orders, as well as providing details of matches (fills) against orders.
All orders entering the Platform are first either accepted or rejected using an Execution Report \[8]. The order may then receive further Execution Reports \[8] as necessary given their marketability and TimeInForce (59) constraints. For example: 1. A badly-formatted order which fails validation upon entry will receive an ExecutionReport \[8] with OrdStatus (39) = 8 (Rejected). 2. A good for day order which is not immediately executable will receive an ExecutionReport \[8] with OrdStatus (39) = 0 (New). Should it receive executions during the course of the day, then these will be notified in subsequent Execution Report \[8] messages with OrdStatus (39) = 1 (Partially Filled) and/or 2 (Fully Filled). 3. An order with TimeInForce (59) = 6 (good till time) will receive an ExecutionReport \[8] with OrdStatus (39) = 0 (New) upon entry. If it remains unexecuted, it will expire at the indicated ExpireTime (126) with an Execution Report \[8] message with OrdStatus (39) = C (Expired). 4. A Fill Or Kill order with TimeInForce (59) = 4 which can not be fully executed will first receive an ExecutionReport \[8] with OrdStatus (39) = 0 (New) and then an immediate Execution Report \[8] message with OrdStatus (39) = C (Expired). 5. An order with TimeInForce (59) = 3 (immediate or cancel) which can be partially filled upon entry will receive at least three ExecutionReport \[8] messages; the first will indicate OrdStatus (39) = 0 (New), the next messages will detail the fill(s), and the final Execution Report \[8] message will expire the remainder with OrdStatus (39) = C (Expired). ## Table 16: ExecutionReport (8) message
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 8 | ||
| 1 | Account | N | String | Account reference if indicated on the original order |
| 6 | AvgPx | Y | Price | Volume-weighted average price of all trades against this order. May be zero for unexecuted orders. |
| 11 | ClOrdID | Y | String | The participant-assigned ClOrdID value as sent on the last order action message form the Participant (new order, amendment or cancel). |
| 12 | Commission | N | Amt | Commission amount charged on this fill. Present on trades only. |
| 13 | CommType | N | char | Commission calculation method. 3=Absolute (total dollar amount) |
| 14 | CumQty | Y | Qty | Cumulative quantity so far for this order. May be zero for unexecuted orders. |
| 17 | ExecID | Y | String | Unique identifier for the Execution Report as assigned by Polymarket US. Typically a 13-character alphanumeric string. |
| 22 | SecurityIDSource | Y | String | Identifies source of SecurityID (48) value. 8=Exchange symbol |
| 31 | LastPx | Y | Price | Price of this last fill. Will be zero for messages not relating to a trade. |
| 32 | LastQty | Y | Qty | Quantity traded on this last fill. Will be zero for messages not relating to a trade. |
| 37 | OrderID | Y | String | Unique identifier for Order as assigned by Polymarket US. Typically a 13-character alphanumeric string. |
| 38 | OrderQty | Y | Qty | Total order quantity (amended as necessary) |
| 39 | OrdStatus | Y | char | The latest status of the order after any changes have been applied. 0=New, 1=Partially filled, 2=Fully filled, 4=Canceled, 8=Rejected, C=Expired |
| 40 | OrdType | Y | char | The type of order. 2=Limit, 3=Stop, 4=Stop Limit, K=Market with left over as limit |
| 41 | OrigClOrdID | N | String | Sent in the case of order amendment or cancellation. References the prior ClOrdID (11) value that the action amended/canceled. |
| 44 | Price | Y | Price | Order limit price (amended as necessary) |
| 48 | SecurityID | Y | String | Security identifier; will always match Symbol (55). |
| 54 | Side | Y | char | 1=Buy, 2=Sell |
| 55 | Symbol | Y | String | Instrument symbol |
| 460 | Product | Y | Int | Indicates the type of product the security is associated with. 1=AGENCY, 2=COMMODITY, 3=CORPORATE, 4=CURRENCY, 5=EQUITY, 6=GOVERNMENT, 7=INDEX, 8=LOAN, 9=MONEYMARKET, 10=MORTGAGE, 11=MUNICIPAL, 12=OTHER, 13=FINANCING, 14=ENERGY |
| 59 | TimeInForce | Y | char | Echoed from New Order Single. 0=Good for day, 1=Good till cancel, 3=Immediate or cancel, 4=Fill or kill, 6=Good till date |
| 60 | TransactTime | Y | UTCTime | Timestamp when the business transaction represented by the message occurred. |
| 99 | StopPx | Y | Price | Order stop price (amended as necessary). Will be zero for non stop orders. |
| 103 | OrdRejReason | N | int | Rejection reason (where OrdStatus = Rejected). 0=Broker/Exchange Option, 1=Unknown symbol, 2=Exchange closed (maintenance), 3=Order exceeds limit (price validation), 5=Unknown order, 6=Duplicate order (ClOrdID), 11=Unsupported order characteristic, 12=Surveillance option, 13=Incorrect quantity (lot size), 15=Unknown account (tag 1), 16=Price exceeds current price band, 18=Invalid price increment (tick size), 99=Other |
| 119 | SettlCurrAmt | N | Amt | Present on trades only. Total amount of this last fill. Equal to LastPx (31) x LastQty (32) |
| 126 | ExpireTime | N | UTCTime | Order expiry date (amended as necessary). |
| 150 | ExecType | Y | char | The reason that the Polymarket US sent this Execution Report. 0=New, 4=Canceled, 5=Replaced, 8=Rejected, C=Expired, F=Trade |
| 151 | LeavesQty | Y | Qty | Remaining, unexecuted quantity left on the order. May be zero for fully filled orders. |
| 381 | GrossTradeAmt | N | Amt | Present on orders which have been filled. Total amount traded across all fills for this order. Equal to AvgPx (6) x CumQty (38). |
| 581 | AccountType | N | Int | 1=CUSTOMER, 2=NON\_CUSTOMER, 3=HOUSE\_TRADER, 4=FLOOR\_TRADER, 6=NON\_CUSTOMER\_CROSS\_MARGINED, 7=HOUSE\_TRADER\_CROSS\_MARGINED, 8=JOINT\_BACK\_OFFICE, 9=EQUITIES\_SPECIALIST, 10=OPTIONS\_MARKET\_MAKER, 11=OPTIONS\_FIRM\_ACCOUNT, 12=AGGREGATED\_CUSTOMER\_AND\_NON\_CUSTOMER, 13=AGGREGATED\_MULTIPLE\_CUSTOMERS, 14=LIQUIDITY\_PROVIDER, 15=OPERATING, 16=CLEARING\_FUND, 17=FUTURES\_MARKET\_MAKER |
| 582 | CustOrderCapacity | N | Int | 1=OWN\_ACCOUNT, 2=PROPRIETARY\_ACCOUNT, 3=FINANCIAL\_ADVISOR, 4=ALL\_OTHER, 5=RETAIL\_CUSTOMER |
| 453 | NoPartyIDs | N | Int | Number of PartyID (448), PartyIDSource (447), and PartyRole (452) entries |
| → 448 | PartyID | N | String | Party identifier/code |
| → 447 | PartyIDSource | N | char | D=Proprietary |
| → 452 | PartyRole | N | Int | 1=EXECUTING\_FIRM, 3=CLIENT\_ID, 24=CUSTOMER\_ACCOUNT |
| 828 | TrdType | N | int | Present on trades only. 0=Regular trade |
| 880 | TrdMatchID | C | String | Always populated for trades. Note that buyer and seller will receive the same value. Will match the TradeID (1003) value on market data updates. Typically a 13-character alphanumeric string. |
| 1028 | ManualOrderIndicator | N | Boolean | Indicates if the order was initially received manually (as opposed to electronically) |
| 1057 | AggressorIndicator | C | Boolean | Always populated for trades. Identifies whether this order was the aggressor in the trade. |
| 378 | ExecRestatementReason | N | int | Indicates that the resting order has been canceled as a result of self-match prevention. 99=Self-match prevention |
| 110 | MinQty | N | Qty | Minimum required execution quantity for the order (if specified) |
| 6127 | ConditionTriggerMethod | N | int | The reference price used for triggering the stop order. 2=Last price, 5=Settlement price |
| 7928 | SelfMatchPreventionID | N | String | Unique identifier for the self-match prevention instruction. |
| 8000 | SelfMatchPreventionInstruction | N | String | Self-match instruction. O=Cancel oldest (resting) order, N=Cancel newest (aggressive) order |
| \< Standard Trailer > | Y |
**Example 6: Acknowledgement of new limit order to buy 1,000 shares at 50.00** ``` 8=FIXT.1.1 | 9=269 | 35=8 | 34=14 | 49=TARGET | 52=20240517-19:00:28 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1182560819 | 14=0 | 17=1HPT7DPFMC5KW | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM00 | 38=1000 | 39=0 | 40=2 | 44=50.00 | 48=GOOG | 54=1 | 55=GOOG | 59=0 | 60=20240517-19:00:28.678960817 | 99=0.00 | 150=0 | 151=1000 | 581=3 | 582=1 | 10=088 | ``` **Example 7: Execution of 500 shares at a price of 50.00** ``` 8=FIXT.1.1 | 9=338 | 35=8 | 34=33 | 49=TARGET | 52=20240517-19:06:47.985808615 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=50.00 | 11=1182560826 | 14=500 | 17=1HPT7DPFMC5M5 | 22=8 | 31=50.00 | 32=500 | 37=1HQ4A5T0EDM07 | 38=500 | 39=2 | 40=2 | 44=50.00 | 48=GOOG | 54=2 | 55=GOOG | 59=0 | 60=20240517-19:06:47.977567695 | 99=0.00 | 119=25000.00 | 150=F | 151=0 | 381=25000.00 | 581=3 | 582=1 | 828=0 | 880=1HPT7DPFMC5M4 | 1057=Y | 10=116 | ``` **Example 8: Expiry of FOK order (without execution)** ``` 8=FIXT.1.1 | 9=275 | 35=8 | 34=43 | 49=TARGET | 52=20240517-19:09:23.494862156 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1182560830 | 14=0 | 17=1HPT7DPFMC5MB | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM0A | 38=500 | 39=C | 40=2 | 44=50.01 | 48=GOOG | 54=2 | 55=GOOG | 59=4 | 60=20240517-19:09:23.491276593 | 99=0.00 | 150=C | 151=0 | 581=3 | 582=1 | 10=201 | ``` # FIX FAQs Source: https://docs.polymarket.us/institutional/fix-api/fix-faqs ## Getting FIX Access **What do I need to provide to get FIX access?** If you want FIX access, indicate it and include your AWS account ID on your application. Polymarket will provide: * SenderCompID and TargetCompID * User identifiers (SenderSubID) * Account identifiers (Account) * Connection ports and DNS endpoints **What is the CompID format?** CompIDs follow the format: * SenderCompID: `PMX_{FIRMNAME}` * TargetCompID: `{FIRMNAME}_PMX` These are PMX-assigned and case-sensitive. Clients must not generate or modify CompIDs. *** ## FIX Session Configuration **What is the FIX protocol version used?** FIXT.1.1 with DefaultApplVerID=9 (FIX50SP2) **What are the session connection details?** Connection details are provided during onboarding and vary by client. Typical parameters include: * BeginString: FIXT.1.1 * SenderCompID: \[Your assigned CompID] * TargetCompID: \[Polymarket assigned CompID] * Host: \[Provided during onboarding] * Port: \[Varies by service - Order Entry, Drop Copy, or Market Data] * Heartbeat Interval: 30 seconds (configurable) * Encryption: None (98=0) **What ports are used for different FIX services?** There are three services: Order Entry, Drop Copy, and Market Data. Ports are provided during onboarding and are fixed for all clients. **What is the connection model?** FIX sessions are client-initiated. PMX acts as the acceptor. Transport is FIXT.1.1 with application messages using FIX 5.0 SP2. Example QuickFIX-style configuration: ``` [DEFAULT] ConnectionType=initiator BeginString=FIXT.1.1 DefaultApplVerID=9 SocketConnectHost=
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = X | ||
| 262 | MDReqID | Y | String | The ID of the request as indicated on the request |
| 268 | NoMDEntries | Y | NumInGroup | |
| → 279 | MDUpdateAction | Y | char | The type of action conveyed by this block (0=New, 1=Change, 2=Delete) |
| → 269 | MDEntryType | C | char | Type of entry. Set where MDUpdateAction (279) = (0) New or 1 (Change). 0=Bid, 1=Offer, 2=Trade, 4=Opening Price, 5=Closing Price, 6=Settlement Price, 7=Trading Session High Price, 8=Trading Session Low Price, B=Trade Volume, g=Trading Reference Price |
| → 278 | MDEntryID | N | String | Unique reference for this entry. Typically a 13-character alphanumeric string. |
| → 55 | Symbol | Y | String | Instrument symbol |
| → 22 | SecurityIDSource | Y | int | 8 = Exchange symbol |
| → 48 | SecurityID | Y | String | Will always equal Symbol (55) |
| → 167 | SecurityType | N | String | EVENT=Event contract. Currently, Polymarket only offers EVENT instruments. |
| → 1151 | SecurityGroup | N | String | Security sub-type. For example "Equities" |
| → 270 | MDEntryPx | N | Price | Order level price where MDEntryType (269) = 0 (Bid) or 1 (Offer). Traded price where MDEntryType (269) = 2 (Trade). Total value traded where MDEntryType (269) = B (Trade Volume) |
| → 271 | MDEntrySize | N | Qty | Remaining order size where MDEntryType (269) = 0 (Bid) or 1 (Offer). Will be zero where MDUpdateAction (279) = 2 (Delete). Trade size where MDEntryType (269) = 2 (Trade). Total quantity traded where MDEntryType (269) = B (Trade Volume) |
| → 272 | MDEntryDate | N | UTCDateOnly | The date on which the price level or trade occurred |
| → 273 | MDEntryTime | N | UTCTimeOnly | The time at which the price level updated or trade occurred (in UTC) |
| → 59 | TimeInForce | N | char | Time in force for this order (0=Good for day, 1=Good till cancel, 6=Good till date) |
| → 126 | ExpireTime | N | UTCTimestamp | Populated where TimeInForce (59) = 6 (Good Till Date) |
| → 37 | OrderID | N | String | Only sent for price level updates. Will match OrderID (37) in the ExecutionReport \[8], allowing Participants to identify their own orders within market data. |
| → 40 | OrdType | N | char | 2 = Limit order, K = Market-to-limit order |
| → 828 | TrdType | N | int | Only sent for trades. 0 = Regular trade |
| → 1003 | TradeID | N | String | Only sent for trade updates. Will match the ExecID (17) in the ExecutionReport fill, allowing Participants to identify their own trades within market data. |
| → 2446 | AggressorSide | N | char | Only sent for trades. Indicates which side was the aggressor in a trade (1=Buy, 2=Sell) |
| → 336 | TradingSessionID | C | String | Sent for trades and trading status changes. Possible values: CLOSED, OPEN, PREOPEN, SUSPENDED, EXPIRED, TERMINATED, HALTED, MATCH\_AND\_CLOSE\_AUCTION |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = V | ||
| 262 | MDReqID | Y | String | Unique ID for this request |
| 263 | SubscriptionRequestType | Y | char | Type of subscription requested (0=Snapshot, 1=Snapshot plus Updates, 2=Delete previous request/unsubscribe) |
| 264 | MarketDepth | Y | int | Depth requested, maximum 25 levels (0=Full book depth, 1=Top of book/best prices only, 2+=Number of levels requested) |
| 267 | NoMDEntryTypes | N | NumInGroup | |
| →269 | MDEntryType | N | char | A repeating group of MD Entry Types requested (0=Bid, 1=Offer, 2=Trade, 4=Opening Price, 5=Closing Price, 6=Settlement Price, 7=Trading Session High Price, 8=Trading Session Low Price, B=Trade Volume, g=Trading Reference Price) |
| 146 | NoRelatedSym | Y | NumInGroup | Number of symbols requested |
| →55 | Symbol | Y | String | Instrument symbol. |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = W | ||
| 22 | SecurityIDSource | Y | int | 8 = Exchange symbol |
| 48 | SecurityID | Y | String | Will always equal Symbol (55) |
| 55 | Symbol | Y | String | Instrument symbol |
| 167 | SecurityType | N | String | EVENT=Event contract. Currently, Polymarket only offers EVENT instruments. |
| 262 | MDReqID | Y | String | The ID of the request as indicated on the request. |
| 292 | Corporate Action | C | char | Provided if the instrument is currently subject to a Corporate Action (A-W codes) |
| 268 | NoMDEntries | Y | NumInGroup | The number of market data levels returned. Might be zero if the symbol is valid but there are currently no bids/offers in this symbol. |
| → 269 | MDEntryType | Y | char | Type of entry (0=Bid, 1=Offer, 2=Trade, 4=Opening Price, 5=Closing Price, 6=Settlement Price, 7=Trading Session High Price, 8=Trading Session Low Price, B=Trading Session Volume, g=Trading Reference Price) |
| → 270 | MDEntryPx | Y | Price | Price level |
| → 271 | MDEntrySize | C | Qty | Quantity of the individual order or trade, or the aggregate quantity where MDEntryType (269) = B (Trading Session Volume). Not sent for session open/high/low. |
| → 272 | MDEntryDate | Y | UTCDateOnly | Time priority (date) of the order. |
| → 273 | MDEntryTime | Y | UTCTimeOnly | Time priority (time) of the order. |
| → 336 | TradingSessionID | C | String | Sent for entries other than MDEntryType (269) = 0 (Bid) or 1 (Offer): CLOSED, OPEN, PREOPEN, SUSPENDED, EXPIRED, TERMINATED, HALTED, MATCH\_AND\_CLOSE\_AUCTION |
| → 1151 | SecurityGroup | C | String | The name of the group of related securities to which this instrument belongs. |
| → 1070 | MDQuoteType | C | int | Identifies market data quote type. Only sent for MDEntryType (269) = 4 (Opening Price). 0 = Indicative |
| → 59 | TimeInForce | C | char | Sent for MDEntryType (269) = 0 (Bid) or 1 (Offer). The time in force for this order (0=Good for day, 1=Good till cancel, 6=Good till date) |
| → 37 | OrderID | C | String | Sent for MDEntryType (269) = 0 (Bid) or 1 (Offer). Matches the order ID in the ExecutionReport \[8] acknowledgement, allowing Participants to identify their own orders within market data. Typically a 13-character alphanumeric string. |
| → 278 | MDEntryID | C | String | Sent for MDEntryType (269) = 0 (Bid) or 1 (Offer). Unique reference for the entry. Typically 13-character alphanumeric string. |
| → 40 | OrdType | C | char | Sent for MDEntryType (269) = 0 (Bid) or 1 (Offer). |
| → 126 | ExpireTime | N | UTCTimestamp | Sent for MDEntryType (269) = 0 (Bid) or 1 (Offer) where the order has ExpiryTime (126) set. |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = D | ||
| 11 | ClOrdID | Y | String | Unique, participant-created identifier for this Order. Uniqueness must be guaranteed across a session (i.e. between logon and logout), which may span multiple days |
| 1 | Account | N | String | Account reference as previously advised to the exchange operator |
| 18 | ExecInst | N | MultipleChar | Instructions for order handling. Note that Price Validity Checks can only be ignored (c) for market-to-limit orders to sell. G=All or None, c=Ignore Price Validity Checks, 6=Participate Don't Initiate |
| 110 | MinQty | N | Qty | Minimum order quantity that must be executed upon entry (or else the whole order is immediately canceled). |
| 55 | Symbol | Y | String | Instrument symbol |
| 460 | Product | N | Int | Indicates the type of product the security is associated with. All current products on Polymarket are Product=12 (OTHER). |
| 54 | Side | Y | char | 1=Buy, 2=Sell |
| 60 | TransactTime | N | UTCTime | Timestamp of order entry in UTC. |
| 38 | OrderQty | Y | Qty | Order quantity. Can be a decimal. |
| 40 | OrdType | Y | Char | Order type (2=Limit, 3=Stop, 4=Stop limit, K=Market with left-over as limit) |
| 44 | Price | N | Price | Price per share/unit. Required where OrdType (40) = 2 (Limit) or 4 (Stop Limit). |
| 99 | StopPx | N | Price | Stop price at which to trigger the stop order. Required for OrdType (40) = 3 (Stop) or 4 (Stop Limit). Must be greater than or equal to Price (44) for buy order, or less than or equal to Price (44) for sell orders. |
| 581 | AccountType | N | Int | Account type codes (1-17) |
| 582 | CustOrderCapacity | N | Int | Customer order capacity codes (1-5) |
| 453 | NoPartyIDs | N | NumingGroup | Number of PartyID (448), PartyIDSource (447), and PartyRole (452) entries |
| → 448 | PartyID | N | String | Party identifier/code |
| → 447 | PartyIDSource | N | char | D=Proprietary |
| → 452 | PartyRole | N | Int | 1=EXECUTING\_FIRM, 3=CLIENT\_ID, 24=CUSTOMER\_ACCOUNT |
| 59 | TimeInForce | N | char | 0=Good for day \[Default], 1=Good till cancel, 3=Immediate or cancel, 4=Fill or kill, 6=Good till date |
| 126 | ExpireTime | N | UTCTime | Order expiry date and time for orders where TimeInForce = Good Till Date |
| 1028 | ManualOrderIndicator | N | Boolean | Indicates if the order was initially received manually (as opposed to electronically) |
| 6127 | ConditionTriggerMethod | N | int | The reference price used to trigger the stop order. Applicable to Stop orders only. 2=Last price \[Default], 5=Settlement price. Settlement price may be the preferred trigger method for markets where settlement price is updated frequently from a price oracle. |
| 7928 | SelfMatchPreventionID | N | String | Unique identifier to be returned in the case of a self-match prevention cancellation. The same ID must be present on all orders where self-match prevention is desired. |
| 8000 | SelfMatchPreventionInstruction | C | String | Self-match instruction. O=Cancel oldest (resting) order, N=Cancel newest (aggressive) order |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = F | ||
| 11 | ClOrdID | Y | String | Fresh, participant-generated, unique reference for this OrderCancelRequest. Must be different from the original ClOrdID (11) for the order. |
| 41 | OrigClOrdID | Y | String | The last (participant-generated) ClOrdID (11) reference for the order. This might be from the original NewOrderSingle or prior amends. |
| 55 | Symbol | Y | String | Instrument symbol as indicated on the order. |
| \< Standard Trailer > | Y |
If the request to cancel the order passed validation, then the Polymarket US will acknowledge the order cancellation with an ExecutionReport \[8] message indicating OrdStatus (39) = 4 (canceled), and LeavesQty (151) = 0. ## Figure 12: Successful cancelation of existing order  **Example 16: Example of order cancel message** ``` 8=FIXT.1.1 | 9=107 | 35=F | 49=SENDER | 56=TARGET | 34=96 | 52=20240517-19:29:50 | 50=SENDERSUB | 41=1182560834 | 11=1182560840 | 55=GOOG | 54=1 | 10=244 | ``` Rejected attempts to cancel orders for any reason (for example order is no longer alive) are rejected using the OrderCancelReject \[9] message, which identifies the reason for the rejection. ## Table 19: OrderCancelReject (9) message
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 9 | ||
| 11 | ClOrdID | Y | String | Echoed from the OrderCancelRequest |
| 37 | OrderID | Y | String | Will be 'NONE' for unknown orders |
| 39 | OrdStatus | Y | char | Status of the cancellation request. 8=Rejected |
| 41 | OrigClOrdID | Y | String | Echoed from the OrderCancelRequest |
| 58 | Text | Y | String | Free text string providing additional rejection reason |
| 102 | CxlRejReason | Y | int | Reason for the rejection. 0=Too late to cancel, 1=Unknown order, 6=Duplicate ClOrdID, 18=Invalid price increment (tick size), 99=Other |
| 434 | CxlRejResponseTo | Y | char | 1=Order cancel request, 2=Order amend request |
| \< Standard Trailer > | Y |
## Figure 13: Unsuccessful attempt to cancel existing order 
**Example 17: Rejection of an unsuccessful cancel attempt** ``` 8=FIXT.1.1 | 9=145 | 35=9 | 34=91 | 49=TARGET | 52=20240521-09:26:30.378549737 | 56=SENDER | 57=SENDERSUB | 11=1886428723 | 37=NONE | 39=8 | 41=1886428676 | 58=Unknown order | 102=1 | 434=1 | 10=198 | ``` # Order Entry Overview Source: https://docs.polymarket.us/institutional/fix-api/fix-order-entry-overview ## Overview The Exchange operates as a continuous central limit order book to match orders within the system according to price-time priority: * Higher-priced orders to buy have priority over lower-priced bids, * Lower-priced offers to sell buy have priority over higher-priced sells, * Within a price level, older orders have priority over newer orders, * Should an existing order increase its quantity (at the same price), it is assigned a new timestamp and therefore loses time priority, but quantity decreases retain time priority. ## Tick Sizes / Minimum Quantity Increments Each instrument on the Polymarket US has a minimum price increment ("tick size") and minimum quantity increment ("lot size"). These instrument-level settings are indicated in the SecurityList \[y] message in the MinPriceIncrement (969) and MinTradeVol (562) fields respectively. Order with a price and/or quantity which do not comply with these increments will be rejected using BusinessMessageReject \[j] with reason 13 = Incorrect quantity or 18 = Invalid price increment (tick size). ## Order Types, Time In Force & Execution Instructions The intended behavior of orders entering the Polymarket US is controlled using a combination of OrderType (40), TimeInForce (59) and ExecInst (18) fields. These are explained in turn below. ### Table 12: OrdType (40) definitions | Order Type | Value | Definition | | --------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | LIMIT | 2 | A priced order that can only trade at a price equal to or better than the price specified. | | MARKET TO LIMIT | K | An order that fills as far as possible at the best price(s) in the market. Should the order volume exceed that available in the order book, then the remaining order quantity is converted into a Limit order with the price equal to the last fill price (subject to Time In Force instructions).\
In the case where there is no market, the order will be rejected with reason "No liquidity for market order". | | STOP | 3 | An order which initially enters the system as hidden, but which activates (converts to active) once the price indicated by StopPx (99) is triggered in the market. At this point the order is converted into a Market to Limit order with the indicated quantity. | | STOP LIMIT | 4 | An order similar to STOP, but where the converted order is a Limit order with the indicated Price (44). | Looking for a "classic" Market Order? Simply enter a Market-to-Limit order with IOC Time in Force condition. ### Table 13: TimeInForce (59) conditions | Time In Force | Value | Definition | | :------------------------ | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | DAY | 0 | The order remains open for the current trading day only. | | GOOD TILL CANCEL (GTC) | 1 | The order remains available for execution until fully executed or canceled. | | IMMEDIATE OR CANCEL (IOC) | 3 | The order is immediately executed as far as possible upon entry, with all unfilled quantity expired. Can be used in conjunction with MinQty (110) to specify a minimum quantity which must be executed immediately. | | FILL OR KILL (FOK) | 4 | If the entire order quantity can not be satisfied immediately, then the order is canceled in full. | | GOOD TILL DATE (GTD) | 6 | The trade is active until a specific date and time (expressed in UTC) as indicated in ExpireTime (126). | In addition to order-level Time In force conditions, participants can also specify a minimum order quantity using MinQty (110), which requires that an order receives at least a minimum execution quantity upon entry (possibly in multiple fills). When used in combination with Time In Force, this field offers fine-grained control over the conditions under which an order can participate. For example: * An order marked as IOC with MinQty (110) of 200 must receive an immediate, minimum trade quantity of 200. If this is not possible, then the entire order immediately expires. * In the case of orders marked with a FOK TimeInForce (59), MinQty (110) can be included but has no material effect, as the FOK requires a full fill upon entry. * A Good Till Cancel order with a MinQty (110) specified must trade at least the specified quantity upon first entry into the order book, otherwise the order expires. Note that MinQty (110) only limits order behavior as it enters the order book; it does not prevent smaller trades occurring against the order once it is resting on the order book. ### Table 14: ExecInst (18) definitions | Exec Instruction | Value | Definition | | :----------------------------------------- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ALL OR NONE | G | Require that either (a) all of the order quantity is filled immediately, or (b) none of it should trade even partially. Marking an order with this ExecInst instruction is functionally-equivalent to setting Time In Force to FOK. | | IGNORE PRICE VALIDITY CHECKS | c | Exempt this order from absolute price limits, relative price limits, order size limits, and total notional limits. Only allowed for market-to-limit orders to sell. This flag exists to support quickly liquidating a position. | | PARTICIPATE DON'T INITIATE | 6 | Require that the order is only accepted if it would NOT immediately match. This guarantees that the order will always be the passive side in any trades. An order that would result in a match would be rejected with reason "Order may participate but not initiate in the market". Should not be used in combination with MinQty (110) or conditions which require immediate executions - ExecInst (18) = G (All or None), or TimeInForce (59) = 3 or 4 (IOC or FOK). | | SINGLE EXECUTION REQUESTED FOR BLOCK TRADE | j | A flag for submitting block trades to Polymarket US. | | BEST LIMIT | R | A flag that if set indicates that the price of a limit order shall be set to the price at the top of the book on the same side as this order. | | IMMEDIATELY EXECUTABLE LIMIT | T | A flag that if set indicates that the price of a limit order shall be set to the price at the top of the book on the opposing side as this order, thus able to immediately match. |
# Order Modification Source: https://docs.polymarket.us/institutional/fix-api/fix-order-modification
Participants may request to amend any open order using the OrderCancelReplaceRequest \[G] message. In this case, the order to be amended is identified using the last-entered ClOrdID (11) value relating to the order into the OrigClOrdID (41) field. Following FIX convention, this modification message will also contain a fresh ClOrdID (11) value which can then be used by the Participant to further modify the order if required. Note that the Polymarket US does not require the entry of the (platform-generated) OrderID (37) in order to amend the order. ## Table 17: OrderCancelReplaceRequest (G) message If the order has been successfully modified, the Polymarket US will respond with an ExecutionReport \[8] message which echoes many of the key (updated) order attributes, and with ExecType (150) = 5 (replaced). Note that a modification which increases the remaining order quantity will lose its time priority at a price level. Any modifications to reduce order quantity (or other non-price modifications which do not change quantity) will not cause the order to lose their order book priority. ## Figure 10: Successful amend of existing order to adjust OrderQty \[38]
**Example 15: Request to replace an existing order** ``` 8=FIXT.1.1 | 9=127 | 35=G | 49=SENDER | 56=TARGET| 34=66 | 52=20240517-19:17:08 | 50=SENDERSUB | 41=1182560827 | 11=1182560836 | 55=GOOG | 54=2 | 40=2 | 38=500 | 44=1000 | 10=061 | ``` If the order can not be modified for any reason (for example if the requested price / order size are not acceptable, or the order has already expired), then the Polymarket US will respond with an OrderCancelReject \[9] message indicating the reason. **Where the amendment has been rejected, the existing order remains working with prior attributes.** ## Figure 11: Unsuccessful amend of existing order to adjust OrderQty \[38]  # FIX API Overview Source: https://docs.polymarket.us/institutional/fix-api/fix-overview The purpose of this document is to outline the trading functionality available via a FIX trading protocol.
### Primary State Flow | State | Description | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PENDING` | Initial state for a newly created instrument which has not yet begun trading. Clients will receive a PENDING → OPEN state change notification but will not see PENDING in the order book. | | `OPEN` | In this state, the instrument is open for continuous order entry and matching. | | `CLOSED` | In this state, orders can not be entered, modified, or canceled, and no matching occurs. Any existing Day orders will be expired. | | `EXPIRED` | An instrument moves to this state when its Expiration Date/Time is reached. In this state, any resting orders are expired and no new orders can be entered. | | `TERMINATED` | When an instrument's Termination Date is reached, the order book is removed from the matching engine, orders are canceled, and positions are closed. Historical data will still remain in Polymarket US ledgers. | ### Exception States | State | Description | | --------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `SUSPENDED` | Orders can be canceled but no matching occurs, and no order entry or modification is allowed. | | `HALTED` | This state is similar to SUSPENDED, with the exception that orders cannot be canceled. | ### Other Possible States | State | Description | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PREOPEN` | Orders can be entered and modified, but no matching occurs. When the instrument transitions to an OPEN state, the orders entered during PREOPEN will match at a single opening price that is automatically determined by an algorithm that is designed to maximize the volume traded at the open. | | `MATCH_AND_CLOSE_AUCTION` | This state is similar to PREOPEN, with the exception that matching will occur upon the transition of this state to any other state. This state is useful if you want matching to occur at the end of the state, but you don't want the instrument to be open after. | ## FIX Notation Please note the following presentation notes which apply to message definitions and FIX examples throughout this document. * FIX tag/value pairs are delimited within a TCP connection using the SOH (ascii character 1) character. Since this is a non-printable character, in this document we use the | character instead, and pad each pair with spaces to make them easier to use. * Components are blocks of FIX tags which appear frequently in the specification (e.g. header and footers which appear on every FIX message). They are defined centrally for convenience and then referenced throughout the document using \<> notation. * Repeating groups of FIX tags appear in various messages. The depth of a repeating group is indicated using the → marker in FIX message definitions. * References to individual FIX fields (or “tags”) are presented in italic font, with the tag number following the tag name. For example HeartBtInt (108). # FIX Reject Reasons Source: https://docs.polymarket.us/institutional/fix-api/fix-reject-reasons Error codes and reject messages across FIX sessions ## Application Layer Messages ### Execution Reports (35=8) and Order Cancel Reject (35=9) For Execution Reports (i.e. when a NewOrderSingle is rejected), the reason code is provided in **OrdRejReason (Tag 103)**. For Order Cancel Reject messages (i.e. when a cancel or cancel/replace is rejected), the reason code is provided in **CxlRejReason (Tag 102)**. Note that the FIX protocol specifies different enumerations for OrdRejReason vs CxlRejReason. As such, the exact same error condition may produce a different error code in an execution report versus an order cancel reject message. | Description | Example Error String (Tag 58) | OrdRejReason (Tag 103) | CxlRejReason (Tag 102) | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------- | | Notional lower than minimum | "Low total notional size limit is 1, given 0.944" | Exchange option (0) | Exchange option (2) | | Notional larger than maximum | "High total notional size limit is 500000, given 500025" | Exchange option (0) | Exchange option (2) | | Price lower than minimum | "Low price limit is 0.5, given 0.49" | Exchange option (0) | Exchange option (2) | | Price higher than maximum | "High price limit is 1.5, given 1.51" | Exchange option (0) | Exchange option (2) | | Quantity lower than minimum | "Low order size limit is 100, given 98" | Exchange option (0) | Exchange option (2) | | Quantity higher than maximum | "High order size limit is 500, given 600" | Exchange option (0) | Exchange option (2) | | Minimum trade quantity | "Minimum trade quantity is 100, given 99" | Exchange option (0) | Exchange option (2) | | Insufficient buying power | "1000 USD available, requested 1000.098" | Exchange option (0) | Exchange option (2) | | Self Match Prevention | "Self Match Prevention" | Exchange option (0) | Exchange option (2) | | Participate Don't Initiate | "Order may participate but not initiate in the market" | Exchange option (0) | Exchange option (2) | | BEST\_LIMIT Exec Instruction with no orders on same side | "No liquidity to derive limit price" | Exchange option (0) | Exchange option (2) | | IMMEDIATELY\_EXECUTABLE\_LIMIT Exec Instruction with no orders on opposite side | "No liquidity to derive limit price" | Exchange option (0) | Exchange option (2) | | Re-use of ClOrdID in Session | "ClOrdID already in use by an open order" | Exchange option (0) | Exchange option (2) | | Account Type Validation | "Requested Account Type (FLOOR\_TRADER) does not match account configuration" | Exchange option (0) | Exchange option (2) | | Customer Order Capacity validation | "Requested Customer Order Capacity (PROPRIETARY\_ACCOUNT) does not match user/account configuration" | Exchange option (0) | Exchange option (2) | | No Reference Price for Market to Limit Order | "failed risk check: rpc error: code = FailedPrecondition desc = No last trade when open, trading reference price, settlement price, or previous close is available to evaluate reference price" | Exchange option (0) | n/a | | No Qty Filled on CashOrderQty Order | "There is no liquidity to immediately fill any portion of this CashOrderQty order, and the order cannot rest as a limit order because the order qty would be 0 at the current fallback price" | Exchange option (0) | n/a | | Invalid Attributes | "Order has attributes that cannot be placed in MATCH\_AND\_CLOSE\_AUCTION" | Exchange closed (2) | Exchange option (2) | | Invalid Attributes | "Order has attributes that cannot be placed in PRE\_OPEN" | Exchange closed (2) | Exchange option (2) | | Market Closed | "Book is CLOSED" | Exchange closed (2) | Exchange option (2) | | Market Suspended by Exchange | "Book is SUSPENDED" | Exchange closed (2) | Exchange option (2) | | Market Halted by Exchange | "Book is HALTED" | Exchange closed (2) | Exchange option (2) | | Attempt to Cancel/Replace a Filled Order | "Unknown order" | n/a | Unknown order (1) |
Note that resting order(s) will expire just after the incoming order has been accepted by the Platform, and before any trades have taken place. The incoming order is therefore permitted to trade against other orders in the order book as it entered the market. **Example 13: ExecutionReport indicating resting order expiry as a result of self-match prevention** ``` 8=FIXT.1.1 | 9=341 | 35=8 | 34=69 | 49=TARGET | 52=20240521-11:22:26.078209896 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1886428747 | 14=0 | 17=1HPT7DQ1GC4JA | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM26 | 38=1 | 39=4 | 40=2 | 41=1886428747 | 44=0.02 | 48=GOOG | 54=1 | 55=GOOG | 58=Self Match Prevention | 59=0 | 60=20240521-11:22:26.075068980 | 99=0.00 | 150=4 | 151=0 | 378=99 | 581=3 | 582=1 | 7928=111 | 8000=O | 10=039 | ``` If the SelfMatchPreventionInstruction (8000) is N (newest), then it is the incoming order which is rejected to prevent the execution, as shown below. This is the default behavior where SelfMatchPreventionID (7928) is present but SelfMatchPreventionInstruction (8000) is not specified. Note that the incoming order is fully canceled in the case it would potentially match against other orders with the same SelfMatchPreventionID (7928); partial execution against other orders is not permitted. ### Figure 9: Self-match prevention causes newest order to be rejected
**Example 14: ExecutionReport immediately rejecting incoming order as a result of self-match prevention** ``` 8=FIXT.1.1 | 9=314 | 35=8 | 34=109 | 49=TARGET | 52=20240521-11:55:30.495116582 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1886428755 | 14=0 | 17=1HPT7DQ1GC4JT | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM2E | 38=10 | 39=8 | 40=2 | 44=0.02 | 48=GOOG | 54=1 | 55=GOOG | 58=Self Match Prevention | 59=0 | 60=20240521-11:55:30.487845738 | 99=0.00 | 103=0 | 150=8 | 151=0 | 581=3 | 582=1 | 7928=222 | 10=165 | ```
# FIX Session Management Source: https://docs.polymarket.us/institutional/fix-api/fix-session-management ## Establishing and Maintaining a FIX Session The Logon \[A] message initiates a connection to the Polymarket US. FIX sessions are typically initiated by customers (as opposed to the exchange platform), and can be made any time. **Important: Logon \[A] messages must NOT specify a SenderSubID \[50] in the header. Sending this tag will cause the logon attempt to be rejected.** ### Table 4: Logon (A) message
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = A | ||
| 98 | EncryptMethod | Y | int | Encrypted messages are not supported. 0=None |
| 108 | HeartBtInt | Y | int | A 30-second interval is recommended |
| 141 | ResetSeqNumFlag | Y | Boolean | Indicates both sides of a FIX session should reset sequence numbers back to 1 during a normal end of session (and not due to an unintended disconnect). Recommended |
| 1137 | DefaultApplVerID | Y | String | Specifies the FIX 5.0 service pack release being applied. 9=FIX50SP2 |
| \< Standard Trailer > | Y |
**Example 1: Logon message** ``` 8=FIXT.1.1 | 9=76 | 35=A | 49=SENDER | 56=TARGET | 34=1 | 52=20240516-14:14:53 | 98=0 | 108=30 | 1137=9 | 141=Y | 10=132 | ```
### Figure 1: Successful Logon  Under normal circumstances, both FIX engines on either side of the connection will regularly exchange Heartbeat messages. The frequency of such a message exchange is determined by the HeartBtInt (108) value indicated in the Logon \[A] message. Regular application messages qualify as a heartbeat, i.e both sides of the connection are behaving nominally if a message is received during the HeartBtInt (108). If no application messages are received during the interval, the Heartbeat \[0] message is used as described below.
### Table 5: Heartbeat (0) message
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 0 (zero) | ||
| 112 | TestReqID | N | String | Required when the heartbeat is the result of a TestRequest \[1] message |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 1 | ||
| 112 | TestReqID | Y | String | ID to be returned in the resulting Heartbeat \[0] response |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 2 | ||
| 7 | BeginSeqNo | Y | SeqNum | MsgSeqNum (34) of first message in the range to be resent (inclusive) |
| 16 | EndSeqNo | Y | SeqNum | MsgSeqNum (34) of the last message in the range to be resent (inclusive), or "0" to request resend all messages after the indicated BeginSeqNo (7) |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 4 | ||
| 123 | GapFillFlag | N | Boolean | Indicates that the Sequence Reset message is replacing administrative or application messages which will not be resent. |
| 36 | NewSeqNo | Y | SeqNum | New sequence number |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 5 | ||
| 58 | Text | N | String | Free format text string |
| \< Standard Trailer > | Y |
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = 3 | ||
| 45 | RefSeqNum | Y | SeqNum | The message sequence number being rejected |
| 371 | RefTagID | N | int | The tag (field) number being rejected |
| 373 | SessionRejectReason | N | int | Reason for the rejection. 0=Invalid tag number, 1=Required tag missing, 2=Tag not defined for this message type, 3=Undefined tag, 4=Tag specified without value, 5=Value is incorrect, 6=Incorrect data format for value, 9=CompID problem, 10=SendingTime accuracy problem, 11=Invalid MsgType, 13=Tag appears more than once, 14=Tag specified out of required order, 15=Repeating group fields out of order, 16=Incorrect NumInGroup count, 99=Other |
| 58 | Text | N | String | Optional string to further describe the error |
| \< Standard Trailer > | Y |
**Example 3: Reject \[3] example due to bad limit price** ``` 8=FIXT.1.1 | 9=127 | 35=3 | 34=39 | 49=TARGET | 52=20240517-19:08:47 | 56=SENDER | 45=42 | 58=Value is incorrect (out of range) for this tag | 371=44 | 372=D | 373=5 | 10=237 | ```
### Table 11: BusinessMessageReject (j) message
| Tag | Name | Req | Type | Description |
|---|---|---|---|---|
| \< Standard Header > | Y | 35 = j | ||
| 45 | RefSeqNum | N | SeqNum | The message sequence number being rejected |
| 58 | Text | N | String | String to further describe the error |
| 372 | RefMsgType | Y | String | The MsgType being rejected |
| 379 | BusinessRejectRefID | N | String | When a FIX gateway rejects a message with a BusinessMessageReject, it provides tag 379 (BusinessRejectRefID) on the BusinessMessageReject and populates it with the ClOrdId or MDReqID to allow FIX clients to quickly determine which message was rejected. |
| 380 | BusinessRejectReason | Y | int | The reason for the rejection. 0=Other, 1=Unknown ID, 2=Unknown Security, 3=Unsupported Message Type, 4=Application Not Available (downtime), 5=Conditionally required field missing, 6=Not authorized, 18=Invalid price increment (tick size) |
| \< Standard Trailer > | Y |
**Example 4: BusinessMessageReject \[j] example due to bad role permissions** ``` 8=FIXT.1.1 | 9=116 | 35=j | 34=5 | 49=TARGET | 52=20240516-14:19:40 | 56=SENDER | 45=6 | 58=Supervising firms cannot perform this action | 372=x | 380=6 | 10=082 | ``` # Stop Orders Source: https://docs.polymarket.us/institutional/fix-api/fix-stop-orders ## Triggering Stop Orders Stop Orders which have been accepted by the Platform are immediately acknowledged with an ExecutionReport \[8] message indicating OrdStatus (39) = 0 (New). They remain outside the central limit order book until the StopPx (99) has been observed, triggering the release of either a Limit or Market-to-Limit order into the order book. At this point, the Platform will send a second, unsolicited Execution Report \[8] with a matching OrderID (37) value, and the OrdType (40) of either 2 (Limit) or K (market-to-limit). The OrdStatus (39) of this triggered order will be 0 (New). ### Figure 6: Triggering of Stop Limit order 
**Example 9: Entry of a Stop Limit order** ``` 8=FIXT.1.1 | 9=160 | 35=D | 49=SENDER | 56=TARGET | 34=119 | 52=20240521-09:45:21 | 11=1886428727 | 21=1 | 55=GOOG | 54=1 | 60=20240521-09:45:21 | 40=4 | 44=0.03 | 38=1500 | 50=SENDERSUB | 1=ACCT | 59=0 | 99=0.03 | 10=163 | ``` **Example 10: Initial acknowledgement of Stop Limit order** ``` 8=FIXT.1.1 | 9=279 | 35=8 | 34=112 | 49=TARGET | 52=20240521-09:45:21.252049258 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1886428727 | 14=0 | 17=1HPT7DQ1GC4C4 | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM1T | 38=1500 | 39=0 | 40=4 | 44=0.03 | 48=GOOG | 54=1 | 55=GOOG | 59=0 | 60=20240521-09:45:21.246689976 | 99=0.03 | 150=0 | 151=1500 | 581=3 | 582=1 | 10=079 | ``` **Example 11: ExecutionReport indicating conversion of Stop Limit into Limit order** ``` 8=FIXT.1.1 | 9=293 | 35=8 | 34=126 | 49=TARGET | 52=20240521-09:52:30.011976583 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1886428732 | 14=0 | 17=1HPT7DQ1GC4ET | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM1T | 38=1500 | 39=0 | 40=2 | 41=1886428727 | 44=0.03 | 48=GOOG | 54=1 | 55=GOOG | 59=0 | 60=20240521-09:52:30.004561670 | 99=0.02 | 150=0 | 151=1500 | 581=3 | 582=1 | 10=253 | ``` ## Market-To-Limit Order Behavior Market-to-limit orders (OrderType (39) = K) are unpriced orders which are designed to execute against any existing orders in the order book upon arrival, with any remaining order balance automatically converted into a Limit order at the last trade or "worst fill" price. To illustrate this behavior, consider the below order book:  When a new Market-to-Limit order selling 1,800 hits the order book, then the order will immediately trade 1,000 shares at 10.03, and a further 500 shares at 10.02. Since there are no further bids, the Platform will place the remaining 300 shares into the order book at a price equal to the last fill price of 10.02.  ### Figure 7: Handling of Market-to-Limit order (see example)
Note that unlike Stop Orders, Market-to-Limit orders retain the same OrdType (40) of K (Market-to-limit) throughout their life; the initial acknowledgement contains the limit Price (44) of the resting order.
**Example 12: Initial acknowledgment of Market-to-Limit order indicating end Limit Price (44)** ``` 8=FIXT.1.1 | 9=278 | 35=8 | 34=11 | 49=TARGET | 52=20240521-10:40:28.546598320 | 56=SENDER | 57=SENDERSUB | 1=ACCT | 6=0.00 | 11=1886428739 | 14=0 | 17=1HPT7DQ1GC4GH | 22=8 | 31=0.00 | 32=0 | 37=1HQ4A5T0EDM20 | 38=1000 | 39=0 | 40=K | 44=0.02 | 48=GOOG | 54=2 | 55=GOOG | 59=0 | 60=20240521-10:40:28.542693638 | 99=0.00 | 150=0 | 151=1000 | 581=3 | 582=1 | 10=012 | ```
# REST/gRPC vs FIX Source: https://docs.polymarket.us/institutional/fix-api/fix-vs-rest Understanding the differences between REST/gRPC and FIX APIs ## Architecture ### REST/gRPC is Internet-Native * Public API accessible over HTTPS * Authentication is Private Key JWT (RSA key signatures → access token) * Secured cryptographically (private key signatures), not by network location * No VPC, PrivateLink, or IP allowlisting required * Designed for stateless, elastic, internet-style clients ### FIX is Exchange-Native * Traffic terminates on dedicated FIX gateways via AWS PrivateLink * Access is gated by AWS account allowlisting * Authentication is FIX session identity (SenderCompID / TargetCompID / SenderSubID) * Designed for long-lived, stateful connections with known counterparties REST/gRPC relies on cryptographic identity (RSA signatures and JWTs). FIX relies on network-level trust (AWS account allowlisting via PrivateLink) + session semantics. They run on different infrastructure layers and intentionally use different trust models. *** ## Concept Mapping This table shows how the same concepts are represented in REST/gRPC vs FIX: | Concept | REST/gRPC | FIX | | ------------------ | -------------------- | ----------------- | | Firm / participant | Implicit via login | SenderCompID (49) | | Exchange | REST base URL | TargetCompID (56) | | User / trader | Logged-in user | SenderSubID (50) | | Trading account | Implicit | Account (1) | | Instrument | Symbol | Symbol (55) | | Client order ID | Client-generated ID | ClOrdID (11) | | Exchange order ID | Returned in response | OrderID (37) | | Side | buy / sell | Side (54) | | Order type | JSON field | OrdType (40) | | Quantity | JSON field | OrderQty (38) | | Price | JSON field | Price (44) | | Time in force | JSON field | TimeInForce (59) | *** ## Authentication ### REST/gRPC Authentication is cryptographic and passwordless. User and account context is implicit once authenticated. Users authenticate by: 1. Generating an RSA key pair during onboarding 2. Signing a JWT with their private key 3. Exchanging the signed JWT for an access token from Auth0 4. Using the access token in API requests ### FIX User and account context is explicit per order. FIX does not use JWTs or passwords. Authentication is based on: 1. AWS account allowlisting via PrivateLink 2. FIX session identity (SenderCompID, TargetCompID) *** ## Identity Model **REST/gRPC** infers user + account from login. **FIX** requires them to be sent on every order. | Concept | REST/gRPC | FIX | | --------------- | ------------------ | ----------------- | | Firm identity | Implicit via login | SenderCompID (49) | | User / trader | Login user | SenderSubID (50) | | Trading account | Implicit | Account (1) | | Auth scope | Session token | FIX session | In FIX, the session itself (SenderCompID / TargetCompID) uniquely identifies the participant firm/clearing member, so symbols, accounts, and trader IDs do not need globally unique, fully qualified names the way REST resources do. **REST/gRPC**: Uses globally unique, fully qualified resource names (e.g., `firms/{id}/accounts/{id}`) **FIX**: Fully qualified names are not required; participant identity is scoped by the FIX session (CompIDs), and identifiers only need to be unique within that session context *** ## Connectivity ### REST/gRPC HTTPS (REST) / HTTP streaming (gRPC). No static IP requirement. No VPC or network allowlisting. Public internet access. Single endpoint per environment. ### FIX TCP FIXT.1.1. Static IP allowlisting required. Separate sessions for: * Order Management * Drop Copy * Market Data *** ## State & Reliability | Area | REST/gRPC | FIX | | ---------- | ---------------- | ----------------------- | | Transport | Request/response | Persistent session | | Sequencing | Not required | Mandatory (MsgSeqNum) | | Recovery | Client retries | ResendRequest / GapFill | | Heartbeats | Not applicable | Required | *** ## Permissions & Validation ### REST/gRPC Permissions enforced at login. Invalid actions rejected at API layer. ### FIX Permissions enforced at: 1. Session level 2. User level (SenderSubID) 3. Account level (Account) Invalid values cause order-level rejects. *** ## Onboarding ### REST/gRPC Self-service after initial onboarding, no network infrastructure required, cryptographically secured (RSA signatures), public internet access. 1. Generate RSA key pairs for each environment 2. Submit onboarding request via Google Drive to [onboarding@polymarket.us](mailto:onboarding@polymarket.us) with public keys and signed Individual or Entity Participant Agreement 3. Receive Client ID credentials from Polymarket 4. Sign JWTs with private key to obtain access tokens 5. Fund account via wire transfer (production only) ### FIX Requires AWS account and VPC setup, coordinated provisioning with exchange, uses AWS PrivateLink for private network connectivity, suited for automated trading systems and high-throughput integrations. 1. Download and complete Individual or Entity Participant Agreement 2. If you want FIX access, indicate it and include your AWS account ID on your application 3. Receive connection details from Polymarket (VPC Service Names, FIX session identifiers, user/account IDs, connection ports and DNS endpoints) 4. Create AWS VPC Endpoint and wait for Polymarket to accept connection request 5. Configure Private DNS and test FIX sessions (Logon, Orders, Market Data, Drop Copy) *** ## Operational Differences | Area | REST/gRPC | FIX | | --------------- | ----------- | ------------------------- | | Who can onboard | Any user | Exchange + client | | Network setup | None | Required | | Identity setup | Automatic | Manual | | Failure modes | HTTP errors | Session / sequence errors | # Funding Overview Source: https://docs.polymarket.us/institutional/funding/overview Cash balance changes (deposits, withdrawals, fills, fees, adjustments) The balance ledger records every change to an account's cash balance, with both `before_balance` / `after_balance` and a typed `entry_type` describing why the balance moved. Use it for cash reconciliation, audit trails, and regulatory reporting. For real-time push of these same entries, see the [Balance Ledger Stream](/streaming-endpoints/balance-ledger-stream). ## Endpoints | Method | Endpoint | Required Scope | Description | | ------ | ------------------------------------- | ---------------- | ----------------------------------------------- | | `GET` | `/v1/funding/balance-ledger` | `read:positions` | Paginated query of balance ledger entries | | `GET` | `/v1/funding/balance-ledger/download` | `read:positions` | Streamed CSV download of balance ledger entries |
to the participant per their wallet terms ``` **Why this beats bank rails:** the participant's fiat already sits with your funding entity. Allocating it to trading is one platform ledger transfer — seconds — instead of a bank transfer to the clearinghouse — hours to days. The time between *"I want to trade with these funds"* and *"I can submit a trade with these funds"* is one confirmed `DEPOSIT` transfer. ## Deposits Create a `DEPOSIT` transfer when the participant allocates wallet funds to trading: * **Event-driven, typically 1:1.** One transfer per wallet allocation event is the intended pattern. If wallet deposits and withdrawals are the only ways a participant's allocation changes, mirroring them keeps on-platform buying power in lock-step with the wallet. * **Latency-sensitive.** A participant is typically waiting to trade behind a deposit. Give deposits priority over batch work (fee collections, scheduled withdrawals) in your transfer queue — see [rate limits and smoothing](/partners/funding/transfers#rate-limits-and-smoothing). * **Funded from the pool.** A deposit is rejected if the partner funding account can't cover it — size and top up the pool for peak allocation demand, per [sizing the funding account](/partners/funding/overview#sizing-the-funding-account). * **Consider batching micro-events.** If your product produces many small allocations per participant (e.g. round-ups), aggregate them into fewer, larger deposits rather than one transfer each — transfers scale with wallet events, and the [budget](/partners/funding/overview#the-transfer-budget) is shared across your integration. ## Withdrawals Create a `WITHDRAWAL` transfer when the participant de-allocates funds from trading. The amount must be covered by the participant's **free cash**: ``` free cash = account cash − collateral locked by open orders and positions ``` * **Check before you initiate.** Confirm free cash via your ledger projection (authoritative read: `PositionAPI/GetAccountBalance` — see [Reconciliation](/partners/reconciliation#cash-balances-polymarket-v1-positionapi)). A withdrawal exceeding free cash is [rejected](/partners/funding/transfers#insufficient-funds). * **Leave the fee earmark behind.** Accrued, uncollected vendor fees are cash in the same account. Cap withdrawable amount at `free cash − accrued uncollected vendor fees`, or your fee collection becomes uncollectable — see [Vendor Fees](/partners/funding/vendor-fees#accrued-fees-are-credit-exposure). * **Open orders lock collateral.** If the participant wants to withdraw more than their free cash, they (or you, on their behalf) must first cancel open orders or close positions to release collateral. * **Trading proceeds are withdrawable.** Settlement credits, realized profit, and released collateral accumulate in the account as free cash — a participant "cashing out winnings" is just a withdrawal like any other. ## Keeping the mirror honest Both legs of every confirmed transfer post to the [balance ledger](/streaming-endpoints/balance-ledger-stream) as typed entries (`DEPOSIT` / `WITHDRAWAL`), alongside trading events. Reconcile per account: ``` account cash = Σ deposits − Σ withdrawals − Σ vendor fee collections − collateral locked ± realized P&L + settlement credits − exchange fees ``` Your funding entity's wallet ledger and the platform's account ledger should agree on the allocation at all times; the [Reconciliation](/partners/reconciliation) page covers the stream-first pattern for maintaining that projection across your participant base. ## Related pages
post to the participant account PM-->>FE: Vendor Fees report (daily) FE->>PM: Vendor fee transfer — participant account → funding account (≤ 1/day) RP->>FE: Withdraw (wallet) FE->>PM: Withdrawal transfer — participant account → funding account ``` | Flow | Direction | When | Moved by | | ------------------------- | ------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Deposit** | Funding account → participant account | Participant allocates funds to trade | Your funding entity, via [transfer](/partners/funding/transfers) | | **Trading** | Within the participant account | Continuously | Polymarket US — collateral locks, exchange fees, fills, settlement credits, realized P\&L all post to the account | | **Vendor fee accrual** | *No movement* | Each order placement | Recorded only — Polymarket US stores your declared fee against the order | | **Vendor fee collection** | Participant account → funding account | Periodic, at most once per day | Your funding entity, via [transfer](/partners/funding/transfers), reconciled against the [Vendor Fees report](/partners/funding/vendor-fees) | | **Withdrawal** | Participant account → funding account | Participant withdraws from their wallet | Your funding entity, via [transfer](/partners/funding/transfers) | **Trading proceeds stay put.** Settlement credits, realized profit, and released collateral remain in the participant's account — they *are* the participant's buying power for the next trade. Nothing needs to be swept after fills or settlements; cash only leaves an account for a withdrawal or a vendor fee collection. ## Buying power Two numbers matter for every order, and they are owned by different systems: | Check | Owner | Formula | | ------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Platform check** | Polymarket US | An order is rejected unless the participant account's available cash covers **worst-case collateral + exchange fee** | | **Your gate** | You & your funding entity | Spendable balance = account cash − **accrued, uncollected vendor fees** | Polymarket US knows nothing about your fee basis and does not reserve for vendor fees — it only records the amounts you declare. Between collections, accrued fees are cash sitting in the participant's account that the participant could otherwise trade with. **Your platform must gate order submission off-platform** so a participant cannot spend the cash that is earmarked for your accrued fees. See [Vendor Fees](/partners/funding/vendor-fees) for the accrual model and the credit-risk consequences of not gating. If deposits and withdrawals are the only balance events in your wallet product, mirroring them 1:1 with deposit and withdrawal transfers keeps on-platform buying power exactly in step with the participant's wallet allocation — see [Deposits & Withdrawals](/partners/funding/deposits-withdrawals). ## The transfer budget Platform transfers are a **limited, shared resource — budget for 5 transfers per second** across your integration. The model is designed to fit comfortably inside that: * **Deposits and withdrawals are event-driven** — typically one transfer per wallet deposit/withdrawal event per participant. No per-order movement. * **Vendor fees are batched** — one transfer per participant account per collection period, **at most once per day** (weekly or monthly are fine too). * **Trading itself uses zero transfers** — collateral, exchange fees, fills, and settlement all post inside the participant account. Do not design flows that scale transfers with order volume, and smooth out bursts — for example, spread an end-of-day vendor fee collection run across minutes rather than firing one call per account simultaneously. See [Transfers](/partners/funding/transfers#rate-limits-and-smoothing) for concrete rate-limit handling patterns. ## Sizing the funding account The partner funding account is the **unallocated pool** — participant trading balances live in their own accounts. Size the pool to cover expected **deposit demand** between top-ups from your funding entity's treasury: peak concurrent "allocate funds" flow, not open interest. A deposit transfer fails if the pool can't cover it. Use `GetFundingAccountBalance` to read the authoritative, current pool balance on demand. The service resolves the partner funding account from your authenticated firm identity, so you do not supply an account ID. Poll at modest rates to monitor available capacity, and read the balance before or after treasury top-ups and large transfer batches when you need a current value. A real-time mirror remains useful for alerting and reconciliation. Seed and periodically verify it with `GetFundingAccountBalance`, and investigate any drift from this identity: ``` pool balance = treasury top-ups (external) − Σ deposit transfers (out to participant accounts) + Σ withdrawal transfers (back in) + Σ vendor fee collections (back in) ``` The RPC is the source of truth when the mirror and the returned balance differ. See [GetFundingAccountBalance](/partners/funding/transfers#getfundingaccountbalance) for the request, response, and retry behavior. ### Deposits and withdrawals at the wallet A participant's fiat deposits and withdrawals are movements between the participant and your funding entity — part of their wallet relationship, settled through your payment provider, entirely outside Polymarket US. What reaches Polymarket US is the allocation: when a participant designates wallet funds for trading, your funding entity mirrors that allocation onto the platform with a deposit transfer, and mirrors de-allocations back with withdrawal transfers. ## Directional guarantees The platform enforces the money-flow rules at the API level. Your partner funding account is **always one side** of every transfer, and a participant account under your Firm is always the other: | Money movement | Reason | Allowed? | | ------------------------------------------------------------------------------ | ------------- | ---------- | | Funding account → participant account | `DEPOSIT` | ✅ | | Participant account → funding account | `WITHDRAWAL` | ✅ | | Participant account → funding account | `VENDOR_FEES` | ✅ | | Participant account → your firm, another participant, or any other destination | — | ❌ Rejected | This is what lets your firm operate without ever holding participant funds: you can only route money between the participant and the funding entity that custodies their wallet. ## API surface The partner funding APIs are **gRPC-only**. Connection and authentication follow the standard conventions — TLS and a Bearer access token in the `authorization` metadata header; see the [gRPC API Overview](/grpc-api/overview) and [Authentication](/streaming-endpoints/authentication). | Concern | Service | Pages | | -------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Order placement with vendor fee declaration | `polymarket.us.orderfunding.v1.OrderFundingService/CreateVendorOrder` | [Create Order](/partners/orders/create-order) · [Data Model](/partners/orders/data-model) | | Deposits, withdrawals, vendor fee collection | `polymarket.us.cashmovement.v1.CashMovementService` | [Transfers](/partners/funding/transfers) | | Fee accrual reporting | Daily Vendor Fees report | [Vendor Fees](/partners/funding/vendor-fees) |
fee on each order placement"] --> B["Accrue
recorded as fee ↔ order ID"] B --> C["Report
daily Vendor Fees report"] C --> D["Collect
one VENDOR_FEES transfer
per account, ≤ 1/day"] ``` ## Declaring the fee Every order you place through [`CreateVendorOrder`](/partners/orders/create-order) carries a `vendor_fee` — a **fixed USD amount you compute** per your agreement with the participant. Polymarket US validates that it is well-formed, non-negative, and allowed for your firm, then records the mapping *"this firm declared vendor fee \$X for order Y"*.
created automatically P->>RP: Ready to fund and trade else Rejected P->>RP: Onboarding declined end ``` 1. **You collect** each trader's required details and present the appropriate participant agreement. 2. **You submit** the information through the [KYC](/partners/onboarding/kyc/overview) endpoints. 3. **Polymarket US verifies** the identity asynchronously and makes the decision — you do not perform the verification yourself. 4. **You're notified by [webhook](/partners/onboarding/kyc/webhooks)** when the outcome is terminal. On approval, the `kyc.approved` event carries the participant's `provisioned_account` and `provisioned_participant` once the trading account is provisioned (provisioning is asynchronous, so this can arrive shortly after the initial response). 5. **On approval**, the trader's [Participant](/partners/onboarding/users) identity and [Account](/partners/onboarding/accounts) are already provisioned. Once their account is funded with a [deposit transfer](/partners/funding/deposits-withdrawals) *(Beta)*, they can trade.
auto-provisioned] C --> D[Funded] D --> E[Trading] B -->|No| F[KYC Rejected] ``` When a Retail Participant completes KYC and is approved: 1. Polymarket US automatically provisions their **trading identity** (Participant). 2. A **trading account** is created for them. 3. They can then be funded and trade. There is no separate "create user" or "create account" call. See the [KYC Verification Flow](/partners/onboarding/kyc/verification-flow) for the steps, and [Partner Funding](/partners/funding/overview) *(Beta)* for how participant trading is funded.