> ## Documentation Index > Fetch the complete documentation index at: https://docs.believe.app/llms.txt > Use this file to discover all available pages before exploring further. # Burn Tokens (Deprecated) > This endpoint allows burning tokens based on a provided proof, with an option to persist proof data on-chain. **Deprecated**: This endpoint is deprecated in favor of the new [Flywheel API](/api-reference/getting-started). The Flywheel API provides enhanced security, batch operations, multi-signature approval, and more sophisticated tokenomic strategies. Please migrate to the Flywheel API for new implementations. ## Overview The Burn Tokens endpoint facilitates the burning of a specified amount of tokens. It requires a proof of an off-chain event or condition that justifies the burn. If `persistOnchain` is true, the hash of the proof will be recorded on the blockchain. **NOTE**: This endpoint only works for /v1 tokens. ## Authentication This endpoint requires API key authentication. The API key must have the `burn` scope. To authenticate, provide your API key in the `x-believe-api-key` request header. Example: `x-believe-api-key: your_actual_api_key_here` ## Rate Limiting Requests to this endpoint are rate-limited to 10 requests per second per API key. ## Idempotency To prevent accidental duplicate operations, this endpoint supports idempotency via the `x-idempotency-key` header. * **Header**: `x-idempotency-key` * **Value**: A unique string (e.g., a UUID) generated by the client for each distinct operation. * **Purpose**: If a request is retried (e.g., due to a network error) with the same `x-idempotency-key` as a previously successful request, the server should recognize it and not perform the operation a second time, instead returning the result of the original successful operation. This ensures that operations are processed at most once. Example: `x-idempotency-key: your_unique_generated_uuid_v4_here` ## Request Body | Field | Type | Required | Description | | ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------- | | `type` | string | Yes | A string identifier for the type of proof being submitted (e.g., "PRODUCT\_BUY", "PRODUCT\_SELL"). | | `proof` | Object | Yes | A JSON object containing the actual proof data. Its structure will depend on the `type`. | | `burnAmount` | number | Yes | The quantity of tokens to burn. Must be a positive number. | | `persistOnchain` | boolean | Yes | A boolean flag indicating whether the hash of the `proof` should be recorded on the blockchain. | ### Example Request ```json theme={null} { "type": "PRODUCT_BUY", "proof": { "transactionId": "237892372", "value": "100" }, "burnAmount": 10000, "persistOnchain": true } ``` ## Response Body On success, the API returns a JSON object with the following fields: | Field | Type | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `result` | string | Indicates the outcome of the operation (e.g., "SUCCESS"). | | `hash` | string | A SHA256 hash of the provided `proof` object. | | `txHash` | string | The on-chain transaction hash for the token burn. If `persistOnchain` was true, this hash also confirms the proof data was recorded on-chain. | | `type` | string | The `type` of proof that was processed. | | `dateBurned` | string | An ISO 8601 timestamp indicating when the burn was processed. | ### Example Response (Success) ```json theme={null} { "result": "SUCCESS", "hash": "NEW_HASH_FOR_PRODUCT_BUY_EXAMPLE_TO_BE_CALCULATED", "txHash": "21RHE6MoxjjTHvKZ5X9hgGpS66CT7pikuL1AQmFXVPqHCxt2fQZaoj3WbYrJUzn1KxFNkFSF1Z4v7Mk4PRpWQx3J", "type": "PRODUCT_BUY", "dateBurned": "2025-05-20T01:56:40.169Z" } ``` ### Functional Error Codes Beyond authentication and rate limiting, the burn endpoint can return specific error codes related to the burn operation itself. These are typically returned with a 400 Bad Request status. | Error Code | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ERR_TOKEN_NOT_FOUND` | The token associated with the API key (or specified, if applicable) could not be found or is invalid. Ensure the token ID is correct. | | `ERR_CREATE_API_EVENT_FAILED` | The system encountered an issue while trying to record the API event for this burn attempt. This might indicate a temporary internal problem. | | `ERR_INVALID_PROOF` | The `type` of proof provided is not recognized, not permitted for the API key, or the `proof` object itself is considered invalid. | | `ERR_BURN_TOKENOMICS_FAILED` | The core token burn operation failed. This could be due to issues with the on-chain transaction, insufficient funds, or other internal errors during the burn process. | When these errors occur, the API response will typically include the error code and a message providing more details, similar to the authentication error format. Example (400 Bad Request): ```json theme={null} { "error": "ERR_INVALID_PROOF", "message": "Proof type not found" } ``` ## OpenAPI ````yaml POST /v1/tokenomics/burn openapi: 3.1.0 info: title: OpenAPI Plant Store description: >- A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification license: name: MIT version: 1.0.0 servers: - url: https://public.believe.app security: - bearerAuth: [] paths: /v1/tokenomics/burn: post: tags: - Tokenomics summary: Burn Tokens description: >- This endpoint allows burning tokens based on a provided proof, with an option to persist proof data on-chain. parameters: - name: x-idempotency-key in: header description: >- A unique key generated by the client to ensure a request is processed at most once. This is used to prevent accidental duplicate operations if a request is retried (e.g., due to a network error). required: true schema: type: string format: uuid requestBody: description: Details for the token burn operation. required: true content: application/json: schema: $ref: '#/components/schemas/BurnRequest' responses: '200': description: Successful token burn. content: application/json: schema: $ref: '#/components/schemas/BurnResponse' '400': description: Bad Request - Invalid input or error during processing. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKeyAuth: [] components: schemas: BurnRequest: type: object required: - type - proof - burnAmount - persistOnchain properties: type: type: string description: >- A string identifier for the type of proof being submitted (e.g., "PRODUCT_BUY"). proof: type: object description: A JSON object containing the actual proof data. additionalProperties: true burnAmount: type: number format: double positive: true description: The quantity of tokens to burn. Must be a positive number. persistOnchain: type: boolean description: >- A boolean flag indicating whether the hash of the proof should be recorded on the blockchain. BurnResponse: type: object required: - result - hash - type - txHash - dateBurned properties: result: type: string description: Indicates the outcome of the operation (e.g., "SUCCESS"). hash: type: string description: A SHA256 hash of the provided proof object. txHash: type: string description: The on-chain transaction hash for the token burn, if successful. type: type: string description: The type of proof that was processed. dateBurned: type: string format: date-time description: An ISO 8601 timestamp indicating when the burn was processed. Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-believe-api-key ````