/api/partner/ routes.
1
Record the operation
Create a balance operation names the
account, the direction, a positive amount, and your own The move lands on the account immediately and the trader’s dashboard repaints live. The
response is small on purpose:
referenceId.recorded, the op, and the amount.2
Let the referenceId do the safety work
The operation is written to the balance ledger first, keyed on your
referenceId. A
duplicate reference answers 409 and moves nothing — so a retried pipeline can never pay out
twice, and a 409 on a payout retry is the correct, boring outcome rather than an incident.The reference is at most 80 characters. Key it on the thing your business actually means: the
payout run and the account, not a timestamp that changes on retry.3
See it in the balance
List issued accounts shows the effect. The
balance field is the live figure — the starting balance plus realized trading P&L plus every
balance operation you have recorded — while startingBalance does not move.4
Follow it on your own server
Every recorded operation fires a
balance.recorded event to your registered endpoints, with
the account number, the op, the amount, and your referenceId in the payload — which is also
the natural key for a handler that must tolerate a retried delivery.The three ops
amount is always positive. The op carries the direction — there are no negative amounts to get
the sign wrong on.
amount is in account currency and at most 10000000. A missing field, a non-positive amount, or
an unknown op is a 400.
When a firm records one
- A payout. The trader earned a profit share and you are moving it off the platform account. A
debit, keyed on the payout run. - A promotional credit. A bonus balance, a goodwill top-up after an outage, a reward. A
credit. - A correction. Something landed wrong and the books need to agree. An
adjustment, with thecommentcarrying why.
resetAt on the account. Reaching for a balance operation to fake a
reset leaves the trader’s open risk in place.
What lands in the audit trail
The ledger row is permanent and auditable on both sides — your records and ours describe the same event, because both were written from the same call. Each row carries yourreferenceId and, when
you sent one, the comment (at most 300 characters). Write something a colleague will understand
in six months; it is the only free text on the row.
Two other things write to the same ledger, so a firm’s account history reads as one sequence: a
provision row when the account is issued, and a row for every
reset.
The refusals
Where to go deeper
- Issue evaluation accounts — where
startingBalanceand reset come from. - Receive events — wiring
balance.recordedinto your back office. - Read your usage — the other number your finance team reconciles.
- Prop firms — the whole firm surface in one page.