Order Data Model

BETA — SUBJECT TO CHANGE. This API is in beta and may change without notice.

CreateVendorOrder embeds the public polymarket.v1.InsertOrderRequest. The supported order shape for partner entry is intentionally narrow: limit orders with fill-or-kill (FOK) time in force and either a share quantity or a cash quantity such as “spend $20.” The service validates populated fields against a fail-closed allowlist. Any field marked Rejected if set below causes INVALID_ARGUMENT, with the offending field named in the error. This prevents newly added public-order features from becoming available to partner callers unintentionally.

Supported fields

`InsertOrderRequest` field	Type	Partner support	Requirements
`type`	`OrderType`	Required	Must be `ORDER_TYPE_LIMIT`.
`side`	`Side`	Required	`SIDE_BUY` or `SIDE_SELL`, expressed in YES terms. Use the complementary order for NO.
`order_qty`	`int64`	Optional; exactly one quantity required	Positive contract quantity in the instrument’s fixed-point quantity scale. Set exactly one of `order_qty` and `cash_order_qty`.
`symbol`	`string`	Required	Exchange symbol for the market.
`price`	`int64`	Required	Positive YES limit price in the instrument’s fixed-point price scale, including for an order expressing a NO position.
`time_in_force`	`TimeInForce`	Required	Must be `TIME_IN_FORCE_FILL_OR_KILL`. Every other time-in-force value is rejected.
`clord_id`	`string`	Required	Your FIX tag-11 client order ID: 1–64 visible ASCII characters, unique across live orders for the participant. Echoed as `clOrdID` on Drop Copy and included in the Vendor Fees report.
`account`	`string`	Required	The participant’s DCM trading account from the KYC approval webhook. This is the sole customer identifier and the account used to match Drop Copy.
`stop_price`	`int64`	Rejected if set	Stop and stop-limit orders are unsupported.
`min_qty`	`int64`	Rejected if set	Minimum-quantity instructions are unsupported.
`self_match_prevention_id`	`string`	Rejected if set	Custom self-match prevention identifiers are unsupported.
`quote`	`string`	Rejected if set	Quote-linked orders are unsupported.
`all_or_none`	`bool`	Rejected if set	Use FOK for the supported all-or-cancel execution behavior.
`session_id`	`string`	Rejected if set	The service derives submission context. Do not copy a session from another API call.
`user`	`string`	Rejected if set	The service derives the submitting participant from the authenticated firm’s relationship to `account`.
`client_account_id`	`string`	Rejected if set	Use `account` as the account identifier.
`client_participant_id`	`string`	Rejected if set	The service derives the participant associated with `account`.
`participate_dont_initiate`	`bool`	Rejected if set	Post-only behavior is unsupported.
`cash_order_qty`	`int64`	Optional; exactly one quantity required	Positive USD principal in the instrument’s fixed-point price scale. On BUY, this is YES principal; on SELL, it is complementary NO collateral—not target proceeds. Set exactly one of `cash_order_qty` and `order_qty`.
`strict_limit`	`bool`	Rejected if set	Strict-limit behavior is unsupported.
`good_till_time`	`Timestamp`	Rejected if set	Non-default `good_till_time` is unsupported and rejected.
`best_limit`	`bool`	Rejected if set	Best-limit pricing is unsupported.
`immediately_executable_limit`	`bool`	Rejected if set	Immediately-executable-limit behavior is unsupported.
`self_match_prevention_instruction`	`SelfMatchPreventionInstruction`	Rejected if set	Custom self-match prevention instructions are unsupported.
`order_capacity`	`OrderCapacity`	Rejected if set	Custom order-capacity values are unsupported.
`ignore_price_validity_checks`	`bool`	Rejected if set	Price validity checks cannot be bypassed.
`manual_order_indicator`	`ManualOrderIndicator`	Required	`MANUAL_ORDER_INDICATOR_MANUAL` for a human-entered order or `MANUAL_ORDER_INDICATOR_AUTOMATED` for a system-generated order.

In proto3, scalar fields at their default value are not populated on the wire. “Rejected if set” means do not send a non-default value for that field. Construct the supported request directly rather than reusing a broad public-order object.

Outcomes and prices

