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

# Balance adjustments

> Credit or debit one trading account by an amount, with your own reference, safely and exactly once.

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.

> [!NOTE]
>
> 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

```bash theme={null}
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`:

```json theme={null}
{
  "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](https://docs.hyperprop.com/concepts/idempotency) 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`):

```bash theme={null}
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:

```bash theme={null}
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):

```json theme={null}
{
  "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"
  }
}
```

> [!WARNING]
>
> `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**.


## Related topics

- [List an account's balance adjustments](https://docs.hyperprop.com/platform-api/trading-accounts/list-an-accounts-balance-adjustments.md)
- [Get a balance adjustment by reference](https://docs.hyperprop.com/platform-api/trading-accounts/get-a-balance-adjustment-by-reference.md)
- [Retry a balance adjustment batch](https://docs.hyperprop.com/platform-api/mass-credit/retry-a-balance-adjustment-batch.md)
- [Get a balance adjustment batch](https://docs.hyperprop.com/platform-api/mass-credit/get-a-balance-adjustment-batch.md)
- [List balance adjustment batches](https://docs.hyperprop.com/platform-api/mass-credit/list-balance-adjustment-batches.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.