Balance adjustments

Use a balance adjustment when money moves on your side (a deposit, a withdrawal, a correction) and the trading account should follow. You send a signed amount and your own reference; Hyperprop changes the account’s live balance by that amount and records it under your reference.

A balance adjustment changes the balance by an amount. It never sets the balance to a value, so it cannot overwrite profit or loss the trader makes at the same moment. Use it instead of setting currentBalance with PATCH /organization/trading-accounts/{accountId} whenever the account may be trading.

Credit or debit an account

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" }
  }'

Field	Required	Description
`amount`	Yes	Signed JSON number with at most 2 decimals. Positive credits the account, negative debits it. Not zero; at most 10,000,000 either way.
`reference`	Yes	Your ID for this adjustment, 1 to 128 characters: letters, digits and `. _ : @ + = ~ -`, starting with a letter or digit. Unique within your organization, case-sensitive.
`reason`	No	Up to 500 characters. Shown in the account activity, the audit log and the webhook.
`metadata`	No	Up to 20 keys of your own (strings, numbers, booleans or null), returned as sent.
`countTowardDailyPnl`	No	Default `false`: the adjustment is not counted as the day’s profit or loss, and the daily loss limit stays where it was. `true`: it counts toward the day’s P&L.
`moveHighWaterMark`	No	Default `false`: the high-water mark (trailing drawdown peak) stays where it is. `true`: it moves by the amount as well.

A new adjustment returns 201 Created:

{
  "success": true,
  "data": {
    "adjustmentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "reference": "DEP-2026-104233",
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "accountNumber": "ACC-50K-000123",
    "type": "credit",
    "amount": 500,
    "status": "applied",
    "reason": "Deposit via card",
    "metadata": { "crmTransactionId": "TX-88213" },
    "countTowardDailyPnl": false,
    "moveHighWaterMark": false,
    "balanceBefore": 50000,
    "balanceAfter": 50500,
    "errorCode": null,
    "errorMessage": null,
    "requestedBy": "api-key",
    "createdAt": "2026-10-30T11:02:11.000Z",
    "appliedAt": "2026-10-30T11:02:11.412Z",
    "replayed": false
  }
}

balanceBefore and balanceAfter are the live balance just before and just after the change. To debit, send a negative amount, for example "amount": -250.

Retry safely with your reference

Your reference is the idempotency key, and it never expires.

Same reference, same request: you get the original adjustment back with 200 and "replayed": true. Nothing changes.
Same reference, different request (another account, amount, reason, metadata or option): refused with 409 REFERENCE_CONFLICT. Use a new reference for a new adjustment.

So when a call times out or your process restarts, send the same request again. It is applied once at most. The Idempotency-Key header is accepted too, as on every write, but you do not need it here.

Which accounts can be adjusted

Account	Result
Not started, in progress, turned off	Adjusted
Passed, failed or expired	`409 ACCOUNT_CLOSED`, the balance does not change
Not in your organization	`404 ACCOUNT_NOT_FOUND`, nothing recorded

Debits and the account’s rules

A debit that would take the balance below zero is refused with 422 INSUFFICIENT_BALANCE. Nothing is recorded, so you can reuse the reference.
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 and you receive account.failed. Check the account with GET /organization/trading-accounts/{accountId} first when that matters.

Errors

Status	Code	Meaning	What to do
`400`	`VALIDATION_ERROR`	Invalid amount, reference, reason or metadata	Fix the request
`404`	`ACCOUNT_NOT_FOUND`	The account is not in your organization	Check the account ID
`409`	`REFERENCE_CONFLICT`	The reference was used for a different adjustment	Use a new reference
`409`	`ACCOUNT_CLOSED`	The account is passed, failed or expired	Do not adjust it
`422`	`INSUFFICIENT_BALANCE`	The debit would take the balance below zero	Debit less
`503`	`OUTCOME_UNKNOWN`	The change could not be confirmed in time; status `pending`	Send the same request again
`503`	`ADJUSTMENT_NOT_APPLIED`	The change was not applied; status `failed`	Send the same request again

The two 503 answers include the adjustment in an adjustment field. Sending the same request again settles it; it is never applied twice.

Reconcile

List an account’s adjustments, newest first (filter by status, paginate with limit and offset):

curl "https://api.hyperprop.com/platform/v1/organization/trading-accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/balance-adjustments?limit=20" \
  -H "X-API-Key: hp_live_your_key_here"

Or look one up by your reference, for example after a response you did not receive:

curl "https://api.hyperprop.com/platform/v1/organization/trading-accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/balance-adjustments/DEP-2026-104233" \
  -H "X-API-Key: hp_live_your_key_here"

Webhooks

Subscribe an endpoint to account.balance_adjusted to receive one event per adjustment (never for a replay):

{
  "id": "evt_9c1e...",
  "type": "account.balance_adjusted",
  "createdAt": "2026-10-30T11:02:11.512Z",
  "organizationId": "a6fcc0ce-...",
  "trigger": "balance_adjustment",
  "data": { "id": "7c9e6679-...", "accountNumber": "ACC-50K-000123", "currentBalance": 50500, "...": "..." },
  "previousAttributes": { "currentBalance": 50000 },
  "balanceAdjustment": {
    "adjustmentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "reference": "DEP-2026-104233",
    "type": "credit",
    "amount": 500,
    "reason": "Deposit via card",
    "metadata": { "crmTransactionId": "TX-88213" },
    "balanceBefore": 50000,
    "balanceAfter": 50500,
    "countTowardDailyPnl": false,
    "moveHighWaterMark": false,
    "appliedAt": "2026-10-30T11:02:11.412Z"
  }
}

account.balance_adjusted is delivered only to endpoints that list it explicitly. A "*" subscription does not include it.

Every adjustment also produces account.updated (with trigger balance_adjustment) and, for its subscribers, account.balance_changed with reason adjustment.

Permissions

Creating an adjustment needs manage permission on Traders & accounts, the same as editing an account’s balance. Listing and reading need view.

Get Started

Core Concepts

Guides

Custom indicators

Hyperprop Deep Liquidity (HDL)

Credit or debit an account

Retry safely with your reference

Which accounts can be adjusted

Debits and the account’s rules

Errors

Reconcile

Webhooks

Permissions

​Credit or debit an account

​Retry safely with your reference

​Which accounts can be adjusted

​Debits and the account’s rules

​Errors

​Reconcile

​Webhooks

​Permissions

Credit or debit an account

Retry safely with your reference

Which accounts can be adjusted

Debits and the account’s rules

Errors

Reconcile

Webhooks

Permissions