Move cash or securities from one account to another. The caller's token must carry grants covering both source_account_id and target_account_id.
Set type to cash and supply currency + amount for a cash movement, or set type to securities and supply instrument + positions for a securities movement.
positions names the buckets to move, one entry per bucket. A bucket you leave out of the array is not moved. Send at most one entry per position_type.
A securities transfer moves each bucket independently and preserves it: the quantity drawn from the source account's long bucket lands in the target account's long bucket, and likewise for the net and short buckets.
The bucket names (net, long, short) are labels, not directional assertions — each quantity is signed, and a bucket may hold either sign regardless of its name.
A securities transfer whose every quantity is "0" moves nothing. It is refused with 400 and type invalid-quantity. Nothing is recorded.
An empty positions array fails schema validation, because the array declares minItems: 1. That returns 400 with type validation-error, not invalid-quantity.
A repeated position_type is refused with 400 and type duplicate-position-type. The service does not merge repeated entries and does not let the last one win, because either rule could move a quantity the caller did not intend.
The response carries all three buckets whatever the request named. A bucket the request left out comes back with quantity "0".
The service checks six conditions before it records anything: source and target being the same account, a securities transfer that moves nothing, a repeated position_type, an unresolvable instrument, a restricted account, and insufficient quantity in the source account. Each one returns a 4xx response. Nothing is recorded.
A 201 means the instruction passed every local check. It does not mean the movement happened. Booking runs after the response, and it can still end without a movement: terminal rejected if the downstream service declines the instruction, terminal failed if it takes the instruction on and errors. Both carry a status_reason, and after both the position is unchanged. Read the terminal outcome by polling.
A 5xx means the transfer may or may not have been recorded. It never means a movement partly happened, because nothing is booked inside the create call. The client must retry with the same reference_id. A new reference_id after a 5xx risks moving the position twice.
reference_id is a client-supplied idempotency key. A duplicate request with the same reference_id and the same payload returns the original transfer. It does not create a new one.
A replay also returns 201, not a separate status code. It carries the transfer in its current status, not the status it had when it was created, so a replay can return a terminal transfer.
Reuse of a reference_id with a different payload returns 409 with type reference-id-conflict. That is a malformed request, not a business refusal. The new instruction is never applied.
A reference_id is bound only by a 201. A request that returns 4xx records nothing and leaves the key free, so a corrected payload may reuse it. The 409 therefore applies only after a transfer was recorded under that key.
Keys never expire. An expiry window would let a replayed instruction move a position twice after the window closed.
A reference_id is unique within the calling tenant, not globally. Two applications in one tenant share the same namespace.
Use a UUID rather than a counter. A per-day counter collides with the client's own earlier keys when the counter repeats.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||