Skip to main content

​
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.
AspectDetail
MethodPOST
Path/v1/tokens/{tokenId}/burn
AuthenticationBearer API key
Required permissionstokens:burn plus the on-chain BURNER role
IdempotencyIdempotency-Key header required
Approval policyRequired for any non-zero amount
Blockchain effectContract call to burn(uint256) or burnFrom(address,uint256)
Webhook eventstoken.burn_requested, token.burned, token.operation_failed

​
Request body

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

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

​
Errors

CodeTypeMeaning
1703TOKEN_NOT_DEPLOYEDToken has no on-chain contractAddress.
1704TOKEN_OPERATION_NOT_ALLOWEDStandard or template does not allow burn.
1707TOKEN_BURN_NOT_ALLOWEDCaller lacks the on-chain BURNER role.
1713TOKEN_INVALID_AMOUNTAmount is zero, negative, or exceeds the source balance.
1200POLICY_DENIEDApproval policy denied the operation.
1201APPROVAL_REQUIREDApproval is required and was not yet granted.
1601IDEMPOTENCY_CONFLICTSame Idempotency-Key reused with different body.

​
Retry safety

Retries with the same Idempotency-Key are safe and return the original operation.