> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt
> Use this file to discover all available pages before exploring further.
# On-Demand Funding
> How participant accounts are funded at order time — the model, the parties, and the full order-to-sweep workflow.
**BETA — SUBJECT TO CHANGE.** This API is in beta, enabled per partner. Email **[institutional@polymarket.us](mailto:institutional@polymarket.us)** to discuss access for your integration.
On-demand funding is the funding model for IB/ISV partners: instead of a Retail Participant pre-depositing cash at Polymarket US, their trading account is funded **at the moment an order is placed**. In a single [`CreateFundedOrder`](/partners/funding/create-funded-order) call, Polymarket US transfers the exact cost of the order — collateral, exchange fee reserve, and your vendor fee — from your **partner funding account** into the participant's account, then submits the order. If the order never durably reaches the book, the transfer is automatically reversed. After trades settle, funds flow back the other way via **settlement sweeps**.
On-demand funding is available to **IB and ISV partners with a configured funding relationship** only. The service authenticates your partner firm and looks up your funding configuration; calls from firms without a funding relationship are rejected.
## Why this model exists
**The problem is bank speed.** If every Retail Participant had to move cash from their bank into the clearinghouse before trading, fiat rails would set the pace of your product: a newly onboarded user couldn't place their first trade until their deposit cleared, and an existing user topping up would wait just as long between requesting a deposit and having funds available to trade. Bank transfers take hours to days; a trading opportunity doesn't.
**The solution is to keep the cash close, in aggregate.** Participant cash is custodied by your *funding entity* (typically the wallet provider affiliated with your firm), which maintains one pooled **partner funding account** at Polymarket US, pre-positioned ahead of trading. Funding an individual order then becomes an **instant ledger transfer at order time** — pool → participant account → order on the book, in one call — rather than a per-participant bank movement. Onboarding-to-first-trade and deposit-to-tradeable shrink from days to seconds.
**The structure follows the rules on who may hold customer funds.** Regulation constrains which intermediaries are permitted to hold customer funds — and an IB or ISV is not one of them. The model is designed around that constraint:
* The pooled funds are held by the **funding entity** — a separate legal entity in your corporate structure — not by your firm.
* Your firm is a pure **message facilitator**: you authenticate as the Firm, submit orders and instructions on behalf of Retail Participants, and relay funding instructions for your funding entity. Your firm's own identity never holds a balance.
* Funds enter a participant's account **only as part of a specific order**, and leave it **only back to the partner funding account**. Every dollar movement is tied to an order or a sweep, giving a complete audit trail by design.
Legally, a funded order carries two instructions — "move the collateral" and "place the order." Polymarket US accepts them as **one API call** and executes both, so your integration makes a single request instead of coordinating a transfer and an order placement yourself.
## The three parties
| Party | Role | Holds funds at Polymarket US? |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| **Retail Participant** | The trader. Owns a trading account that holds order collateral and positions. | Yes — transiently, per order |
| **Your firm (IB/ISV)** | Message facilitator. Submits funded orders and sweeps on behalf of the participant and the funding entity. | **No — never** |
| **Your funding entity** | Separate legal entity that custodies pooled participant cash off-platform and holds the **partner funding account**. | Yes — the aggregate pool |
The participant, your firm, and your funding entity coordinate through your product's UX and the legal agreements between the three parties. From the participant's point of view they just click "place order" — your backend turns that into one `CreateFundedOrder` call.
## Getting set up
The structure is established once, coordinated with your Polymarket US integration lead during [partner onboarding](/partners/get-connected/onboarding):
1. **Create your funding entity** — a separate legal entity that will custody participant cash and fund orders. Your firm cannot hold participant funds itself.
2. **Two onboardings, coordinated as one workflow** — your firm onboards as an access shell (holds no funds, no positions); your funding entity onboards as its own entity with an active, funded account. **Your funding entity must exist and be active before your firm's API credentials can be enabled.**
3. **Credentials linked to the funding account** — your firm's API credentials are provisioned against your funding entity's account. From then on, every funded order draws from it automatically.
4. **Each participant gets a \$0 account** — provisioned automatically on KYC approval (see [Onboard Participants](/partners/onboarding/onboard-participants)). Accounts start empty and hold funds only order-by-order.
5. **Three-party agreement in place** — participant, your firm, and your funding entity must have an agreement authorizing the fund movements and sweeps.
The funding relationship is fixed per firm: a firm is either fully on-demand funded or not — there is no per-order or per-participant mixing.
## The funded order workflow
```mermaid theme={null}
sequenceDiagram
participant RP as Retail Participant
participant App as Your App
participant PM as Polymarket US
RP->>App: Place order
App->>PM: PreviewFundedOrder (optional)
PM-->>App: Cost breakdown (collateral + fees)
App->>PM: CreateFundedOrder (order, participant account, vendor fee, idempotency key)
Note over PM: 1. Transfer total prefund
partner funding account → participant account
Note over PM: 2. Submit limit order,
wait for durable outcome
alt Order durably reaches the book
PM-->>App: ACCEPTED — prefund stays in participant account
else Order rejected
Note over PM: Compensating reversal
participant account → partner funding account
PM-->>App: REJECTED — prefund returned in full
end
App-->>RP: Confirmation
```
1. *(Optional)* You call [`PreviewFundedOrder`](/partners/funding/preview-funded-order) to show the participant the cost breakdown. Preview is informational — placement recomputes all economics from the placement request.
2. You call [`CreateFundedOrder`](/partners/funding/create-funded-order) with the order, the participant's `customer_account_id`, your `vendor_fee`, and a required `idempotency_key`.
3. Polymarket US calculates the total prefund and transfers it from your partner funding account into the participant's account in one aggregate transfer.
4. It then submits the limit order and waits for the exchange's durable outcome.
5. You receive a terminal response:
* **`ACCEPTED`** — the order durably reached the book (or matched immediately). The prefund stays in the participant's account.
* **`REJECTED`** — the order did not reach the book. A **compensating reversal** returns the full prefund to your partner funding account automatically. You never trigger or manage reversals yourself.
If the funding account can't cover the prefund, or the participant account doesn't exist, the call fails **before** any order reaches the book — see the [error reference](/partners/funding/create-funded-order#errors).
## Cost model
```
total_prefund = collateral + exchange_fee + vendor_fee
```
| Component | Semantics |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collateral` | Worst-case collateral for the limit order: `quantity × price` for buys, `quantity × (1 − price)` for sells on binary event contracts. No margin compression from existing positions is assumed. |
| `exchange_fee` | An **estimated maximum reserve**, sufficient for a full fill at the least favorable permitted execution price (see the [fee schedule](/fees)). The exchange collects the actual fee per execution as fills occur — the amount actually collected can be lower than the reserve after partial fills, and unfilled cancelled/expired quantity collects nothing. |
| `vendor_fee` | A static USD amount **you** supply on the request, calculated per your agreement with the participant. The service validates that it is well-formed, non-negative, and allowed for your firm; it does not compute it from a percentage or schedule. |
| `total_prefund` | The exact amount transferred into the participant's account before order submission — and the exact amount reversed if no order reaches the book. |
Because collateral is sized pessimistically, an accepted order frequently leaves **excess** in the participant's account — after a partial fill, a cancel of resting quantity, or fee collection below the reserve. That excess is recovered by sweeps, below.
**You compute the vendor fee.** If your agreement with the participant is 2% and the order principal is \$100, you send `"2.00"` — the platform never derives it from a percentage or schedule. Tracking and administering vendor fees per order, in line with your own terms of service, is your responsibility: the platform prefunds and sweeps the amounts you supply but does not account for them on your behalf.
## After acceptance: settlement and sweeps
An `ACCEPTED` response is the *start* of the money lifecycle, not the end. As the order fills, settles, is cancelled, or the position closes, cash lands in (or is released within) the participant's account:
| Event | What lands in the participant account |
| -------------------------------- | -------------------------------------------- |
| Partial fill, then cancel/expiry | Unused collateral and unconsumed fee reserve |
| Order cancelled before any fill | The full prefund |
| Trade settles at a profit | Realized profit plus released collateral |
| Position closed | Released margin |
**Nothing moves back automatically.** Polymarket US does not decide when participant funds return to the pool — that is governed by the agreements between the participant, your firm, and your funding entity. Your backend:
1. **Monitors** the participant account in real time via the [Balance Ledger Stream](/streaming-endpoints/balance-ledger-stream) — every prefund, reversal, fill, fee, and settlement credit appears as a ledger event.
2. **Determines** the sweepable amount and timing per your agreements, relaying balance information to your funding entity as needed.
3. **Initiates a sweep** — a transfer from the participant's account back to the partner funding account — via the settlement sweep flow.
**Settlement sweeps are available as part of the beta rollout.** See [Settlement Sweeps](/partners/funding/sweeps) for the API contract. Contact [institutional@polymarket.us](mailto:institutional@polymarket.us) for beta access.
### Directional guarantees
The platform enforces the audit-trail asymmetry at the API level:
| Money movement | Mechanism | Allowed? |
| --------------------------------------------------------- | ---------------------------------------------------------- | ---------- |
| Partner funding account → participant account | `CreateFundedOrder` only — always tied to a specific order | ✅ |
| Participant account → partner funding account | Settlement sweep (or automatic compensating reversal) | ✅ |
| Participant account → your firm, or any other destination | — | ❌ Rejected |
You can only **add** funds to a participant account by funding an order, and only **remove** them back to the configured funding account. This is what lets your firm operate without ever holding participant funds.
## Sizing the funding account
The partner funding account must cover the **peak concurrent prefund** across all your participants — every resting funded order holds its full prefund until it fills, cancels, or is swept back. Size the pool for peak open interest plus fee reserves (not average daily volume), and monitor the funding account's own balance on the ledger stream. A `FAILED_PRECONDITION` on `CreateFundedOrder` means the pool couldn't cover the next order.
At any point the pool should reconcile to a simple identity — maintain a real-time mirror of it from the ledger stream and investigate any drift:
```
pool balance = initial deposit
− Σ prefund transfers (out to participant accounts)
+ Σ sweeps and reversals (back in)
± net realized P&L
− fees collected
```
### Deposits and withdrawals
A participant's cash deposits and withdrawals are movements between the participant and your funding entity — part of their wallet relationship, settled in fiat through your payment provider, entirely outside Polymarket US. What reaches Polymarket US is the aggregate: your funding entity pre-positions the pooled proceeds of those wallet balances in the partner funding account, topping it up or drawing it down on a cadence agreed during onboarding. Per-participant money moves on the platform in only two ways — into a participant account via a funded order, and back to the funding account via a sweep.
## Reliability model
Three properties you can build on — see [`CreateFundedOrder`](/partners/funding/create-funded-order) for the full contract:
* **Idempotency.** Every placement carries your `idempotency_key`; retries with the same key never double-fund or double-place. Retry the same key on timeouts, `UNAVAILABLE`, and `PENDING`.
* **Durable acceptance.** `ACCEPTED` is only returned once the order durably reached the book — never on submission alone. There are no phantom accepted orders.
* **Automatic reversal.** Any path where the prefund moved but no order reached the book ends in a compensating reversal of exactly the prefund amount. A `REJECTED` response means the reversal path has been taken.
## API surface
The API is **gRPC-only**:
**Service:** `polymarket.us.orderfunding.v1.OrderFundingService`
| RPC | Description |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [`PreviewFundedOrder`](/partners/funding/preview-funded-order) | Returns the prefund cost breakdown for an order without moving funds or placing it. |
| [`CreateFundedOrder`](/partners/funding/create-funded-order) | Idempotently transfers the total prefund and submits the order, returning a terminal accepted/rejected result. |
Connection and authentication follow the standard gRPC conventions — TLS and a Bearer access token in the `authorization` metadata header. See the [gRPC API Overview](/grpc-api/overview) for server endpoints and [Authentication](/streaming-endpoints/authentication) for obtaining tokens.
**Funded orders must go through this service.** Do not place or cancel funded-flow orders via generic order entry or FIX — those paths do not perform the prefund workflow.
## Reconciliation
Every cash movement made by on-demand funding — the prefund transfer, any compensating reversal, and sweeps — is visible on the account's cash ledger. Use the standard surfaces to reconcile:
Real-time balance impact of every cash event, with replay.
Funding transaction state changes.
Firm-wide execution reports for placed orders.
Responses also carry correlation identifiers (`idempotency_key`, `funding_request_id`, `request_id`) that you should log and quote in support requests.
## Next steps
Quote the prefund cost breakdown for an order.
Fund and place an order in one idempotent call.