Transfer tokens

`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

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

Response (202)

{
  "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.

Create transaction (the underlying generic flow)
Compliance and allowlist
Security model

Burn tokens Manage token roles

Overview

Health

Tenants

Vaults

Wallets

Transactions

Assets

Tokens

Webhooks

Administration

Transfer tokens

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

Request body

Response (202)

Errors

Retry safety

​POST /v1/tokens/{tokenId}/transfers

​Request body

​Response (202)

​Errors

​Retry safety

​Related

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

Request body

Response (202)

Errors

Retry safety

Related