Sandbox funding

Sandbox only. Not part of the production API. In production, and anywhere they are not enabled, sandbox_deposit and sandbox_withdraw answer error MALFORMED with the message unsupported type "sandbox_deposit" (or "sandbox_withdraw"). Never build them into a production flow.

sandbox_deposit moves USD from Securitize into your own cash, and sandbox_withdraw moves it out, so you can fund yourself and test the cash flow end to end.

Request

Both are signed like place_order and need a key registered for trading; a read-only key answers NOT_PERMITTED. Both take the same payload:

Field	Meaning
`amount`	USD, greater than zero, at most 2 decimal places
`clientRef`	Your own id for the request, up to 64 letters, digits, `.`, `_`, `:` or `-`. The same `clientRef` never moves money twice, and the same `clientRef` with another amount is refused

sandbox_deposit

Moves USD from Securitize into your own cash.

{
  "type": "sandbox_deposit",
  "requestId": "4e8b2d7f1a6c4f93b0d5e2a7c9f1b386",
  "timestamp": 1792998000,
  "payload": { "amount": "1000.00", "clientRef": "fund-2026-10-26-0001" },
  "signature": "5Hd8…"
}

sandbox_withdraw

Moves USD out of your own cash. It can take at most your available (see get_cash_balance_v2): the amount is held at once and counts in committed until it is booked, so it cannot be spent on a buy meanwhile.

{
  "type": "sandbox_withdraw",
  "requestId": "9a1c5e3b7d2f4a68b0c4e6d8f2a1b357",
  "timestamp": 1792998060,
  "payload": { "amount": "250.00", "clientRef": "withdraw-2026-10-26-0001" },
  "signature": "3kPq…"
}

A withdrawal for more than your available answers NOT_PERMITTED, and nothing is held.

The ack

The ack carries clientRef, amount, currency (USD) and a status:

`status`	Meaning	What to do
`PENDING`	Requested. It is booked about a minute later	Wait for the `cash_movement` push
`ALREADY_REQUESTED`	This `clientRef` was asked for before; nothing new was sent	Nothing. Read `get_cash_movements` to see where it stands
`CANCELLED`	It was cancelled before it was booked; nothing moved	Ask again with a new `clientRef`
`UNKNOWN`	No answer in time; it may have been requested	Ask again with the same `clientRef`, which never moves money twice

Once booked, the movement is pushed as cash_movement, a DEPOSIT or a WITHDRAW, and get_cash_balance_v2 and get_cash_movements show it.

Errors

A refusal answers error:

`code`	Meaning	What to do
`NOT_PERMITTED`	Refused, with the reason in `message`: not enough `available` for a withdrawal, the `clientRef` already used for another amount, a request with that `clientRef` still being processed or just sent, the transfer refused, or not available in this environment. Also a read-only key	For a request still being processed, ask again in a couple of minutes. Otherwise fix the amount or use a new `clientRef`
`UPSTREAM_UNAVAILABLE`	It was not confirmed. A withdrawal’s cash stays held meanwhile	Ask again with the same `clientRef`
`MALFORMED`	A bad payload, or not sandbox (`unsupported type`)	Fix the payload. In production there is nothing to fix: these messages do not exist there

Signature and timestamp errors are those of any signed message. See Signing. What each figure of your cash means is in Cash.

Get started

Sandbox only

Guides

Concepts

Help

API reference

Request

sandbox_deposit

sandbox_withdraw

The ack

Errors