> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer tokens

> Transfer QRC tokens between vault accounts, registered wallets, or external addresses.

## `POST /v1/tokens/{tokenId}/transfers`

Move supply of a deployed QRC token between participants. The endpoint resolves recipients and senders, applies token-specific compliance checks (allowlist, frozen-account checks, paused-state checks), and routes the transaction through the standard approval and signing flow.

| Aspect               | Detail                                                                                             |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| Method               | `POST`                                                                                             |
| Path                 | `/v1/tokens/{tokenId}/transfers`                                                                   |
| Authentication       | Bearer API key                                                                                     |
| Required permissions | `tokens:transfer`                                                                                  |
| Idempotency          | `Idempotency-Key` header **required**                                                              |
| Approval policy      | Subject to vault and token-level policy                                                            |
| Blockchain effect    | Contract call to `transfer(address,uint256)` (or template-equivalent)                              |
| Webhook events       | `transaction.created`, `transaction.status_changed`, `transaction.completed`, `transaction.failed` |

### Request body

```json theme={null}
{
  "from": { "type": "vaultAccountId", "vaultAccountId": "vault_123" },
  "to": { "type": "address", "address": "0x9a8e5e21f0c27d2c5c14b6e9bd8e4a0f9c9b4d12" },
  "amount": "100000000000000000000",
  "feeStrategy": "MEDIUM",
  "idempotencyKey": "transfer-2026-04-27-001"
}
```

### Response (202)

```json theme={null}
{
  "operationId": "op_transfer_789",
  "tokenId": "token_abc123",
  "operationType": "TRANSFER",
  "status": "PENDING_AUTHORIZATION",
  "amount": "100000000000000000000",
  "transactionRequestId": "txreq_004",
  "createdAt": "2026-04-27T10:11:00Z"
}
```

### Errors

| Code | Type                                  | Meaning                                                  |
| ---: | ------------------------------------- | -------------------------------------------------------- |
| 1703 | `TOKEN_NOT_DEPLOYED`                  | Token has no on-chain `contractAddress`.                 |
| 1712 | `TOKEN_INVALID_RECIPIENT`             | Recipient resolution failed.                             |
| 1713 | `TOKEN_INVALID_AMOUNT`                | Amount is zero or exceeds the sender's balance.          |
| 1714 | `TOKEN_COMPLIANCE_RESTRICTION_FAILED` | Allowlist, freeze, or pause check rejected the transfer. |
| 1200 | `POLICY_DENIED`                       | Approval policy denied the transfer.                     |
| 1201 | `APPROVAL_REQUIRED`                   | Approval is required and was not yet granted.            |
| 1601 | `IDEMPOTENCY_CONFLICT`                | Same `Idempotency-Key` reused with different body.       |

### Retry safety

Retries with the same `Idempotency-Key` are safe and return the original operation.

## Related

* [Create transaction](/api-reference/endpoint/create-transaction) (the underlying generic flow)
* [Compliance and allowlist](/api-reference/tokens/compliance-and-allowlist)
* [Security model](/qustody/token-management/security-model)