Skip to main content
POST
/
v1
/
tokenomics
/
burn
Burn Tokens
curl --request POST \
  --url https://public.believe.app/v1/tokenomics/burn \
  --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
}
'
{
  "result": "<string>",
  "hash": "<string>",
  "txHash": "<string>",
  "type": "<string>",
  "dateBurned": "2023-11-07T05:31:56Z"
}
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 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

FieldTypeRequiredDescription
typestringYesA string identifier for the type of proof being submitted (e.g., “PRODUCT_BUY”, “PRODUCT_SELL”).
proofObjectYesA JSON object containing the actual proof data. Its structure will depend on 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.

​
Example Request

{
  "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:
FieldTypeDescription
resultstringIndicates the outcome of the operation (e.g., “SUCCESS”).
hashstringA SHA256 hash of the provided proof object.
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.
dateBurnedstringAn ISO 8601 timestamp indicating when the burn was processed.

​
Example Response (Success)

{
  "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 CodeDescription
ERR_TOKEN_NOT_FOUNDThe 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_FAILEDThe system encountered an issue while trying to record the API event for this burn attempt. This might indicate a temporary internal problem.
ERR_INVALID_PROOFThe type of proof provided is not recognized, not permitted for the API key, or the proof object itself is considered invalid.
ERR_BURN_TOKENOMICS_FAILEDThe 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): 
{
  "error": "ERR_INVALID_PROOF",
  "message": "Proof type not found"
}

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 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).

Body

application/json

Details for the token burn operation.

​
type
string
required

A string identifier for the type of proof being submitted (e.g., "PRODUCT_BUY").

​
proof
object
required

A JSON object containing the actual proof data.

​
burnAmount
number<double>
required

The quantity of tokens to burn. Must be a positive number.

​
persistOnchain
boolean
required

A boolean flag indicating whether the hash of the proof should be recorded on the blockchain.

Response

Successful token burn.

​
result
string
required

Indicates the outcome of the operation (e.g., "SUCCESS").

​
hash
string
required

A SHA256 hash of the provided proof object.

​
txHash
string
required

The on-chain transaction hash for the token burn, if successful.

​
type
string
required

The type of proof that was processed.

​
dateBurned
string<date-time>
required

An ISO 8601 timestamp indicating when the burn was processed.