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

# Settlement Sweeps

> The planned cash-movement API for sweeping released funds from participant accounts back to the partner funding account.

<Warning>
  **COMING SOON — NOT YET AVAILABLE.** This page describes the **planned** sweep API so you can design your integration ahead of release. The contract below is directional and may change before launch; nothing on this page is callable today. Contact [institutional@polymarket.us](mailto:institutional@polymarket.us) for availability.
</Warning>

After a funded order reaches a terminal state, any residual cash in the participant's account — excess collateral, unconsumed fee reserve, realized profit, released margin — must be swept back to your partner funding account **by you**. The [funding overview](/partners/funding/overview#after-acceptance-settlement-and-sweeps) covers the concept; this page describes the planned API for executing it.

## When you sweep — and when Polymarket US does

| Scenario                                                                            | Who moves the money                                                                                                                             |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Prefund succeeded but the order was **rejected or failed before reaching the book** | **Polymarket US** — automatic compensating reversal; `CreateFundedOrder` returns the error                                                      |
| Order reached the book, then filled / partially filled / cancelled / expired        | **You** — sweep the residual                                                                                                                    |
| **FOK accepted, then cancelled with zero fill**                                     | **You** — a durably created FOK is past the automatic-reversal boundary; its full prefund remains in the participant account until you sweep it |

The automatic reversal covers only pre-book failures. Everything after durable creation follows the same residual-sweep path.

## The safe-sweep precondition

Create a sweep only when **both** are true:

1. Your execution/position processing (from the [Drop Copy streams](/streaming-endpoints/dropcopy-stream)) indicates funds may have been released, **and**
2. An authoritative balance read (`PositionAPI/GetAccountBalance`) confirms the amount — see [Reconciliation](/partners/reconciliation) for the read APIs.

Never sweep on stream events alone: quantities may be estimates until fee collection and settlement post to the ledger.

## Planned service

**Service:** `polymarket.us.cashmovement.v1.CashMovementService`

Cash movement is **firm-scoped** — do not send `x-participant-id`. The source account is explicit in the request, and the destination (your funding account) is resolved from your firm's configured funding relationship; you cannot direct funds anywhere else.

### CreateCashMovement

```protobuf theme={null}
message CreateCashMovementRequest {
  string idempotency_key;
  oneof intent { OdfSweep odf_sweep; }
}

message OdfSweep {
  string source_account_id;   // the participant account to sweep from
  string amount;              // exact decimal
  string currency;            // ISO 4217
  OdfSweepReason reason;      // see below
  string external_reference;  // your reference
  string order_id;
  string execution_id;
  string market_id;
  string memo;
}

message CreateCashMovementResponse { CashMovement cash_movement; }
```

Sweep reasons: `VENDOR_FEE`, `EXCESS_COLLATERAL`, `RELEASED_MARGIN`, `REALIZED_PNL`, `SETTLEMENT_CREDIT`, `CANCEL_EXPIRE_CLEANUP`.

Populate `order_id`, `execution_id`, `market_id`, and `external_reference` whenever available — they tie the sweep to its cause on the audit trail.

### GetCashMovement

```protobuf theme={null}
message GetCashMovementRequest { string workflow_id; }
message GetCashMovementResponse { CashMovement cash_movement; }

message CashMovement {
  string workflow_id;
  string idempotency_key;
  string intent_type;
  CashMovementStatus status;  // PENDING, CONFIRMED, REJECTED, AMBIGUOUS
  string amount;
  string currency;
  string source_account_id;
  string destination_account_id;
  string dco_transfer_id;
  string rejection_reason;
  google.protobuf.Timestamp created_at;
  google.protobuf.Timestamp updated_at;
}
```

## Idempotency and recovery

The same discipline as [funded orders](/partners/funding/create-funded-order#idempotency-and-retries):

* Use a **distinct, durable idempotency key per logical sweep**, persisted before the call.
* A transport timeout or an `AMBIGUOUS` status is **not** permission to create a second workflow — replay the same create request with the same key, or read the original workflow by `workflow_id`.
* Use bounded recovery for `PENDING` workflows rather than a permanent polling scheduler.
* Persist `workflow_id` and all correlation fields through a terminal result.

## Correlating sweeps to orders

For funded orders, the execution stream's `clord_id` equals the `funding_request_id` returned by `CreateFundedOrder`, and the create response carries `prefund_transfer_id`. Persist all of these at placement time so your sweep pipeline can join stream events → order → prefund → sweep without guesswork.

## Related pages

<CardGroup cols={2}>
  <Card title="On-Demand Funding Overview" icon="building-columns" href="/partners/funding/overview">
    The model — including the sweep lifecycle and directional guarantees.
  </Card>

  <Card title="Reconciliation" icon="scale-balanced" href="/partners/reconciliation">
    The ledger reads that back the safe-sweep precondition.
  </Card>
</CardGroup>