> ## 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.

# Create a Funded Order

> Idempotently prefund a participant account and place the order, with automatic reversal on rejection.

<Warning>
  **BETA — SUBJECT TO CHANGE.** This API is in beta and may change without notice.
</Warning>

`CreateFundedOrder` executes the full on-demand funding flow in one call: it validates the request, transfers the total prefund (collateral + exchange fee reserve + vendor fee) from your partner funding account into the participant's account, submits the limit order, and waits for the exchange's durable outcome before returning.

## Service definition

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

```protobuf theme={null}
service OrderFundingService {
    rpc CreateFundedOrder(CreateFundedOrderRequest)
        returns (CreateFundedOrderResponse);
}
```

## Request

### CreateFundedOrderRequest

| Field                 | Type          | Required | Description                                                                                                                                                                       |
| --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order`               | `FundedOrder` | Yes      | The order to fund and place. See [FundedOrder](/partners/funding/preview-funded-order#fundedorder) for the full field reference.                                                  |
| `customer_account_id` | `string`      | Yes      | The participant trading account that receives the prefund and owns the order, in the same format returned by the account onboarding/list APIs.                                    |
| `vendor_fee`          | `MoneyAmount` | Yes      | Your static USD vendor fee for this order. Prefunded into the participant account as part of `total_prefund`; collected via the partner settlement sweep after an accepted order. |
| `idempotency_key`     | `string`      | Yes      | Your unique key for this funded-order request. Retries with the same key never double-fund or double-place — see [Idempotency and retries](#idempotency-and-retries).             |

## Response

### CreateFundedOrderResponse

| Field                 | Type                 | Description                                                                                                        |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `funding_request_id`  | `string`             | Service-assigned identifier of this funding attempt.                                                               |
| `prefund_transfer_id` | `string`             | Identifier of the aggregate prefund transfer into the participant account.                                         |
| `id`                  | `string`             | Exchange order identifier.                                                                                         |
| `status`              | `FundedOrderStatus`  | Terminal or current status of the funded-order flow. See below.                                                    |
| `cost_breakdown`      | `CostBreakdown`      | The prefund economics actually applied. See [CostBreakdown](/partners/funding/preview-funded-order#costbreakdown). |
| `correlation`         | `FundingCorrelation` | Echoed `idempotency_key`, `funding_request_id`, and service `request_id` for audit and support. Log these.         |

### FundedOrderStatus

| Status                         | Meaning                                                                                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `FUNDED_ORDER_STATUS_ACCEPTED` | The order **durably reached the book or matched immediately**. The prefund remains in the participant account.                            |
| `FUNDED_ORDER_STATUS_REJECTED` | The order did not reach the book. The prefund has been (or is being) returned to your partner funding account by a compensating reversal. |
| `FUNDED_ORDER_STATUS_PENDING`  | The outcome could not be confirmed within the request deadline. Retry with the **same** `idempotency_key` to resolve — see below.         |

<Info>
  **`ACCEPTED` means durable acceptance.** The service does not report an order as accepted based on submission alone — it waits for the exchange's durable outcome. An order the exchange rejects asynchronously after submission is returned as `REJECTED` with the prefund reversed, not as a phantom accepted order.
</Info>

## Idempotency and retries

The `idempotency_key` identifies one funded-order request for your authenticated firm. The service guarantees **at most one** prefund transfer and **at most one** resting order per key:

* **Retry on transport failure or timeout** (deadline exceeded, connection loss, `UNAVAILABLE`): call again with the same key. If the original attempt completed, you get its recorded terminal result; if it was interrupted, the service resumes or resolves it.
* **Retry on `PENDING`**: call again with the same key. The service re-checks the exchange outcome and either returns the terminal result or safely resumes the flow.
* **Never reuse a key for a different order.** Use a fresh key for each new funded-order request.

## Compensating reversal

When the prefund transfer succeeds but no order durably reaches the book — validation failure at the exchange, rejection, or permanent submission failure — the service automatically reverses **exactly the total prefund amount** from the participant account back to your partner funding account. The reversal is linked to the original `funding_request_id` and `prefund_transfer_id`, and both legs are visible on the [balance ledger](/streaming-endpoints/balance-ledger-stream).

You do not need to trigger or manage reversals; a `REJECTED` response means the reversal path has been taken.

<Warning>
  **The automatic reversal covers pre-book failures only.** An order that durably reaches the book and *then* ends with residual cash — including a **FOK that is accepted and cancels with zero fill** — is past the reversal boundary: the prefund stays in the participant account until you sweep it back. See [Settlement Sweeps](/partners/funding/sweeps).
</Warning>

## Cancelling a funded order

<Warning>
  **COMING SOON — `CancelFundedOrder` is planned and not currently available.** Do **not** substitute the generic trading cancel (or FIX) for a funded order — generic order-entry paths do not perform the funding workflow's bookkeeping. Until the cancellation RPC is released, rely on order `tif` (e.g. `TIME_IN_FORCE_DAY`, `GOOD_TILL_TIME`) to bound order lifetime, and contact [institutional@polymarket.us](mailto:institutional@polymarket.us) if you need an order cancelled.
</Warning>

## Example

```python theme={null}
import uuid

request = order_funding_pb2.CreateFundedOrderRequest(
    order=order_funding_pb2.FundedOrder(
        market_slug="example-market-slug",
        type=order_funding_pb2.ORDER_TYPE_LIMIT,
        price=order_funding_pb2.MoneyAmount(value="0.45", currency="USD"),
        quantity="100",
        tif=order_funding_pb2.TIME_IN_FORCE_DAY,
        intent=order_funding_pb2.ORDER_INTENT_OPEN,
        outcome_side=order_funding_pb2.OUTCOME_SIDE_YES,
        action=order_funding_pb2.ORDER_ACTION_BUY,
        manual_order_indicator=order_funding_pb2.MANUAL_ORDER_INDICATOR_AUTOMATED,
    ),
    customer_account_id="<customer-account-id>",
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=str(uuid.uuid4()),
)

response = stub.CreateFundedOrder(request, metadata=metadata)
print(response.status, response.id, response.funding_request_id)
```

## Errors

| gRPC status           | Meaning                                                                                      | Retry guidance                                                             |
| --------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `INVALID_ARGUMENT`    | Malformed or unsupported order parameters, invalid vendor fee, or missing `idempotency_key`. | Fix the request. Do not retry as-is.                                       |
| `UNAUTHENTICATED`     | Missing or invalid access token.                                                             | Refresh the token and retry.                                               |
| `PERMISSION_DENIED`   | No enabled funding relationship for your firm, or vendor fee not allowed.                    | Contact [institutional@polymarket.us](mailto:institutional@polymarket.us). |
| `NOT_FOUND`           | Unknown market or customer account.                                                          | Fix the request.                                                           |
| `FAILED_PRECONDITION` | Insufficient funds in your partner funding account for the total prefund.                    | Fund the partner account, then retry with the same key.                    |
| `UNAVAILABLE`         | Transient service or exchange unavailability.                                                | Retry with the **same** `idempotency_key`.                                 |

An order-level rejection (for example, a price outside market limits) is not a gRPC error: the call returns `OK` with `status = FUNDED_ORDER_STATUS_REJECTED`, and the prefund is reversed. Quote the `correlation` identifiers when you need the underlying rejection detail from support.