> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt > Use this file to discover all available pages before exploring further. # Execute a payout (balance withdrawal) > Withdraw balance from a trading account **synchronously** — the new balance applies as soon as the request returns. **Idempotency (recommended):** send an `Idempotency-Key` header (or the equivalent `x-idempotency-key` — both spellings work everywhere). Replays with the same key never withdraw twice: you get the original payout back (a replay may return HTTP 200 with `duplicate: true`), so it's safe to retry on timeouts. **What a payout does to the account:** 1. Deducts `amount` from the balance. The daily baseline and high-water mark shift down by the same amount, so the withdrawal never appears as a trading loss or phantom drawdown. 2. `moveMllToLock` (optional): locks the loss floor at `initial balance + payoutMllLockOffset` (rule default, e.g. +$100) or at your explicit `lockBalance`. From then on, equity at/below the floor is a max-loss violation. 3. `consistencyReset` (optional): starts a new payout cycle — the funded consistency rule resets to $0 cycle profit. 4. `enforceConsistency` (optional): pre-checks the funded consistency rule and rejects the payout with the full status if any day in the cycle reaches the daily cap. **Requirements:** the account must be flat (no open positions or working orders) and tradable. **Webhooks:** `account.payout_processed` fires on every executed payout; `account.max_payouts_reached` fires when the account hits the rule's `maxPayouts` (e.g. "goes live after 5 payouts"). **Example:** ```bash curl -X POST ".../v1/organization/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/payouts" \ -H "X-API-Key: hp_live_your_key_here" \ -H "x-idempotency-key: payout-2026-07-13-acc7c9e" \ -H "Content-Type: application/json" \ -d '{ "amount": 1600, "moveMllToLock": true, "consistencyReset": true, "enforceConsistency": true }' ``` **Error codes:** | Code | Meaning | |------|---------| | `OPEN_EXPOSURE` | Account has open positions/working orders — flatten first | | `CONSISTENCY_BLOCKED` | Funded consistency rule fails right now (response includes the full consistency status with the blocking days) | | `INVALID_AMOUNT` | Amount exceeds balance, or post-payout balance would breach the requested loss floor | | `ACCOUNT_NOT_TRADABLE` | Account is violated/completed/paused | | `ENGINE_UNREACHABLE` | Engine did not respond — the payout was NOT executed; retry with the same idempotency key | ## OpenAPI ````yaml /api-reference/openapi.json post /v1/organization/accounts/{accountId}/payouts openapi: 3.0.0 info: title: Hyperprop Platform API version: 1.0.0 description: >- REST API for the Hyperprop Trading Platform — provision evaluation and funded trading accounts, manage traders and plans, react to account lifecycle events via signed webhooks, and reconcile billing. Built for prop firms integrating from their own backend. Authentication, quick start, error handling, idempotency, pagination, custom metadata, webhooks, and the MCP connector are documented at https://docs.hyperprop.com. x-logo: url: https://app.hyperprop.com/logo-icon.svg altText: Hyperprop href: https://hyperprop.com servers: - url: https://api.hyperprop.com/platform description: Production security: [] tags: - name: Trading accounts description: Create, update, and inspect trading accounts. - name: Traders description: Look up and update the traders in your organization. - name: Trading plans description: Define the plans you sell. - name: Trading rules description: Define how accounts are evaluated. - name: Lockouts description: Pause and resume trading on an account. - name: Payouts description: Check payout eligibility and record payouts. - name: Purchases description: Purchases recorded for your organization. - name: Time Machine description: Restore accounts to an earlier trading day or instant. - name: Webhooks description: Register webhook endpoints and inspect deliveries. - name: Events description: Your organization's event history and real-time event stream. - name: Reconciliation description: Balances, end-of-day snapshots, and fills for reconciliation. - name: Analytics description: Organization performance and plan economics. - name: Billing description: 'Your Hyperprop bill: activity, billing cycles, and forecasts.' - name: Team and roles description: Manage dashboard access for your staff. - name: API keys description: Manage your organization's API key. - name: Logs and health description: API request logs, the audit log, and integration health. - name: Organization profile description: Your organization's profile and logo. - name: Support description: Open and follow up on support tickets. - name: Partner access description: >- Read a trader's journal as an approved partner app, with the trader's own key. paths: /v1/organization/accounts/{accountId}/payouts: post: tags: - Payouts summary: Execute a payout (balance withdrawal) description: >- Withdraw balance from a trading account **synchronously** — the new balance applies as soon as the request returns. **Idempotency (recommended):** send an `Idempotency-Key` header (or the equivalent `x-idempotency-key` — both spellings work everywhere). Replays with the same key never withdraw twice: you get the original payout back (a replay may return HTTP 200 with `duplicate: true`), so it's safe to retry on timeouts. **What a payout does to the account:** 1. Deducts `amount` from the balance. The daily baseline and high-water mark shift down by the same amount, so the withdrawal never appears as a trading loss or phantom drawdown. 2. `moveMllToLock` (optional): locks the loss floor at `initial balance + payoutMllLockOffset` (rule default, e.g. +$100) or at your explicit `lockBalance`. From then on, equity at/below the floor is a max-loss violation. 3. `consistencyReset` (optional): starts a new payout cycle — the funded consistency rule resets to $0 cycle profit. 4. `enforceConsistency` (optional): pre-checks the funded consistency rule and rejects the payout with the full status if any day in the cycle reaches the daily cap. **Requirements:** the account must be flat (no open positions or working orders) and tradable. **Webhooks:** `account.payout_processed` fires on every executed payout; `account.max_payouts_reached` fires when the account hits the rule's `maxPayouts` (e.g. "goes live after 5 payouts"). **Example:** ```bash curl -X POST ".../v1/organization/accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/payouts" \ -H "X-API-Key: hp_live_your_key_here" \ -H "x-idempotency-key: payout-2026-07-13-acc7c9e" \ -H "Content-Type: application/json" \ -d '{ "amount": 1600, "moveMllToLock": true, "consistencyReset": true, "enforceConsistency": true }' ``` **Error codes:** | Code | Meaning | |------|---------| | `OPEN_EXPOSURE` | Account has open positions/working orders — flatten first | | `CONSISTENCY_BLOCKED` | Funded consistency rule fails right now (response includes the full consistency status with the blocking days) | | `INVALID_AMOUNT` | Amount exceeds balance, or post-payout balance would breach the requested loss floor | | `ACCOUNT_NOT_TRADABLE` | Account is violated/completed/paused | | `ENGINE_UNREACHABLE` | Engine did not respond — the payout was NOT executed; retry with the same idempotency key | operationId: postV1OrganizationAccountsAccountidPayouts parameters: - description: Trading account to withdraw from x-format: guid: true name: accountId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Model718' responses: '201': description: Payout processed content: '*/*': schema: $ref: '#/components/schemas/Model720' '401': description: Authentication required content: '*/*': schema: $ref: '#/components/schemas/Model9' '403': description: Access denied content: '*/*': schema: $ref: '#/components/schemas/Model47' '404': description: Account not found content: '*/*': schema: $ref: '#/components/schemas/Model721' '409': description: Payout blocked (open exposure or consistency rule) content: '*/*': schema: $ref: '#/components/schemas/Model723' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model5' security: - X-API-Key: [] components: schemas: Model718: type: object properties: amount: type: number description: Amount to withdraw from the account balance ($) example: 1600 x-constraint: greater: 0 moveMllToLock: type: boolean description: >- Lock the max-loss floor after the withdrawal: floor = initial balance + the rule's payoutMllLockOffset (or lockBalance when provided). Equity at/below the locked floor fails the account. example: true default: false lockBalance: type: number description: >- Explicit loss-floor balance for moveMllToLock (overrides the rule's payoutMllLockOffset). example: 50100 x-constraint: greater: 0 consistencyReset: type: boolean description: >- Start a new consistency payout cycle at the post-withdrawal balance. The funded consistency rule then measures against profit made after this payout. example: true default: false enforceConsistency: type: boolean description: >- Reject the payout (409 CONSISTENCY_BLOCKED, with the full consistency status in the response) when the account currently fails its funded consistency rule. example: true default: false required: - amount Model720: type: object properties: success: type: boolean example: true message: type: string example: Payout processed successfully data: $ref: '#/components/schemas/Model719' Model9: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Authentication required code: type: string description: Machine-readable error code — switch on this, not on message text example: UNAUTHORIZED Model47: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: Access denied code: type: string description: Machine-readable error code — switch on this, not on message text example: FORBIDDEN Model721: type: object properties: statusCode: type: number example: 404 error: type: string example: Not Found message: type: string example: Account not found in your organization code: type: string example: ACCOUNT_NOT_FOUND Model723: type: object properties: success: type: boolean example: false code: type: string example: CONSISTENCY_BLOCKED message: type: string example: >- Best day $1,290.00 reaches the $1,290.00 daily cap (50% of $2,500.00 + $40.00 buffer). Spread gains across more days to dilute it. consistency: $ref: '#/components/schemas/Model722' Model5: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 500 error: type: string example: Internal Server Error message: type: string example: An unexpected error occurred code: type: string description: Machine-readable error code — switch on this, not on message text example: INTERNAL_ERROR Model719: type: object example: payoutId: e5f6a7b8-c9d0-1234-ef01-234567890abc accountId: 7c9e6679-7425-40de-944b-e07fc1f90ae7 amount: 1600 balanceBefore: 52500 balanceAfter: 50900 payoutCount: 1 mllLockedTo: 50100 consistencyReset: true maxPayoutsReached: false duplicate: false properties: payoutId: type: string accountId: type: string amount: type: number balanceBefore: type: number balanceAfter: type: number payoutCount: type: number mllLockedTo: type: number consistencyReset: type: boolean maxPayoutsReached: type: boolean duplicate: type: boolean Model722: type: object description: Full consistency status incl. blocking days securitySchemes: X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key. Format: "hp_live_{key}". Organization admins manage the key in the dashboard. ```` ## Related topics - [List payouts for an account](/platform-api/payouts/list-payouts-for-an-account.md) - [Webhooks](/guides/webhooks.md) - [Idempotency](/concepts/idempotency.md) - [Payout queue — bulk payout eligibility](/platform-api/payouts/payout-queue-—-bulk-payout-eligibility.md) - [Update a trading account](/platform-api/trading-accounts/update-a-trading-account.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.