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

# Mint and burn tokens

> Increase or decrease supply on a deployed QRC token through Qustody.

Mint adds new supply; burn removes it. Both are privileged operations that flow through approval, post-quantum signing, broadcast, and audit.

## Prerequisites

* A `DEPLOYED` token (see [Create a QRC-20 token](/guides/create-a-qrc-20-token)).
* An API key with `tokens:mint` and `tokens:burn`.
* The on-chain `MINTER` and/or `BURNER` role granted to the vault account performing the operation.
* An [approval policy](/concepts/policies) attached to the token.

## Mint flow

```http theme={null}
POST /v1/tokens/token_abc123/mint
Idempotency-Key: mint-2026-04-27-001

{
  "amount": "1000000000000000000000",
  "recipient": { "type": "address", "address": "0x9a8e5e21f0c27d2c5c14b6e9bd8e4a0f9c9b4d12" },
  "feeStrategy": "MEDIUM"
}
```

After approval, watch for the `token.minted` webhook, which carries the on-chain `transactionHash`.

## Burn flow

```http theme={null}
POST /v1/tokens/token_abc123/burn
Idempotency-Key: burn-2026-04-27-001

{
  "amount": "500000000000000000000",
  "from": { "type": "vaultAccountId", "vaultAccountId": "vault_123" },
  "feeStrategy": "MEDIUM"
}
```

After approval, watch for `token.burned`.

## Required permissions

| Operation | API permission | On-chain role |
| --------- | -------------- | ------------- |
| Mint      | `tokens:mint`  | `MINTER`      |
| Burn      | `tokens:burn`  | `BURNER`      |

If the on-chain role is missing, you receive `TOKEN_MINT_NOT_ALLOWED` (1706) or `TOKEN_BURN_NOT_ALLOWED` (1707).

## Approval policy

Configure stringent rules for supply changes:

* `REQUIRE_APPROVAL` with multi-approver quorum.
* `MAX_AMOUNT` per single mint or burn.
* `DAILY_LIMIT` aggregated per token.
* `TIME_WINDOW` to prevent off-hours operations.

## Idempotency

`Idempotency-Key` is **required** on every mint and burn request. Reuse the same key on retry; never vary the key for the same logical request.

## Webhooks

| Event                      | When                                      |
| -------------------------- | ----------------------------------------- |
| `token.mint_requested`     | Mint operation accepted by Qustody.       |
| `token.minted`             | On-chain mint confirmed.                  |
| `token.burn_requested`     | Burn operation accepted.                  |
| `token.burned`             | On-chain burn confirmed.                  |
| `token.operation_rejected` | Approver rejected the operation.          |
| `token.operation_failed`   | Operation failed during signing or chain. |

## Common errors

| Error                         | Cause                                            | Retry safe?            |
| ----------------------------- | ------------------------------------------------ | ---------------------- |
| `TOKEN_NOT_DEPLOYED`          | Token has no `contractAddress` yet.              | After deploy completes |
| `TOKEN_OPERATION_NOT_ALLOWED` | Standard or template doesn't support the action. | No                     |
| `TOKEN_SUPPLY_EXCEEDED`       | Mint would exceed `maxSupply`.                   | After reducing amount  |
| `TOKEN_MINT_NOT_ALLOWED`      | Caller lacks `MINTER`.                           | After granting role    |
| `TOKEN_BURN_NOT_ALLOWED`      | Caller lacks `BURNER`.                           | After granting role    |
| `TOKEN_INVALID_AMOUNT`        | Zero, negative, or above source balance.         | After fixing amount    |
| `POLICY_DENIED`               | Approval policy rejected the operation.          | No                     |
| `IDEMPOTENCY_CONFLICT`        | Key reused with a different body.                | No                     |

## Related

* [Mint endpoint](/api-reference/tokens/mint-tokens)
* [Burn endpoint](/api-reference/tokens/burn-tokens)
* [Token security model](/qustody/token-management/security-model)
* [Approval policies](/concepts/policies)