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

Create new transfer

Organization tokenNo token

POST
/transfers

Creates a new on-chain transfer. Returns unsigned payloads for the client to sign before executing.

For CeFi transfers, network is required — retrieve the supported values from GET /assets (see the network field below). Omit it for DeFi transfers, which derive the network from the asset's chain. A CeFi asset held in the wallet is sent from the wallet.

A transfer can spend funds committed to CeFi trading; they are freed before the payloads are returned. If they can't be, the request fails with 422 funds_allocated (held by open CeFi orders) or 409 release_settling (retry shortly).

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 create a new on-chain transfer

asset_id*string

Asset identifier (UUID)

Formatuuid
qty*string

Transfer quantity as a positive decimal string

qty_unit*string

Unit of the quantity.

  • base — Quantity is denominated in the base asset.
  • quote — Quantity is denominated in the quote asset.
Value in"base""quote"
to*string

Destination wallet address

network?string

Destination network for the withdrawal. Required for CeFi transfers and must be omitted for DeFi transfers (DeFi derives the network from the asset's chain).

The set of supported networks is asset-specific and is retrieved from the listAssets (GET /assets) response: for the asset whose id equals this request's asset_id, network must match one of that asset's networks[].network values or any of their networks[].compatible_networks values. Matching is case-insensitive. Supplying an unsupported network returns 400 Bad Request.

Response Body

Transfer created successfully

application/json
  1. response

Canonical representation of a transfer.

id*string

Unique transfer identifier

Formatuuid
status*TransferStatus

The current status of the transfer.

  • awaiting_signature — Transfer has been created and is waiting for the client to sign the unsigned payloads and call the execute endpoint.
  • pending — Signed transaction has been submitted and is awaiting on-chain confirmation.
  • completed — Transfer has been confirmed on-chain.
  • failed — Transfer failed due to an on-chain error or rejection.
Value in"awaiting_signature""pending""completed""failed"
venue*Venue

The trading venue to filter by.

  • defi — Decentralized exchange (on-chain swaps).
  • cefi — Centralized exchange (off-chain order book).
Value in"defi""cefi"
asset_id*string

Asset identifier

Formatuuid
asset_symbol*string

Asset ticker symbol (e.g. USDC, SOL)

chain*|

Blockchain network (e.g. solana, base) for DeFi transfers, or null for CeFi transfers

network*|

Destination network the CeFi withdrawal was submitted on (one of the asset's supported networks from GET /assets), or null for DeFi transfers.

to*string

Destination wallet address

qty*string

Transfer quantity as a decimal string

qty_unit*string

Unit of the quantity

Value in"base""quote"
sent*string

Amount sent as a decimal string

fee*string

Fee as a decimal string

received*string

Amount received as a decimal string

tx_hash*string

On-chain transaction hash

explorer_url?|

Public block-explorer page for tx_hash, null until the transfer is broadcast

payloads*array<>

Unsigned transaction payloads for the client to sign. Present when status is awaiting_signature; empty array after execution.

created_at*string

Timestamp when the transfer was created (RFC 3339)

Formatdate-time
updated_at*string

Timestamp of the last status update (RFC 3339)

Formatdate-time
Example Request
curl -X POST 'https://api.truemarkets.co/v1/gateway/transfers' \  -H 'TM-On-Behalf-Of: 3f6d2c0e-8a41-4c2b-9f1e-2b7d5c0a9e11' \  -H 'Content-Type: application/json' \  -d '{  "asset_id": "b3d9e5f2-1a4c-4e7b-9f0d-2c8a6b3e5f91",  "qty": "100.00",  "qty_unit": "base",  "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "pending",  "venue": "defi",  "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",  "asset_symbol": "string",  "chain": "string",  "network": "bitcoin",  "to": "string",  "qty": "string",  "qty_unit": "base",  "sent": "string",  "fee": "string",  "received": "string",  "tx_hash": "string",  "explorer_url": "string",  "payloads": [    {      "digest": "string",      "payload": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}