> ## 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. # Credit or debit a trading account > Changes one account's balance by an amount and records it under your own `reference` (for example a deposit or withdrawal ID from your CRM). A positive `amount` credits the account, a negative one debits it. The amount is applied to the live balance as a change, alongside any trading on the account, so it never overwrites profit or loss made at the same moment. The response gives the balance just before and just after it. **Idempotent by reference.** A reference is used once per organization, permanently. Sending the same reference with the same request again returns the original adjustment with `200` and `replayed: true`; it is never applied twice. The same reference with a different request (another account, amount, reason, metadata or option) is refused with `409 REFERENCE_CONFLICT`. The `Idempotency-Key` header is also accepted, as on every write. **Which accounts.** Any account of your organization that is not passed, failed or expired (`409 ACCOUNT_CLOSED`), including accounts not started yet and accounts turned off. **Debits.** A debit that would take the balance below zero is refused (`422 INSUFFICIENT_BALANCE`, checked against the balance when the request arrives). A debit is not checked against the account's loss limits: the account's rules apply to the new balance as after any balance change, so a debit that reaches the maximum loss or drawdown limit fails the account (`account.failed`). Check the account first (`GET /organization/trading-accounts/{accountId}`) when that matters. **Daily P&L and high-water mark.** By default the adjustment is not counted as the day's profit or loss and the high-water mark does not move; see `countTowardDailyPnl` and `moveHighWaterMark`. **Unconfirmed outcome.** In the rare case the change cannot be confirmed in time, the call answers `503 OUTCOME_UNKNOWN` with the adjustment in status `pending`. Send the same request again to settle it. **Webhooks.** `account.balance_adjusted` with the adjustment (reference, amount, balances, your metadata); it is delivered only to endpoints that list it explicitly, never through `["*"]`. As for every balance adjustment, the account also gets `account.updated` with trigger `balance_adjustment`, and `account.balance_changed` with reason `adjustment` for its subscribers. Returns `201` for a new adjustment. Requires **manage** permission on traders. ```bash curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/balance-adjustments" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"amount": 500, "reference": "DEP-2026-104233", "reason": "Deposit via card", "metadata": {"crmTransactionId": "TX-88213"}}' ``` ## OpenAPI ````yaml https://api.hyperprop.com/platform/openapi.json post /v1/organization/trading-accounts/{accountId}/balance-adjustments 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: Instruments description: >- The contracts your organization's accounts can trade, with their specifications. - 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: Mass credit description: >- Credit back losses across many accounts after an incident, as background jobs you can follow, pause, export and reverse. - 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 keys: rotation, read-only keys and IP allowlists. - name: Logs and health description: >- API request logs, the audit log, integration health, and idempotency key recovery. - 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/trading-accounts/{accountId}/balance-adjustments: post: tags: - Trading accounts summary: Credit or debit a trading account description: >- Changes one account's balance by an amount and records it under your own `reference` (for example a deposit or withdrawal ID from your CRM). A positive `amount` credits the account, a negative one debits it. The amount is applied to the live balance as a change, alongside any trading on the account, so it never overwrites profit or loss made at the same moment. The response gives the balance just before and just after it. **Idempotent by reference.** A reference is used once per organization, permanently. Sending the same reference with the same request again returns the original adjustment with `200` and `replayed: true`; it is never applied twice. The same reference with a different request (another account, amount, reason, metadata or option) is refused with `409 REFERENCE_CONFLICT`. The `Idempotency-Key` header is also accepted, as on every write. **Which accounts.** Any account of your organization that is not passed, failed or expired (`409 ACCOUNT_CLOSED`), including accounts not started yet and accounts turned off. **Debits.** A debit that would take the balance below zero is refused (`422 INSUFFICIENT_BALANCE`, checked against the balance when the request arrives). A debit is not checked against the account's loss limits: the account's rules apply to the new balance as after any balance change, so a debit that reaches the maximum loss or drawdown limit fails the account (`account.failed`). Check the account first (`GET /organization/trading-accounts/{accountId}`) when that matters. **Daily P&L and high-water mark.** By default the adjustment is not counted as the day's profit or loss and the high-water mark does not move; see `countTowardDailyPnl` and `moveHighWaterMark`. **Unconfirmed outcome.** In the rare case the change cannot be confirmed in time, the call answers `503 OUTCOME_UNKNOWN` with the adjustment in status `pending`. Send the same request again to settle it. **Webhooks.** `account.balance_adjusted` with the adjustment (reference, amount, balances, your metadata); it is delivered only to endpoints that list it explicitly, never through `["*"]`. As for every balance adjustment, the account also gets `account.updated` with trigger `balance_adjustment`, and `account.balance_changed` with reason `adjustment` for its subscribers. Returns `201` for a new adjustment. Requires **manage** permission on traders. ```bash curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/balance-adjustments" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"amount": 500, "reference": "DEP-2026-104233", "reason": "Deposit via card", "metadata": {"crmTransactionId": "TX-88213"}}' ``` operationId: postV1OrganizationTradingaccountsAccountidBalanceadjustments parameters: - description: Trading account ID x-format: guid: true name: accountId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Model1346' responses: '200': description: >- Replayed - This reference was already applied with the same request; nothing changed content: '*/*': schema: $ref: '#/components/schemas/Model1350' '201': description: Created - The balance changed content: '*/*': schema: $ref: '#/components/schemas/Model1354' '400': description: Validation failed content: '*/*': schema: $ref: '#/components/schemas/Model25' '401': description: Authentication required content: '*/*': schema: $ref: '#/components/schemas/Model11' '403': description: >- Forbidden - The caller lacks traders:manage (`INSUFFICIENT_PERMISSIONS`) content: '*/*': schema: $ref: '#/components/schemas/Model1355' '404': description: Trading account not found content: '*/*': schema: $ref: '#/components/schemas/Model766' '409': description: >- Conflict - The reference was used for a different adjustment (`REFERENCE_CONFLICT`), or the account is passed, failed or expired (`ACCOUNT_CLOSED`); nothing was changed content: '*/*': schema: $ref: '#/components/schemas/Model1359' '422': description: >- Unprocessable Entity - The debit would take the balance below zero (`INSUFFICIENT_BALANCE`); nothing was changed content: '*/*': schema: $ref: '#/components/schemas/Model1361' '500': description: An unexpected error occurred content: '*/*': schema: $ref: '#/components/schemas/Model6' '503': description: >- Service Unavailable - Not confirmed yet (`OUTCOME_UNKNOWN`) or not applied (`ADJUSTMENT_NOT_APPLIED`): send the same request again, it is never applied twice. `FEATURE_NOT_READY`: not available yet, nothing was changed content: '*/*': schema: $ref: '#/components/schemas/Model1363' security: - X-API-Key: [] components: schemas: Model1346: type: object properties: amount: type: number description: >- Signed amount in the account currency, at most 2 decimals: positive credits the account, negative debits it. Not zero; at most 10,000,000 either way. Send a JSON number. example: 500 minimum: -10000000 maximum: 10000000 x-constraint: precision: 2 reference: type: string description: >- Your reference for this adjustment, for example your deposit or withdrawal ID: 1 to 128 characters, letters, digits and `. _ : @ + = ~ -`, starting with a letter or digit. Unique within your organization and case-sensitive. example: DEP-2026-104233 pattern: ^[A-Za-z0-9][A-Za-z0-9._:@+=~-]{0,127}$ reason: type: string description: Shown in the account activity, the audit log and the webhook. example: Deposit via card maxLength: 500 x-convert: trim: true metadata: $ref: '#/components/schemas/Model1345' countTowardDailyPnl: type: boolean description: >- Default `false`: the day's starting balance moves with the adjustment, so it is not counted as that day's profit or loss (the daily loss limit stays where it was). `true`: it counts toward the day's P&L. default: false moveHighWaterMark: type: boolean description: >- Default `false`: the high-water mark (trailing drawdown peak) stays where it is. `true`: it moves by the amount as well. default: false required: - amount - reference Model1350: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Model1349' Model1354: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Model1353' Model25: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 400 error: type: string example: Bad Request message: type: string example: Validation failed code: type: string description: Machine-readable error code — switch on this, not on message text example: VALIDATION_ERROR Model11: 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 Model1355: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: Your role does not have write access to "Traders & accounts" code: $ref: '#/components/schemas/code' Model766: type: object properties: success: type: boolean description: Always false on errors example: false statusCode: type: number example: 404 error: type: string example: Not Found message: type: string example: Trading account not found code: type: string description: Machine-readable error code — switch on this, not on message text example: ACCOUNT_NOT_FOUND Model1359: type: object properties: success: type: boolean example: false statusCode: type: number example: 409 error: type: string example: Conflict message: type: string example: >- Reference "DEP-2026-104233" was already used for a different adjustment; use a new reference code: $ref: '#/components/schemas/Model1356' adjustmentId: type: string description: 'With REFERENCE_CONFLICT: the adjustment that holds the reference' x-format: guid: true adjustment: $ref: '#/components/schemas/adjustment' Model1361: type: object properties: success: type: boolean example: false statusCode: type: number example: 422 error: type: string example: Unprocessable Entity message: type: string example: >- A debit of 600.00 would take the balance (450.00) below zero; nothing was changed code: $ref: '#/components/schemas/Model1360' currentBalance: type: number example: 450 Model6: 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 Model1363: type: object properties: success: type: boolean example: false statusCode: type: number example: 503 error: type: string example: Service Unavailable message: type: string example: >- The adjustment could not be confirmed yet. Send the same request again (same reference) to settle it; it is never applied twice. code: $ref: '#/components/schemas/Model1362' adjustment: $ref: '#/components/schemas/Model760' Model1345: type: object description: >- Up to 20 keys of your own (strings up to 500 characters, numbers, booleans or null), returned as sent and included in the webhook. example: crmTransactionId: TX-88213 method: card Model1349: type: object properties: adjustmentId: type: string example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d x-format: guid: true reference: type: string example: DEP-2026-104233 accountId: type: string example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 x-format: guid: true accountNumber: type: string example: ACC-50K-000123 type: $ref: '#/components/schemas/Model1347' amount: type: number description: 'Signed: positive for a credit, negative for a debit' example: 500 status: $ref: '#/components/schemas/Model1348' reason: type: string example: Deposit via card metadata: $ref: '#/components/schemas/Model759' countTowardDailyPnl: type: boolean example: false moveHighWaterMark: type: boolean example: false balanceBefore: type: number description: The live balance just before the adjustment (null until applied) example: 50000 balanceAfter: type: number description: The live balance just after the adjustment (null until applied) example: 50500 errorCode: type: string description: >- Why it is not applied: `ACCOUNT_CLOSED`, `OUTCOME_UNKNOWN`, or another refusal code example: null errorMessage: type: string example: null requestedBy: type: string description: '`api-key`, or the staff email for a portal user' example: api-key createdAt: type: string example: '2026-10-30T11:02:11.000Z' appliedAt: type: string example: '2026-10-30T11:02:11.412Z' replayed: type: boolean example: true Model1353: type: object properties: adjustmentId: type: string example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d x-format: guid: true reference: type: string example: DEP-2026-104233 accountId: type: string example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 x-format: guid: true accountNumber: type: string example: ACC-50K-000123 type: $ref: '#/components/schemas/Model1351' amount: type: number description: 'Signed: positive for a credit, negative for a debit' example: 500 status: $ref: '#/components/schemas/Model1352' reason: type: string example: Deposit via card metadata: $ref: '#/components/schemas/Model759' countTowardDailyPnl: type: boolean example: false moveHighWaterMark: type: boolean example: false balanceBefore: type: number description: The live balance just before the adjustment (null until applied) example: 50000 balanceAfter: type: number description: The live balance just after the adjustment (null until applied) example: 50500 errorCode: type: string description: >- Why it is not applied: `ACCOUNT_CLOSED`, `OUTCOME_UNKNOWN`, or another refusal code example: null errorMessage: type: string example: null requestedBy: type: string description: '`api-key`, or the staff email for a portal user' example: api-key createdAt: type: string example: '2026-10-30T11:02:11.000Z' appliedAt: type: string example: '2026-10-30T11:02:11.412Z' replayed: type: boolean example: false code: type: string example: INSUFFICIENT_PERMISSIONS enum: - INSUFFICIENT_PERMISSIONS Model1356: type: string example: REFERENCE_CONFLICT enum: - REFERENCE_CONFLICT - ACCOUNT_CLOSED adjustment: type: object description: 'With ACCOUNT_CLOSED on a recorded adjustment: its current state' properties: adjustmentId: type: string example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d x-format: guid: true reference: type: string example: DEP-2026-104233 accountId: type: string example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 x-format: guid: true accountNumber: type: string example: ACC-50K-000123 type: $ref: '#/components/schemas/Model1357' amount: type: number description: 'Signed: positive for a credit, negative for a debit' example: 500 status: $ref: '#/components/schemas/Model1358' reason: type: string example: Deposit via card metadata: $ref: '#/components/schemas/Model759' countTowardDailyPnl: type: boolean example: false moveHighWaterMark: type: boolean example: false balanceBefore: type: number description: The live balance just before the adjustment (null until applied) example: 50000 balanceAfter: type: number description: The live balance just after the adjustment (null until applied) example: 50500 errorCode: type: string description: >- Why it is not applied: `ACCOUNT_CLOSED`, `OUTCOME_UNKNOWN`, or another refusal code example: null errorMessage: type: string example: null requestedBy: type: string description: '`api-key`, or the staff email for a portal user' example: api-key createdAt: type: string example: '2026-10-30T11:02:11.000Z' appliedAt: type: string example: '2026-10-30T11:02:11.412Z' Model1360: type: string example: INSUFFICIENT_BALANCE enum: - INSUFFICIENT_BALANCE Model1362: type: string example: OUTCOME_UNKNOWN enum: - OUTCOME_UNKNOWN - ADJUSTMENT_NOT_APPLIED - FEATURE_NOT_READY Model760: type: object properties: adjustmentId: type: string example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d x-format: guid: true reference: type: string example: DEP-2026-104233 accountId: type: string example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 x-format: guid: true accountNumber: type: string example: ACC-50K-000123 type: $ref: '#/components/schemas/Model757' amount: type: number description: 'Signed: positive for a credit, negative for a debit' example: 500 status: $ref: '#/components/schemas/Model758' reason: type: string example: Deposit via card metadata: $ref: '#/components/schemas/Model759' countTowardDailyPnl: type: boolean example: false moveHighWaterMark: type: boolean example: false balanceBefore: type: number description: The live balance just before the adjustment (null until applied) example: 50000 balanceAfter: type: number description: The live balance just after the adjustment (null until applied) example: 50500 errorCode: type: string description: >- Why it is not applied: `ACCOUNT_CLOSED`, `OUTCOME_UNKNOWN`, or another refusal code example: null errorMessage: type: string example: null requestedBy: type: string description: '`api-key`, or the staff email for a portal user' example: api-key createdAt: type: string example: '2026-10-30T11:02:11.000Z' appliedAt: type: string example: '2026-10-30T11:02:11.412Z' Model1347: type: string example: credit enum: - credit - debit Model1348: type: string description: >- `applied`: the balance changed. `pending`: not confirmed yet; send the same request again to settle it. `failed`: not applied (`errorCode`) example: applied enum: - applied - pending - failed Model759: type: object Model1351: type: string example: credit enum: - credit - debit Model1352: type: string description: >- `applied`: the balance changed. `pending`: not confirmed yet; send the same request again to settle it. `failed`: not applied (`errorCode`) example: applied enum: - applied - pending - failed Model1357: type: string example: credit enum: - credit - debit Model1358: type: string description: >- `applied`: the balance changed. `pending`: not confirmed yet; send the same request again to settle it. `failed`: not applied (`errorCode`) example: applied enum: - applied - pending - failed Model757: type: string example: credit enum: - credit - debit Model758: type: string description: >- `applied`: the balance changed. `pending`: not confirmed yet; send the same request again to settle it. `failed`: not applied (`errorCode`) example: applied enum: - applied - pending - failed 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 - [Balance adjustments](https://docs.hyperprop.com/guides/balance-adjustments.md) - [Reverse a balance credit](https://docs.hyperprop.com/platform-api/mass-credit/reverse-a-balance-credit.md) - [Reverse a mass credit](https://docs.hyperprop.com/platform-api/mass-credit/reverse-a-mass-credit.md) - [List an account's balance adjustments](https://docs.hyperprop.com/platform-api/trading-accounts/list-an-accounts-balance-adjustments.md) - [Confirm a mass credit](https://docs.hyperprop.com/platform-api/mass-credit/confirm-a-mass-credit.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.