For AI agents: the documentation index is at /llms.txt, and this page is available as Markdown at /api/gateway/create-paper-withdrawal.md.

Remove test funds (paper trading only)

Organization tokenNo token

POST
/paper/withdrawals

Paper-trading environments only. This endpoint is not served in production, where it answers 404.

Sends test funds of the DeFi listing asset_id out of the caller's paper wallet. Only the wallet's unallocated balance can leave it, so when the wallet cannot cover the request, allocated balance is first released from CeFi trading through POST /custody/releases, returned in release, and the request waits up to 20 seconds for it to free the funds.

With amount omitted, the wallet is emptied: everything the caller has allocated of the listing on CeFi is released first, then the whole wallet balance leaves. With amount given, CeFi is released from only when the wallet's unallocated balance falls short, and by at most amount. The CeFi release is capped at the caller's allocation of the listing; when omitting amount, any CeFi balance beyond that allocation stays on CeFi and is reported in cefi_unbacked.

When the release has not freed the funds within the wait, the request answers 409 with code release_settling and metadata.release_id; retry shortly. A wallet that still cannot cover the request with nothing left on CeFi answers 422 with code insufficient_balance or funds_allocated.

Rate limit: counts against the Money movement limit, 20 a minute and 300 a day (user token, per user); 200 a minute and 3,000 a day (organization api key, per organization). See Rate limits.

Authorization

bearerAuth
headerAuthorizationBearer <JWT>

An access token from POST /v1/auth/api-key/token. An organization token lasts one hour and has no refresh token; a personal token can be refreshed.

Header Parameters

TM-On-Behalf-Of?string

Act as one of your organization's users. The value is the user_id returned when the user was created; the request then reads and writes that user's account. Requires an organization token and a user your organization created: 400 for a personal token, a repeated header or a non-UUID, 403 for a user outside your organization. Not accepted on organization-scoped routes.

Formatuuid

Request Body

application/json
  1. body

Request to remove test funds from the caller's paper wallet

asset_id*string

DeFi listing identifier (UUID)

Formatuuid
amount?string

Amount to remove, as a positive decimal string; omit to empty the wallet

Response Body

Test funds removed from the wallet

application/json
  1. response

The test funds removed and the CeFi release that freed them, if any

asset_id*string

DeFi listing identifier (UUID)

Formatuuid
debited*string

Amount removed from the wallet, as a decimal string

wallet_balance*string

The paper wallet's balance of the listing after the funds were removed

release?

A release and the CeFi transfer it started.

cefi_unbacked?string

CeFi balance of the listing beyond the caller's allocation, which has no allocation behind it and so was left on CeFi, as a decimal string. Present only when positive.

Example Request
curl -X POST 'https://api.truemarkets.co/v1/gateway/paper/withdrawals' \  -H 'TM-On-Behalf-Of: 3f6d2c0e-8a41-4c2b-9f1e-2b7d5c0a9e11' \  -H 'Content-Type: application/json' \  -d '{  "asset_id": "b3d9e5f2-1a4c-4e7b-9f0d-2c8a6b3e5f91"}'
Example Response
{  "asset_id": "b3d9e5f2-1a4c-4e7b-9f0d-2c8a6b3e5f91",  "debited": "250",  "wallet_balance": "750",  "release": {    "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",    "status": "debiting",    "asset_id": "b3d9e5f2-1a4c-4e7b-9f0d-2c8a6b3e5f91",    "asset_symbol": "USDC",    "amount": "100.00",    "transfer": {      "id": "a7f3c2e1-9b4d-4e6f-8a1c-3d5e7f9b2c4a",      "status": "COMPLETED"    },    "failure_reason": "cefi REJECTED",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "cefi_unbacked": "1.877"}