---
title: "Create new transfer"
url: https://docs.truemarkets.co/api/gateway/create-transfer
description: "Creates a new on-chain transfer. Returns unsigned payloads for the client to sign before executing."
---

Docs index: https://docs.truemarkets.co/llms.txt

# Create new transfer

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](https://docs.truemarkets.co/developer-resources/rate-limits).

## Request

```
POST https://api.truemarkets.co/v1/gateway/transfers
```

### Authentication

Bearer token in `Authorization`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `TM-On-Behalf-Of` | header | string (uuid) | no | 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. |

### Body

`application/json`, required

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_id` | string (uuid) | yes | Asset identifier (UUID) |
| `qty` | string | yes | Transfer quantity as a positive decimal string |
| `qty_unit` | string, one of `base`, `quote` | yes | Unit of the quantity. * **base** — Quantity is denominated in the base asset. * **quote** — Quantity is denominated in the quote asset. |
| `to` | string | yes | Destination wallet address |
| `network` | string | no | 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`](https://docs.truemarkets.co/api/gateway/list-assets) (`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`. |

## Responses

Every error status returns the same body, described in [Errors](https://docs.truemarkets.co/developer-resources/errors.md).

### 201

Transfer created successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes | Unique transfer identifier |
| `status` | string, one of `awaiting_signature`, `pending`, `completed`, `failed` | yes | 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. |
| `venue` | string, one of `defi`, `cefi` | yes | The trading venue to filter by. * **defi** — Decentralized exchange (on-chain swaps). * **cefi** — Centralized exchange (off-chain order book). |
| `asset_id` | string (uuid) | yes | Asset identifier |
| `asset_symbol` | string | yes | Asset ticker symbol (e.g. `USDC`, `SOL`) |
| `chain` | string, nullable | yes | Blockchain network (e.g. `solana`, `base`) for DeFi transfers, or null for CeFi transfers |
| `network` | string, nullable | yes | 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 | yes | Destination wallet address |
| `qty` | string | yes | Transfer quantity as a decimal string |
| `qty_unit` | string, one of `base`, `quote` | yes | Unit of the quantity |
| `sent` | string | yes | Amount sent as a decimal string |
| `fee` | string | yes | Fee as a decimal string |
| `received` | string | yes | Amount received as a decimal string |
| `tx_hash` | string | yes | On-chain transaction hash |
| `explorer_url` | string, nullable | no | Public block-explorer page for `tx_hash`, null until the transfer is broadcast |
| `payloads` | array of object | yes | Unsigned transaction payloads for the client to sign. Present when status is `awaiting_signature`; empty array after execution. |
| `payloads[].digest` | string | yes | Lowercase hex SHA-256 of the `payload` bytes. A signing API that takes a pre-hashed input signs the hex-decoded digest; a library that hashes its input takes `payload` instead. Passing the hex digest to a library that hashes signs the wrong bytes. |
| `payloads[].payload` | string | yes | The exact text to sign: a Turnkey activity as JSON, including its trailing newline. Sign its UTF-8 bytes as-is with ECDSA P-256 and SHA-256; never decode, reformat or re-serialize it. |
| `created_at` | string (date-time) | yes | Timestamp when the transfer was created (RFC 3339) |
| `updated_at` | string (date-time) | yes | Timestamp of the last status update (RFC 3339) |

### 400

Bad request

### 401

Unauthorized

### 403

Forbidden. On order creation this also covers an asset that is not available to trade from the country the request came from.

### 404

Not found

### 409

Conflict

### 422

Request is well-formed but cannot be processed (e.g. leverage missing or out of range for a perp order)

### 500

Internal server error

### 503

Service unavailable
