Skip to main content
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

OperationAPI permissionOn-chain role
Minttokens:mintMINTER
Burntokens:burnBURNER
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

EventWhen
token.mint_requestedMint operation accepted by Qustody.
token.mintedOn-chain mint confirmed.
token.burn_requestedBurn operation accepted.
token.burnedOn-chain burn confirmed.
token.operation_rejectedApprover rejected the operation.
token.operation_failedOperation failed during signing or chain.

​
Common errors

ErrorCauseRetry safe?
TOKEN_NOT_DEPLOYEDToken has no contractAddress yet.After deploy completes
TOKEN_OPERATION_NOT_ALLOWEDStandard or template doesn’t support the action.No
TOKEN_SUPPLY_EXCEEDEDMint would exceed maxSupply.After reducing amount
TOKEN_MINT_NOT_ALLOWEDCaller lacks MINTER.After granting role
TOKEN_BURN_NOT_ALLOWEDCaller lacks BURNER.After granting role
TOKEN_INVALID_AMOUNTZero, negative, or above source balance.After fixing amount
POLICY_DENIEDApproval policy rejected the operation.No
IDEMPOTENCY_CONFLICTKey reused with a different body.No