> ## 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 Batch Tokens (Deprecated) > This endpoint allows burning multiple tokens in a single request, each based on a provided proof, with an option to persist proof data on-chain for each. **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 `POST /v1/tokenomics/burn-batch` endpoint facilitates the burning of specified amounts of tokens for multiple independent operations in a single API call. Each operation in the batch requires its own proof of an off-chain event or condition that justifies the burn. If `persistOnchain` is true for an operation, the hash of its proof will be recorded on the blockchain. This endpoint processes each burn operation in the batch individually. The overall request will succeed, and the response will detail which operations were successful and which ones failed. ## Authentication This endpoint requires API key authentication using the `x-believe-api-key` request header. The API key must have the appropriate `burn` scope. **NOTE**: This endpoint only works for /v1 tokens. Example: `x-believe-api-key: your_actual_api_key_here` Refer to the [Auth Error Codes](/api-reference/auth-error-codes) for details on authentication-related errors. ## Rate Limiting Requests to this endpoint are rate-limited to **1 request per 10 seconds** per API key. The rate limit prefix is `api-key-burn`. ## 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 The request body must be a JSON array, where each object in the array represents a single token burn operation with the following fields: | Field | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `type` | string | Yes | A string identifier for the type of proof being submitted (e.g., "PRODUCT\_BUY", "TWITTER\_LIKE"). | | `proof` | Object | Yes | A JSON object containing the actual proof data. Its structure should correspond to 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 for this operation. | ### Example Request (JSON Body) ```json theme={null} [ { "type": "PRODUCT_BUY", "proof": { "transactionId": "237892372", "value": "100" }, "burnAmount": 10000, "persistOnchain": true }, { "type": "PRODUCT_REFUND", "proof": { "transactionId": "23adadad7892372", "value": "100" }, "burnAmount": 10000, "persistOnchain": true } ] ``` ## Response Body On success (even if some individual operations within the batch fail), the API returns a 2xx HTTP status code and a JSON object with two main arrays: `success` and `errors`. | Field | Type | Description | | --------- | ----- | ------------------------------------------------------------------------------- | | `success` | Array | An array of objects, each representing a successfully processed burn operation. | | `errors` | Array | An array of objects, each representing a burn operation that failed. | ### `success` Array Object Structure Each object in the `success` array has the following fields: | Field | Type | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `result` | string | Indicates the outcome of the operation (always "SUCCESS" for this array). | | `hash` | string | A SHA256 hash of the provided `proof` object for the successful operation. | | `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 successfully. | | `dateBurned` | string | An ISO 8601 timestamp indicating when the burn was processed. | ### `errors` Array Object Structure Each object in the `errors` array has the following fields: | Field | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------ | | `message` | string | A message describing the reason for the failure of this specific operation. | | `type` | string | The error code for this specific failure (e.g., `ERR_INVALID_PROOF`). | | `proof` | Object | The original `proof` object submitted for the operation that failed. | | `proofType` | string | The original `type` of proof that was submitted for the operation that failed. | ### Example Response ```json theme={null} { "success": [ { "result": "SUCCESS", "hash": "3c39644ffbd433fa157871e160fe6a40509dd527e3753cbb4399029d8336735c", "txHash": "MX9tPZhsrnnxVejcKekWndCK9TJjrbTdmdgATqUtPKrDuW2k5CqtAC5N912bNRFLbTxXYzyiz32caWBSMKdGJ6o", "type": "PRODUCT_BUY", "dateBurned": "2025-05-20T23:54:28.587Z" }, { "result": "SUCCESS", "hash": "bdba07a771ef6c05bca98a0a61b0c9c5f9bd45baba3ffc38824416058fe39b16", "txHash": "2WwwtUs6DjujEZiJajDA82Usxq7iuBi869UJeiWRRqwsdoq3nbJqCGiDysFUPKGX3fnq4zw33EQ1Xmv3T8oGys4T", "type": "PRODUCT_REFUND", "dateBurned": "2025-05-20T23:54:28.638Z" } ], "errors": [] } ``` ## Functional Error Codes Individual operations within the batch can fail with error codes similar to those in the single [Burn Tokens endpoint](/api-reference/endpoint/tokenomics/burn#functional-error-codes) (e.g., `ERR_TOKEN_NOT_FOUND`, `ERR_INVALID_PROOF`, `ERR_BURN_TOKENOMICS_FAILED`). These will be reported in the `errors` array of the response, as detailed above. If the entire batch request fails due to issues like invalid overall request structure (e.g., not an array), authentication failure, or exceeding global rate limits, the API will return a standard 4xx or 5xx error response. ## OpenAPI ````yaml POST /v1/tokenomics/burn-batch 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-batch: post: tags: - Tokenomics summary: Burn Batch Tokens description: >- This endpoint allows burning multiple tokens in a single request, each based on a provided proof, with an option to persist proof data on-chain for each. parameters: - name: x-idempotency-key in: header description: >- A unique key generated by the client to ensure a batch request is processed at most once. required: true schema: type: string format: uuid requestBody: description: An array of token burn operations. required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/BurnRequest' responses: '200': description: >- Successful batch token burn. The response indicates success or failure for each individual operation in the batch. content: application/json: schema: $ref: '#/components/schemas/BurnBatchResponse' '400': description: >- Bad Request - The overall request structure might be invalid, or an issue occurred that prevents batch 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. BurnBatchResponse: type: object properties: success: type: array items: $ref: '#/components/schemas/BurnBatchSuccessItem' description: An array of successfully processed burn operations. errors: type: array items: $ref: '#/components/schemas/BurnBatchErrorItem' description: An array of burn operations that failed. Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string BurnBatchSuccessItem: type: object required: - result - hash - txHash - type - 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 for this item. txHash: type: string description: The on-chain transaction hash for this token burn item. type: type: string description: The type of proof that was processed for this item. dateBurned: type: string format: date-time description: An ISO 8601 timestamp indicating when this burn item was processed. BurnBatchErrorItem: type: object required: - message - type - proof - proofType properties: message: type: string description: >- A message describing the reason for the failure of this specific operation. type: type: string description: >- The error code for this specific failure (e.g., "ERR_INVALID_PROOF"). proof: type: object description: The original proof object submitted for the operation that failed. additionalProperties: true proofType: type: string description: >- The original type of proof that was submitted for the operation that failed. securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-believe-api-key ````