Mint and burn tokens

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).
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 attached to the token.

Mint flow

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

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

Integration

Operations

Tokens

Mint and burn tokens

Prerequisites

Mint flow

Burn flow

Required permissions

Approval policy

Idempotency

Webhooks

Common errors

​Prerequisites

​Mint flow

​Burn flow

​Required permissions

​Approval policy

​Idempotency

​Webhooks

​Common errors

​Related

Prerequisites

Mint flow

Burn flow

Required permissions

Approval policy

Idempotency

Webhooks

Common errors

Related