Skip to main content

Burn Token By User

Burn (destroy) tokens owned by a specific user. This action permanently removes the tokens from circulation.

Non-custodial wallets only

This endpoint rejects the call with HTTP 500 (custodial wallet managed by system) when the integration is configured to manage the wallet on the user's behalf. For custodial deployments, use the admin-side Burn Token endpoint instead. The non-custodial flow requires the user to sign the burn transaction outside the integration.

The call is asynchronous — the handler enqueues a BurnToken blockchain transaction and returns HTTP 200 immediately. Supply only decreases on-chain (and via the user overlay) once the wallet pipeline confirms the transaction. Use the admin-side List Token Transactions endpoint to observe completion.

Endpoint​

POST /v2/users/tokens/{token_id}/users/{user_id}/burn

Headers​

HeaderValue
Content-Typeapplication/json
AuthorizationBearer {token}

Path Parameters​

ParameterTypeRequiredDescription
token_idstringYesThe unique identifier of the token to burn
user_idstringYesThe unique identifier of the user whose tokens will be burned

Request Body​

No request body. user_id and token_id are passed only via the path; the handler does not accept a quantity field — the on-chain consumer burns whatever supply the request resolves to.

Response​

Returns 200 OK with no content when the burn operation is successfully initiated. The burn is processed asynchronously.

Success Response (200 OK)​

No content - successful response.

Example​

Request​

curl -X POST "\{\{baseUrl\}\}/v2/users/tokens/68aeb272d9336c619ce249f6/users/680c02896d91ca0145cfeb81/burn" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}"

Response​

200 OK
(No content)

Error Responses​

400 Bad Request​

{
    "error": "Invalid parameters",
    "details": "user_id / token_id missing or malformed"
}

401 Unauthorized​

{
    "error": "Authentication required"
}

403 Forbidden​

{
    "error": "Access denied",
    "details": "Insufficient permissions to burn tokens"
}

404 Not Found​

{
    "error": "Resource not found",
    "details": "Token or user not found"
}

422 Unprocessable Entity​

{
    "error": "Insufficient token balance",
    "details": "User does not have enough tokens to burn"
}

500 Internal Server Error​

{
    "error": "Internal server error"
}

Important Notes​

  • Irreversible Action: Token burning is permanent and cannot be undone
  • Balance Check: The system will verify the user has sufficient token balance before burning
  • Transaction Recording: All burn operations are recorded on the blockchain
  • Permissions: Only authorized users can perform burn operations
  • Audit Trail: All burn operations are logged for audit purposes