POST
/
v1
/
tokenomics
/
burn
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"
}

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

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

The body is of type object.

Response

200
application/json

Successful token burn.

The response is of type object.