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
}
'import requests
url = "https://public.believe.app/v1/tokenomics/burn"
payload = {
"type": "<string>",
"proof": {},
"burnAmount": 123,
"persistOnchain": True
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-believe-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-believe-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({type: '<string>', proof: {}, burnAmount: 123, persistOnchain: true})
};
fetch('https://public.believe.app/v1/tokenomics/burn', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://public.believe.app/v1/tokenomics/burn",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => '<string>',
'proof' => [
],
'burnAmount' => 123,
'persistOnchain' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-believe-api-key: <api-key>",
"x-idempotency-key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://public.believe.app/v1/tokenomics/burn"
payload := strings.NewReader("{\n \"type\": \"<string>\",\n \"proof\": {},\n \"burnAmount\": 123,\n \"persistOnchain\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-believe-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://public.believe.app/v1/tokenomics/burn")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("x-believe-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"<string>\",\n \"proof\": {},\n \"burnAmount\": 123,\n \"persistOnchain\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public.believe.app/v1/tokenomics/burn")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-believe-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"<string>\",\n \"proof\": {},\n \"burnAmount\": 123,\n \"persistOnchain\": true\n}"
response = http.request(request)
puts response.read_body{
"result": "<string>",
"hash": "<string>",
"txHash": "<string>",
"type": "<string>",
"dateBurned": "2023-11-07T05:31:56Z"
}{
"error": 123,
"message": "<string>"
}{
"error": 123,
"message": "<string>"
}Burn Tokens (Deprecated)
This endpoint allows burning tokens based on a provided proof, with an option to persist proof data on-chain.
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
}
'import requests
url = "https://public.believe.app/v1/tokenomics/burn"
payload = {
"type": "<string>",
"proof": {},
"burnAmount": 123,
"persistOnchain": True
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-believe-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-believe-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({type: '<string>', proof: {}, burnAmount: 123, persistOnchain: true})
};
fetch('https://public.believe.app/v1/tokenomics/burn', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://public.believe.app/v1/tokenomics/burn",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => '<string>',
'proof' => [
],
'burnAmount' => 123,
'persistOnchain' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-believe-api-key: <api-key>",
"x-idempotency-key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://public.believe.app/v1/tokenomics/burn"
payload := strings.NewReader("{\n \"type\": \"<string>\",\n \"proof\": {},\n \"burnAmount\": 123,\n \"persistOnchain\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-believe-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://public.believe.app/v1/tokenomics/burn")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("x-believe-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"<string>\",\n \"proof\": {},\n \"burnAmount\": 123,\n \"persistOnchain\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://public.believe.app/v1/tokenomics/burn")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-believe-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"<string>\",\n \"proof\": {},\n \"burnAmount\": 123,\n \"persistOnchain\": true\n}"
response = http.request(request)
puts response.read_body{
"result": "<string>",
"hash": "<string>",
"txHash": "<string>",
"type": "<string>",
"dateBurned": "2023-11-07T05:31:56Z"
}{
"error": 123,
"message": "<string>"
}{
"error": 123,
"message": "<string>"
}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. IfpersistOnchain 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 theburn 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 thex-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-keyas 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.
x-idempotency-key: your_unique_generated_uuid_v4_here
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | A string identifier for the type of proof being submitted (e.g., “PRODUCT_BUY”, “PRODUCT_SELL”). |
proof | Object | Yes | A JSON object containing the actual proof data. Its structure will depend on 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. |
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:| Field | Type | Description |
|---|---|---|
result | string | Indicates the outcome of the operation (e.g., “SUCCESS”). |
hash | string | A SHA256 hash of the provided proof object. |
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. |
dateBurned | string | An 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 Code | Description |
|---|---|
ERR_TOKEN_NOT_FOUND | The 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_FAILED | The system encountered an issue while trying to record the API event for this burn attempt. This might indicate a temporary internal problem. |
ERR_INVALID_PROOF | The type of proof provided is not recognized, not permitted for the API key, or the proof object itself is considered invalid. |
ERR_BURN_TOKENOMICS_FAILED | The 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. |
{
"error": "ERR_INVALID_PROOF",
"message": "Proof type not found"
}
Authorizations
Headers
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
Details for the token burn operation.
A string identifier for the type of proof being submitted (e.g., "PRODUCT_BUY").
A JSON object containing the actual proof data.
The quantity of tokens to burn. Must be a positive number.
A boolean flag indicating whether the hash of the proof should be recorded on the blockchain.
Response
Successful token burn.
Indicates the outcome of the operation (e.g., "SUCCESS").
A SHA256 hash of the provided proof object.
The on-chain transaction hash for the token burn, if successful.
The type of proof that was processed.
An ISO 8601 timestamp indicating when the burn was processed.