Burn Batch Tokens (Deprecated)

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

import requests

url = "https://public.believe.app/v1/tokenomics/burn-batch"

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-batch', 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-batch",
  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-batch"

	payload := strings.NewReader("[\n  {\n    \"type\": \"<string>\",\n    \"proof\": {},\n    \"burnAmount\": 123,\n    \"persistOnchain\": true\n  }\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-batch")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-believe-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"type\": \"<string>\",\n    \"proof\": {},\n    \"burnAmount\": 123,\n    \"persistOnchain\": true\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.believe.app/v1/tokenomics/burn-batch")

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  {\n    \"type\": \"<string>\",\n    \"proof\": {},\n    \"burnAmount\": 123,\n    \"persistOnchain\": true\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "success": [
    {
      "result": "<string>",
      "hash": "<string>",
      "txHash": "<string>",
      "type": "<string>",
      "dateBurned": "2023-11-07T05:31:56Z"
    }
  ],
  "errors": [
    {
      "message": "<string>",
      "type": "<string>",
      "proof": {},
      "proofType": "<string>"
    }
  ]
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

POST

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

import requests

url = "https://public.believe.app/v1/tokenomics/burn-batch"

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-batch', 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-batch",
  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-batch"

	payload := strings.NewReader("[\n  {\n    \"type\": \"<string>\",\n    \"proof\": {},\n    \"burnAmount\": 123,\n    \"persistOnchain\": true\n  }\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-batch")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-believe-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"type\": \"<string>\",\n    \"proof\": {},\n    \"burnAmount\": 123,\n    \"persistOnchain\": true\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.believe.app/v1/tokenomics/burn-batch")

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  {\n    \"type\": \"<string>\",\n    \"proof\": {},\n    \"burnAmount\": 123,\n    \"persistOnchain\": true\n  }\n]"

response = http.request(request)
puts response.read_body

{
  "success": [
    {
      "result": "<string>",
      "hash": "<string>",
      "txHash": "<string>",
      "type": "<string>",
      "dateBurned": "2023-11-07T05:31:56Z"
    }
  ],
  "errors": [
    {
      "message": "<string>",
      "type": "<string>",
      "proof": {},
      "proofType": "<string>"
    }
  ]
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<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:

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<uuid>

required

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

Body

application/json

An array of token burn operations.

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 batch token burn. The response indicates success or failure for each individual operation in the batch.

success

object[]

An array of successfully processed burn operations.

Show child attributes

errors

object[]

An array of burn operations that failed.

Show child attributes

API Documentation

Flywheel V1

Tokenomics (Deprecated)

Burn Batch Tokens (Deprecated)

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

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