Create an Order

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

CreateVendorOrder is the partner order-entry call: it validates the supported structure of an embedded public polymarket.v1.InsertOrderRequest, records your declared vendor fee against the order, passes the order through to the exchange, and waits for its durable outcome before returning. No money moves in this call — the order trades against cash already in the participant’s account, and the vendor fee accrues for later collection. The exchange is authoritative for order economics and buying-power validation; CreateVendorOrder does not calculate or return order economics.

Service definition

Service: polymarket.us.orderfunding.v1.OrderFundingService
RPC: CreateVendorOrder
Type: Unary (request/response)

service OrderFundingService {
  rpc CreateVendorOrder(CreateVendorOrderRequest)
      returns (CreateVendorOrderResponse);
}

message CreateVendorOrderRequest {
  polymarket.v1.InsertOrderRequest order = 1;
  MoneyAmount vendor_fee = 2;
  string idempotency_key = 3;
}

Request

CreateVendorOrderRequest

Field	Type	Required	Description
`order`	`polymarket.v1.InsertOrderRequest`	Yes	The public order-entry shape. Set only the supported fields.
`vendor_fee`	`MoneyAmount`	Yes	Your fixed USD vendor fee for this order. It is recorded against the exchange order ID and collected later with a `VENDOR_FEES` transfer, never moved at order time.
`idempotency_key`	`string`	Yes	Your unique key for this placement request. Persist it before calling the service.

The participant is identified only by order.account. Use the DCM trading account returned by the KYC approval webhook—the same account identifier used to match the participant’s Drop Copy activity. There is no separate customer-account field in this request. Do not set order.user or order.session_id; both are rejected.

The embedded public message is wider than the partner launch surface. The service uses a fail-closed allowlist: if you populate an unsupported field, the request is rejected with INVALID_ARGUMENT and an error that names the offending field. Do not copy a generic InsertOrderRequest wholesale; construct one of the supported shapes below.

Response

CreateVendorOrderResponse

Field	Type	Description
`funding_request_id`	`string`	Service-assigned durable identifier for this placement workflow. Persist it even if `id` is empty, and include it in support requests.
`id`	`string`	Exchange order identifier, when the exchange assigned one. The vendor fee for an accepted order is recorded under this ID, which is also `order_id` on the Vendor Fees report.
`status`	`VendorOrderStatus`	Durable or current placement outcome. See below.
`correlation`	`FundingCorrelation`	Partner and service identifiers for recovery, audit, and support. Log these.

FundingCorrelation

Field	Type	Description
`idempotency_key`	`string`	Your idempotency key from the request.
`funding_request_id`	`string`	The same durable placement-workflow identifier as the top-level field. It remains stable across retries.
`request_id`	`string`	Per-attempt service request identifier for support and audit. It changes on each retry.
`clord_id`	`string`	Your `order.clord_id`, echoed for recovery and Drop Copy correlation.

VendorOrderStatus

Status	Meaning
`VENDOR_ORDER_STATUS_ACCEPTED`	The exchange durably accepted the order — including an order that matched immediately or was cancelled under fill-or-kill. Acceptance does not mean the order is resting or filled; learn execution outcomes from Drop Copy. The vendor fee is recorded against the order. Terminal.
`VENDOR_ORDER_STATUS_REJECTED`	The order was rejected. Nothing was recorded and no fee accrues. Terminal.
`VENDOR_ORDER_STATUS_PENDING`	The service could not establish the durable exchange outcome before its deadline. No collectible vendor fee exists yet. Durable, but not terminal.

ACCEPTED means durable acceptance, not an execution state. The service does not report acceptance based on submission alone, but an accepted order may have rested, matched immediately, or been cancelled under FOK. Track fills and other execution outcomes on Drop Copy. An order the exchange rejects asynchronously after submission is returned as REJECTED, not as a phantom accepted order.

Funding request lifecycle

Every successful CreateVendorOrder call returns a durable funding_request_id and the workflow’s current status. PENDING is a valid durable response, not a gRPC error: submission may have happened, but the service has not yet established the final exchange outcome. When a response is PENDING, re-check it by calling CreateVendorOrder again with the identical request, including the same idempotency_key and order.clord_id. The service resumes the existing workflow and returns the same funding_request_id with its current status. Continue bounded re-checks until the status is terminal:

VENDOR_ORDER_STATUS_ACCEPTED — terminal accepted outcome.
VENDOR_ORDER_STATUS_REJECTED — terminal rejected outcome.

