> ## 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.

# Burn tokens

> Burn supply of a deployed QRC token through Qustody.

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

Reduce the supply of a deployed QRC token by burning from a vault-controlled balance or a permitted external holder.

| Aspect               | Detail                                                           |
| -------------------- | ---------------------------------------------------------------- |
| Method               | `POST`                                                           |
| Path                 | `/v1/tokens/{tokenId}/burn`                                      |
| Authentication       | Bearer API key                                                   |
| Required permissions | `tokens:burn` plus the on-chain `BURNER` role                    |
| Idempotency          | `Idempotency-Key` header **required**                            |
| Approval policy      | **Required** for any non-zero amount                             |
| Blockchain effect    | Contract call to `burn(uint256)` or `burnFrom(address,uint256)`  |
| Webhook events       | `token.burn_requested`, `token.burned`, `token.operation_failed` |

### Request body

```json theme={null}
{
  "amount": "500000000000000000000",
  "from": {
    "type": "vaultAccountId",
    "vaultAccountId": "vault_123"
  },
  "feeStrategy": "MEDIUM",
  "idempotencyKey": "burn-2026-04-27-001"
}
```

`from.type` accepts `address`, `walletId`, or `vaultAccountId`.

### Response (202)

```json theme={null}
{
  "operationId": "op_burn_456",
  "tokenId": "token_abc123",
  "operationType": "BURN",
  "status": "PENDING_AUTHORIZATION",
  "amount": "500000000000000000000",
  "transactionRequestId": "txreq_003",
  "createdAt": "2026-04-27T10:08:00Z"
}
```

### Errors

| Code | Type                          | Meaning                                                  |
| ---: | ----------------------------- | -------------------------------------------------------- |
| 1703 | `TOKEN_NOT_DEPLOYED`          | Token has no on-chain `contractAddress`.                 |
| 1704 | `TOKEN_OPERATION_NOT_ALLOWED` | Standard or template does not allow `burn`.              |
| 1707 | `TOKEN_BURN_NOT_ALLOWED`      | Caller lacks the on-chain `BURNER` role.                 |
| 1713 | `TOKEN_INVALID_AMOUNT`        | Amount is zero, negative, or exceeds the source balance. |
| 1200 | `POLICY_DENIED`               | Approval policy denied the operation.                    |
| 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

* [Mint tokens](/api-reference/tokens/mint-tokens)
* [Token operations](/api-reference/tokens/list-token-operations)
* [Guide — Mint and burn tokens](/guides/mint-and-burn-tokens)
* [Security model](/qustody/token-management/security-model)