There is one order book per market, expressed in instrument (YES) terms. price is always the YES price; there is no separate NO book or NO price field. Express a NO position with the complementary YES order:

BUY q NO @ p  ≡ SELL q YES @ (1 − p)
SELL q NO @ p ≡ BUY q YES @ (1 − p)

The quantity remains q contracts; do not convert it to a dollar amount. For example, buying 10 NO at $0.20 requires SIDE_SELL, order_qty = 1000, and price = 80 when both scales are 100. A fill changes the YES-terms position by -10 contracts. Economically, buying the 10 NO contracts costs $2.00, and the cost is reflected in the account’s buying power. Commission is additional—$0.08 in this example. Set exactly one of order_qty or cash_order_qty. The service rejects requests that set both or neither.

order_qty specifies a number of contracts and is unchanged when translating between YES and NO.
On SIDE_BUY, cash_order_qty is the principal to spend on YES, and fill quantity is principal divided by actual execution price. A $20.00 principal fills 25 contracts at the $0.80 limit or 62.5 contracts with price improvement to $0.32. The limit bounds the worst-case price; commission is additional to the principal.
On SIDE_SELL, cash_order_qty is the complementary NO collateral to spend, not a target for sale proceeds. At a YES limit price of $0.80, $20.00 is divided by the $0.20 complement and buys 100 NO contracts. “Spend $20 on NO at up to $0.20” therefore uses SIDE_SELL, cash_order_qty = 2000, and price = 80 when priceScale = 100.

On SIDE_SELL, cash_order_qty = 2000 does not mean “sell enough to receive $20.00.” It means commit $20.00 of complementary NO collateral.

Cash quantities are valid with the partner surface’s required ORDER_TYPE_LIMIT. Exchange commission is charged in addition to the principal represented by cash_order_qty.

Fixed-point values

price, order_qty, and cash_order_qty are integers on the public exchange message. Convert user-facing decimals with the scales published for the instrument — the priceScale and fractionalQtyScale fields returned by the Reference Data API:

wire price = decimal YES price × priceScale
wire contract quantity = decimal contracts × fractionalQtyScale
wire cash quantity = decimal USD principal × priceScale

For example, when both scales are 100, a $0.45 YES limit price is price = 45, 100 contracts is order_qty = 10000, and $20.00 of principal is cash_order_qty = 2000. Divide by the same scales to convert wire integers back to decimals. Always use each instrument’s published values; do not hard-code them.

Fees on execution reports

Execution reports — on the Drop Copy stream and from SearchExecutions / SearchOrders — carry the exchange fee in the same fixed-point convention as every other wire value. The commission fields are notional units, scaled by both the price scale and the quantity scale:

contracts        = order_qty / fractional_quantity_scale
price ($)        = price / price_scale
commission ($)   = commission_notional_collected / (price_scale × fractional_quantity_scale)

One dollar is price_scale × fractional_quantity_scale notional units. When both scales are 100, commission_notional_collected = 100 means $0.01 — not $1.00. The relevant fields:

Field	Where	Meaning
`commission_notional_collected`	execution	Fee collected for this fill, in notional units. Negative values are rebates credited to the account.
`commission_notional_total_collected`	embedded order	Cumulative fee across all fills of the order, in notional units.
`fractional_quantity_scale`, `price_scale`	embedded order	The scales to decode with. Also published per instrument as `fractionalQtyScale` / `priceScale` by the Reference Data API; treat an instrument that does not publish `fractionalQtyScale` as scale `1`.

The dollar amount always reconciles with the fee schedule formula Fee = Θ × C × p × (1 − p) — where C is contracts (not raw order_qty units) and p is the decimal price — rounded to $0.01.

The most common reconciliation mistake is using raw order_qty units as C. On an instrument with fractional_quantity_scale = 100, that overstates the fee 100×. Instruments with scale 1 make the naive math accidentally correct, so the error often surfaces only on the first fill in a scale-100 market.

Worked example — quantity scale 100

A taker buys order_qty = 312 at price = 97 on an instrument with priceScale = 100 and fractionalQtyScale = 100. The fill execution report (captured from Drop Copy; identifiers anonymized):