Do not rotate the idempotency key while a funding request is pending. A new key identifies a new placement workflow and can create a duplicate order. If you reuse the original key with any caller-controlled field changed, the service returns gRPC ALREADY_EXISTS instead of modifying the existing workflow. Persist the funding_request_id, idempotency_key, and clord_id together. The funding request ID identifies the workflow even before an exchange order ID exists and is the primary identifier to quote in support requests.

Supported order examples

These examples deliberately populate only the launch fields. They assume the instrument publishes priceScale = 100 and fractionalQtyScale = 100 in Reference Data. Use each instrument’s published scales when converting decimal prices and quantities to integers. Every order must set exactly one of order_qty or cash_order_qty. This order buys 100 shares at a limit price of $0.45 and must fill immediately in full or cancel.

import uuid
from polymarket.v1 import trading_pb2
from polymarket.us.orderfunding.v1 import order_funding_pb2

clord_id = f"order-{uuid.uuid4()}"
idempotency_key = str(uuid.uuid4())

request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_BUY,
        order_qty=10_000,  # 100.00 shares at fractionalQtyScale=100
        symbol="<market-symbol>",
        price=45,  # $0.45 at priceScale=100
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=clord_id,
        account="<participant-dcm-account>",
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=idempotency_key,
)

response = stub.CreateVendorOrder(request, metadata=metadata)

There is one order book per market, in instrument (YES) terms, and price is always the YES price. Express BUY 10 NO at $0.20 as SELL 10 YES at the complementary $0.80 price. The contract quantity remains 10.

request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_SELL,
        order_qty=1_000,  # 10.00 contracts at fractionalQtyScale=100
        symbol="<market-symbol>",
        price=80,  # YES $0.80 at priceScale=100; equivalent to NO $0.20
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=f"order-{uuid.uuid4()}",
        account="<participant-dcm-account>",
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=str(uuid.uuid4()),
)

response = stub.CreateVendorOrder(request, metadata=metadata)

A fill changes the participant’s position by -10 in YES terms. Economically, buying 10 NO contracts at $0.20 costs $2.00, with $0.08 commission in this example charged additionally. The cost is reflected in the account’s buying power. Partners can query the authoritative cash balance and buying_power with polymarket.v1.PositionAPI/GetAccountBalance; see Reconciliation. The same complementary convention applies in the other direction: SELL q NO at p is BUY q YES at 1 − p. See Outcomes and prices.

Consumer cash BUY: spend $20 on YES

Set cash_order_qty instead of order_qty when the participant specifies a dollar principal. ORDER_TYPE_LIMIT supports this shape. This order spends $20.00 of principal at a YES limit price of $0.80.

request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_BUY,
        cash_order_qty=2_000,  # $20.00 principal at priceScale=100; omit order_qty
        symbol="<market-symbol>",
        price=80,  # YES $0.80 at priceScale=100
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=f"order-{uuid.uuid4()}",
        account="<participant-dcm-account>",
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=str(uuid.uuid4()),
)

response = stub.CreateVendorOrder(request, metadata=metadata)

For a cash BUY, contract quantity is the principal divided by the actual execution price. The $20.00 principal fills 25 contracts when execution occurs at the $0.80 limit, or 62.5 contracts with price improvement to $0.32; the limit bounds the worst-case price. In the fill-at-limit example, a $0.20 commission makes the total cash decrease $20.20. Commission is charged in addition to cash_order_qty.

Consumer cash SELL: spend $20 on NO

On SIDE_SELL, cash_order_qty is complementary NO collateral, not target proceeds. “Spend $20 on NO at up to $0.20” is expressed as a SELL with a YES limit price of $0.80:

request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_SELL,
        cash_order_qty=2_000,  # $20.00 NO collateral at priceScale=100; omit order_qty
        symbol="<market-symbol>",
        price=80,  # YES $0.80 at priceScale=100; equivalent to NO $0.20
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=f"order-{uuid.uuid4()}",
        account="<participant-dcm-account>",
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=str(uuid.uuid4()),
)

response = stub.CreateVendorOrder(request, metadata=metadata)

The exchange divides the $20.00 cash quantity by the $0.20 complement, so the $20.00 buys 100 NO contracts at $0.20. Commission is additional—$0.80 in this example.

On a SELL, cash_order_qty = 2_000 does not mean “sell enough to receive $20.00.” It means spend $20.00 of complementary NO collateral.

Buying power and previews

The exchange validates buying power when the order is placed and rejects an order unless the participant account’s available cash covers its worst-case collateral plus the applicable exchange fee. This authoritative placement check does not reserve accrued vendor fees. Before submission, you may provide client-side guidance by gating against:

spendable balance = account cash − accrued uncollected vendor fees

