Burn Token By User

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

Endpoint

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

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
token_id	string	Yes	The unique identifier of the token to burn
user_id	string	Yes	The unique identifier of the user whose tokens will be burned

Request Body

{
    "quantity": "number",
    "reason": "string"
}

Parameters

Parameter	Type	Required	Description
quantity	number	No	Number of tokens to burn. If not specified, all user tokens will be burned
reason	string	No	Reason for burning the tokens

Response

Returns confirmation of the burn operation.

Success Response (200 OK)

{
    "success": true,
    "message": "Tokens burned successfully",
    "data": {
        "token_id": "string",
        "user_id": "string",
        "burned_quantity": "number",
        "remaining_quantity": "number",
        "transaction_hash": "string",
        "burned_at": "string"
    }
}

Example

Request

curl -X POST "\{\{baseUrl\}\}/v2/users/tokens/68aeb272d9336c619ce249f6/users/680c02896d91ca0145cfeb81/burn" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}" \
  -d '{
    "quantity": 10,
    "reason": "User requested token burn"
  }'

Response

{
    "success": true,
    "message": "Tokens burned successfully",
    "data": {
        "token_id": "68aeb272d9336c619ce249f6",
        "user_id": "680c02896d91ca0145cfeb81",
        "burned_quantity": 10,
        "remaining_quantity": 40,
        "transaction_hash": "0x1234567890abcdef1234567890abcdef12345678",
        "burned_at": "2024-01-15T14:30:00Z"
    }
}

Error Responses

400 Bad Request

{
    "error": "Invalid parameters",
    "details": "Quantity must be greater than 0"
}

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