POST
/
v1
/
tokenomics
/
burn-batch
Burn Batch Tokens
curl --request POST \
  --url https://public.believe.app/v1/tokenomics/burn-batch \
  --header 'Content-Type: application/json' \
  --header 'x-believe-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '[
  {
    "type": "<string>",
    "proof": {},
    "burnAmount": 123,
    "persistOnchain": true
  }
]'
{
  "success": [
    {
      "result": "<string>",
      "hash": "<string>",
      "txHash": "<string>",
      "type": "<string>",
      "dateBurned": "2023-11-07T05:31:56Z"
    }
  ],
  "errors": [
    {
      "message": "<string>",
      "type": "<string>",
      "proof": {},
      "proofType": "<string>"
    }
  ]
}
Deprecated: This endpoint is deprecated in favor of the new Flywheel API. 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 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:
FieldTypeRequiredDescription
typestringYesA string identifier for the type of proof being submitted (e.g., “PRODUCT_BUY”, “TWITTER_LIKE”).
proofObjectYesA JSON object containing the actual proof data. Its structure should correspond to the type.
burnAmountnumberYesThe quantity of tokens to burn. Must be a positive number.
persistOnchainbooleanYesA boolean flag indicating whether the hash of the proof should be recorded on the blockchain for this operation.

​
Example Request (JSON Body)

[
  {
    "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.
FieldTypeDescription
successArrayAn array of objects, each representing a successfully processed burn operation.
errorsArrayAn array of objects, each representing a burn operation that failed.

​
success Array Object Structure

Each object in the success array has the following fields:
FieldTypeDescription
resultstringIndicates the outcome of the operation (always “SUCCESS” for this array).
hashstringA SHA256 hash of the provided proof object for the successful operation.
txHashstringThe on-chain transaction hash for the token burn. If persistOnchain was true, this hash also confirms the proof data was recorded on-chain.
typestringThe type of proof that was processed successfully.
dateBurnedstringAn ISO 8601 timestamp indicating when the burn was processed.

​
errors Array Object Structure

Each object in the errors array has the following fields:
FieldTypeDescription
messagestringA message describing the reason for the failure of this specific operation.
typestringThe error code for this specific failure (e.g., ERR_INVALID_PROOF).
proofObjectThe original proof object submitted for the operation that failed.
proofTypestringThe original type of proof that was submitted for the operation that failed.

​
Example Response

{
  "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 (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.

Authorizations

​
x-believe-api-key
string
header
required

Headers

​
x-idempotency-key
string<uuid>
required

A unique key generated by the client to ensure a batch request is processed at most once.

Body

application/json · object[]

An array of token burn operations.

The body is of type object[].

Response

200
application/json

Successful batch token burn. The response indicates success or failure for each individual operation in the batch.

The response is of type object.