Burn Batch Tokens

POST

tokenomics

burn-batch

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>"
    }
  ]
}

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.

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:

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)

[
  {
    "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

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

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.

Burn 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>"
    }
  ]
}

API Documentation

Endpoints

Overview

Authentication

Rate Limiting

Idempotency

Request Body

Example Request (JSON Body)

Response Body

`success` Array Object Structure

`errors` Array Object Structure

Example Response

Functional Error Codes

Authorizations

Headers

Body

Response

API Documentation

Endpoints

​Overview

​Authentication

​Rate Limiting

​Idempotency

​Request Body

​Example Request (JSON Body)

​Response Body

​success Array Object Structure

​errors Array Object Structure

​Example Response

​Functional Error Codes

Authorizations

Headers

Body

Response

Overview

Authentication

Rate Limiting

Idempotency

Request Body

Example Request (JSON Body)

Response Body

`success` Array Object Structure

`errors` Array Object Structure

Example Response

Functional Error Codes