{
  "id": "BW9QY8RWN52Z",
  "order": {
    "id": "BT3DNMHB94XJ",
    "type": "ORDER_TYPE_LIMIT",
    "side": "SIDE_BUY",
    "orderQty": "312",
    "symbol": "aachc-cfb-undefeated-2026-11-28-boise",
    "clordId": "example-taker-buy-01",
    "timeInForce": "TIME_IN_FORCE_FILL_OR_KILL",
    "account": "firms/ISV-Example-ClearingMember/accounts/example-trading-account",
    "cumQty": "312",
    "avgPx": "97",
    "state": "ORDER_STATE_FILLED",
    "priceToQuantityFilled": { "97": "312" },
    "commissionNotionalTotalCollected": "100",
    "priceScale": "100",
    "fractionalQuantityScale": "100"
  },
  "lastShares": "312",
  "lastPx": "97",
  "type": "EXECUTION_TYPE_FILL",
  "aggressor": true,
  "commissionNotionalCollected": "100"
}

Decode:

contracts   = 312 / 100                 = 3.12
price       = 97 / 100                  = $0.97
fee formula = 0.06 × 3.12 × 0.97 × 0.03 = $0.005448 → rounds to $0.01
wire fee    = 100 / (100 × 100)         = $0.01  ✓

The account’s balance-ledger entry for this fill confirms the same number: a debit of 3.0364 = 3.12 × $0.97 principal ($3.0264) plus the $0.01 commission.

Worked example — quantity scale 1

A taker buys order_qty = 100 at price = 97 on an instrument with priceScale = 100 and fractionalQtyScale = 1, so order_qty is the contract count. The fill carries commissionNotionalCollected = "17" with "fractionalQuantityScale": "1":

contracts   = 100 / 1                  = 100
price       = 97 / 100                 = $0.97
fee formula = 0.06 × 100 × 0.97 × 0.03 = $0.1746 → rounds to $0.17
wire fee    = 17 / (100 × 1)           = $0.17  ✓

This matches the 100-lot examples in the fee schedule — those tables assume scale-1 instruments. The ledger debit is 97.17 = $97.00 principal + $0.17 commission.

Maker rebates and zero-fee fills

The same decoding applies to the maker side, where the fee coefficient is negative. The resting sell in the scale-1 example above received commissionNotionalCollected = "-4" → −$0.04, matching −0.0125 × 100 × 0.97 × 0.03 = −$0.036 rounded to the cent. Because fees round to $0.01, small fills legitimately produce zero fee: the maker rebate in the scale-100 example rounds −$0.0011 to $0.00, and the field is simply absent from the JSON (proto3 omits default values). Treat a missing commission field as 0, not as missing data.

Customer identity

order.account is the only customer identifier accepted by CreateVendorOrder. Persist the DCM account delivered when KYC is approved and use it consistently for:

order.account on partner order placement
participant_account_id on transfers
the account field on Drop Copy and reconciliation records

Do not set order.user or order.session_id. The service authenticates your firm, verifies that order.account belongs to an enabled participant relationship, and derives the submitting participant.

MoneyAmount

Field	Type	Description
`value`	`string`	Base-10 decimal string, such as `"0.10"`.
`currency`	`string`	ISO 4217 code. Must be `USD`.

MoneyAmount is used for the top-level vendor_fee; it is not used for the fixed-point fields in the embedded public order.

Next step

CreateVendorOrder

See complete YES, NO, cash-BUY, and cash-SELL order examples.

Start Here

Partner Types & Eligibility

Get Connected

Onboard Participants

Funding & Transfers

Submitting Orders

Monitor & Reconcile

Supported fields

Outcomes and prices

Fixed-point values

Fees on execution reports

Worked example — quantity scale 100

Worked example — quantity scale 1

Maker rebates and zero-fee fills

Customer identity

MoneyAmount

Next step

CreateVendorOrder

​Supported fields

​Outcomes and prices

​Share and cash quantities

​Fixed-point values

​Fees on execution reports

​Worked example — quantity scale 100

​Worked example — quantity scale 1

​Maker rebates and zero-fee fills

​Customer identity

​MoneyAmount

​Next step

CreateVendorOrder

Supported fields

Outcomes and prices

Share and cash quantities

Fixed-point values

Fees on execution reports

Worked example — quantity scale 100

Worked example — quantity scale 1

Maker rebates and zero-fee fills

Customer identity

MoneyAmount

Next step