Create internal transfer

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum
required

Discriminates the transfer leg. Set to cash when supplying currency + amount; set to securities when supplying instrument + positions.

Allowed:
string
required
length between 1 and 256

Account ID for the account.

string
required
length between 1 and 256

Account ID for the account.

string
required
length between 1 and 256

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. Reuse with a different payload returns 409 with type reference-id-conflict.

The key is bound only by a 201. A request that returns 4xx records nothing and leaves the key free for a corrected payload.

metadata
object

Caller-defined key/value pairs, echoed back unchanged. At most 10 entries; keys 40 characters or fewer, values 500 characters or fewer.

string
required
^[A-Z]{3}$

ISO 4217 alphabetic currency code, in upper case.

string
required
length between 1 and 32

String representation of a cash amount.

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Choose an example:
application/json
application/problem+json