For a BUY share limit order, client-side worst-case collateral is the contract quantity multiplied by the YES limit price. For a SELL share limit order expressing a NO position, it is the contract quantity multiplied by the complementary NO price. For a cash order, cash_order_qty is the principal: YES principal on BUY or complementary NO collateral on SELL. Add the maximum exchange fee from the fee schedule when estimating required cash; fees are additional to cash_order_qty. CreateVendorOrder does not calculate these amounts. You may calculate them in your client or separately call the public polymarket.v1.OrderEntryAPI/PreviewOrder with the participant’s order shape. The preview is optional and informational, not a locked quote; the exchange validates the order again at placement.

Idempotency and retries

The idempotency_key identifies one placement request for your authenticated firm, while order.clord_id is your standard FIX tag-11 client order ID and recovery key. Persist both before the first call. The service guarantees at most one order per idempotency key — retrying with the same key can never place a duplicate order or double-charge the declared vendor fee.

Retry transport failures and timeouts with the same complete request and the same idempotency_key and clord_id. If the original attempt completed, the service returns its recorded result; otherwise it resumes or resolves the workflow.
Retry PENDING the same way. The service re-checks the exchange outcome and returns the same funding request with its current status.
Match Drop Copy by account and clord_id. order.account is the DCM account on Drop Copy, and the exchange echoes order.clord_id as clOrdID.
Never change the request under an existing key. A different clord_id, account, order field, or vendor fee returns ALREADY_EXISTS.
Never rotate the key for a pending request. A new key creates a new workflow and can submit a duplicate order.
Never reuse a clord_id across live orders for the same participant. Use a fresh idempotency key and client order ID for each new order.

Cancelling an order

An order placed through this service is a standard exchange order. Cancel it through the standard order entry cancel. Cancellation does not alter the recorded vendor fee: the platform records exactly what you declared at placement. If your fee policy waives fees on cancelled or unfilled orders, apply that policy in your books and in the amount you collect.

Errors

gRPC status	Meaning	Retry guidance
`INVALID_ARGUMENT`	A required field is missing; an order or vendor fee is malformed; or an unsupported embedded field is set. The error names an offending unsupported field.	Fix the request. Do not retry as-is.
`UNAUTHENTICATED`	Missing or invalid access token.	Refresh the token and retry.
`PERMISSION_DENIED`	Your firm is disabled or the vendor-fee policy denies the request.	Do not retry unchanged until authorization or policy is corrected.
`NOT_FOUND`	No customer relationship exists for your firm and `order.account`. The same generic error is returned if the account belongs to another firm.	Correct `order.account`.
`FAILED_PRECONDITION`	The customer relationship is inactive, ambiguous, stale, or draining.	Correct the relationship state, then retry according to whether the placement intent changed.
`ALREADY_EXISTS`	The `idempotency_key` is already bound to a different caller-controlled request.	Replay the original request, or use a fresh key only for a genuinely new placement intent.
`UNAVAILABLE`	Transient relationship, policy, persistence, token-minting, or exchange unavailability before a known submission outcome.	Retry the identical request with the same `idempotency_key`.

An order-level rejection from the exchange, such as insufficient buying power or a price outside market limits, is not a gRPC error. The call returns OK with status = VENDOR_ORDER_STATUS_REJECTED; FAILED_PRECONDITION is reserved for relationship-state problems. Quote the correlation identifiers when requesting the underlying rejection detail from support.

Start Here

Partner Types & Eligibility

Get Connected

Onboard Participants

Funding & Transfers

Submitting Orders

Monitor & Reconcile

Service definition

Request

CreateVendorOrderRequest

Response

CreateVendorOrderResponse

FundingCorrelation

VendorOrderStatus

Funding request lifecycle

Supported order examples

Consumer cash BUY: spend $20 on YES

Consumer cash SELL: spend $20 on NO

Buying power and previews

Idempotency and retries

Cancelling an order

Errors

​Service definition

​Request

​CreateVendorOrderRequest

​Response

​CreateVendorOrderResponse

​FundingCorrelation

​VendorOrderStatus

​Funding request lifecycle

​Supported order examples

​Consumer FOK share limit order

​Consumer share order: BUY 10 NO at $0.20

​Consumer cash BUY: spend $20 on YES

​Consumer cash SELL: spend $20 on NO

​Buying power and previews

​Idempotency and retries

​Cancelling an order

​Errors

Service definition

Request

CreateVendorOrderRequest

Response

CreateVendorOrderResponse

FundingCorrelation

VendorOrderStatus

Funding request lifecycle

Supported order examples

Consumer FOK share limit order

Consumer share order: BUY 10 NO at $0.20

Consumer cash BUY: spend $20 on YES

Consumer cash SELL: spend $20 on NO

Buying power and previews

Idempotency and retries

Cancelling an order

Errors