Execute Batch Transaction

curl --request POST \
  --url https://public.believe.app/v1/flywheel/batch/execute \
  --header 'Content-Type: application/json' \
  --header 'x-believe-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "signedTx": "<string>"
}
'

import requests

url = "https://public.believe.app/v1/flywheel/batch/execute"

payload = {
    "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "signedTx": "<string>"
}
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({batchId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', signedTx: '<string>'})
};

fetch('https://public.believe.app/v1/flywheel/batch/execute', 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/flywheel/batch/execute",
  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([
    'batchId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'signedTx' => '<string>'
  ]),
  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/flywheel/batch/execute"

	payload := strings.NewReader("{\n  \"batchId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"signedTx\": \"<string>\"\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/flywheel/batch/execute")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-believe-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batchId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"signedTx\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.believe.app/v1/flywheel/batch/execute")

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  \"batchId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"signedTx\": \"<string>\"\n}"

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

{
  "batchId": "<string>",
  "result": {
    "total": 123,
    "totalSuccessful": 123,
    "totalFailed": 123,
    "successfulExecutions": [
      {
        "bundleId": "<string>",
        "txHashes": [
          "<string>"
        ]
      }
    ],
    "failedOnTransactionIndex": 123,
    "failedStartTransactionIndex": 123,
    "failedTxMsg": "<string>"
  }
}

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

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

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

POST

flywheel

batch

execute

Execute Batch Transaction

curl --request POST \
  --url https://public.believe.app/v1/flywheel/batch/execute \
  --header 'Content-Type: application/json' \
  --header 'x-believe-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "signedTx": "<string>"
}
'

import requests

url = "https://public.believe.app/v1/flywheel/batch/execute"

payload = {
    "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "signedTx": "<string>"
}
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({batchId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', signedTx: '<string>'})
};

fetch('https://public.believe.app/v1/flywheel/batch/execute', 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/flywheel/batch/execute",
  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([
    'batchId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'signedTx' => '<string>'
  ]),
  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/flywheel/batch/execute"

	payload := strings.NewReader("{\n  \"batchId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"signedTx\": \"<string>\"\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/flywheel/batch/execute")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("x-believe-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batchId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"signedTx\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.believe.app/v1/flywheel/batch/execute")

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  \"batchId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"signedTx\": \"<string>\"\n}"

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

{
  "batchId": "<string>",
  "result": {
    "total": 123,
    "totalSuccessful": 123,
    "totalFailed": 123,
    "successfulExecutions": [
      {
        "bundleId": "<string>",
        "txHashes": [
          "<string>"
        ]
      }
    ],
    "failedOnTransactionIndex": 123,
    "failedStartTransactionIndex": 123,
    "failedTxMsg": "<string>"
  }
}

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

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

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

Overview

The Execute Batch Transaction endpoint processes a signed batch transaction and executes all pipeline transactions within the batch. This endpoint should be called after the proposalApproveTx from batch init has been signed with your registered wallet address and approved by the required parties. The endpoint processes transactions in chunks of 4 for optimal performance and uses Jito bundles to ensure reliable execution on Solana. It provides detailed results including successful executions, failures, and transaction hashes.

Authentication

This endpoint requires API key authentication. The API key must have either burn or airdrop scopes. 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 minute per API key.

Request Body

Field	Type	Required	Description
`batchId`	string	Yes	The unique identifier (UUID) of the batch to execute (returned from batch init).
`signedTx`	string	Yes	Base64-encoded signed transaction (the `proposalApproveTx` from batch init, signed by you).

Example Request

{
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "signedTx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDAbc9WnXF..."
}

Response Body

On success, the API returns a JSON object with the following fields:

Field	Type	Description
`batchId`	string	The batch ID (UUID) that was executed.
`result`	Object	Detailed execution results for all transactions in the batch.

Execution Result Object

Field	Type	Description
`total`	number	Total number of pipeline transactions in the batch.
`totalSuccessful`	number	Number of pipeline transactions that executed successfully.
`totalFailed`	number	Number of pipeline transactions that failed to execute.
`successfulExecutions`	Array	Array of successful bundle executions with their details.
`failedOnTransactionIndex`	number	(Optional) Transaction index where failure occurred.
`failedStartTransactionIndex`	number	(Optional) Starting transaction index of the failed batch.
`failedTxMsg`	string	(Optional) Error message describing the failure.

Successful Execution Object

Field	Type	Description
`bundleId`	string	Jito bundle ID (hex string) for this group of transactions.
`txHashes`	Array	Array of Solana transaction signatures (base58 strings) for executed transactions.

Example Response (Success)

{
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "total": 8,
    "totalSuccessful": 8,
    "totalFailed": 0,
    "successfulExecutions": [
      {
        "bundleId": "d0f38d76f53a94b1fa1a0e2c6be123da7ce634afa87733939e406d39f659e68e",
        "txHashes": [
          "27FG487NDUAnrs79xRaycwtW3pCPb4G4664P2nFfmZkH1EEVJqmRoFEEHzXS6A6V2HsZ2bBU6QgP1JgfRx9cRPKh",
          "4KkFDQ1MBKHrvsNjbNWDttNdHq4f6bys7T5GUDc7Vb6Uv1hUGDVhHCQamnQFmFjnDTQxga6KMi9Yx6fru2sMucKa",
          "4E6vzH1ep75ArgxFpoXqWgkPinnuFq4kKp2EMnpjcDXKeW5PSfdqQeSusPaxHjf9qfk9ZGcoZkjvY2SzovGdd3Kf",
          "4pCsbF58DHVfpUZdzmBKimLrAPNE75cXf82FejmYvvxe2eUEXhBhV4RFV9btayMrLsA8QUY8ABed4MxXDUpoB9L3"
        ]
      },
      {
        "bundleId": "a3e27f45c92b8d1e0c6f4a8b2d7e9f1c8a4b5e6d9c2f1a7b3e8d4c9f2e5a1b6c",
        "txHashes": [
          "5YL73XMzhRLa9CQe1CqxsW1XVt8W2xqEqj3HjZcmELeR22pGxg7rxojBViPw1U8k1cSTbpnhdvGTD1V8SZKao2kc",
          "3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1KqJ8LoX2GbM4aC9eR",
          "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC",
          "2P5mHnJsVxF8YqRpT9KwE6ZvB8TdN4PqJ7LoX1GbK3vC5sF"
        ]
      }
    ]
  }
}

Example Response (Partial Failure)

{
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "total": 8,
    "totalSuccessful": 4,
    "totalFailed": 4,
    "successfulExecutions": [
      {
        "bundleId": "d0f38d76f53a94b1fa1a0e2c6be123da7ce634afa87733939e406d39f659e68e",
        "txHashes": [
          "27FG487NDUAnrs79xRaycwtW3pCPb4G4664P2nFfmZkH1EEVJqmRoFEEHzXS6A6V2HsZ2bBU6QgP1JgfRx9cRPKh",
          "4KkFDQ1MBKHrvsNjbNWDttNdHq4f6bys7T5GUDc7Vb6Uv1hUGDVhHCQamnQFmFjnDTQxga6KMi9Yx6fru2sMucKa",
          "4E6vzH1ep75ArgxFpoXqWgkPinnuFq4kKp2EMnpjcDXKeW5PSfdqQeSusPaxHjf9qfk9ZGcoZkjvY2SzovGdd3Kf",
          "4pCsbF58DHVfpUZdzmBKimLrAPNE75cXf82FejmYvvxe2eUEXhBhV4RFV9btayMrLsA8QUY8ABed4MxXDUpoB9L3"
        ]
      }
    ],
    "failedOnTransactionIndex": 5,
    "failedStartTransactionIndex": 5,
    "failedTxMsg": "Bundle execution failed: insufficient funds"
  }
}

Execution Process

Proposal Broadcast: The signed proposal transaction is broadcast to approve the batch execution.
Sequential Processing: Each pipeline transaction in the batch is executed sequentially using Solana multisig batch execute instructions.
Chunked Execution: Transactions are processed in chunks of 4 for optimal performance and reliability.
Jito Bundle Integration: Each chunk is executed as a Jito bundle to ensure atomic execution and better transaction reliability.
Status Tracking: The system tracks the status of each pipeline and updates the database with execution results.
Resilient Handling: If a chunk fails, the system continues processing remaining chunks, providing partial success results.

Important Notes

Prerequisites: Before calling this endpoint, you must:
- Have called /flywheel/batch/init successfully
- Signed the returned proposalApproveTx with your registered wallet address
- Received the required approvals from company and project approvers
Execution Order: Pipeline transactions are executed in the order they were submitted in the batch init call.
Partial Success: If some transactions succeed and others fail, you’ll receive detailed results showing which transactions completed successfully.
Transaction Finality: All returned transaction hashes represent confirmed transactions on the Solana blockchain.
Jito Integration: The endpoint uses Jito bundles for execution, which may include tip transactions that don’t appear in your pipeline results.

Error Codes

The batch execute endpoint can return specific error codes related to the execution process.

Error Code	Status	Description
`ERR_TOKEN_NOT_FOUND`	404	The token associated with the API key could not be found.
`ERR_KEY_NOT_FOUND`	404	The API key could not be found or is invalid.
`ERR_FLYWHEEL_NOT_FOUND`	404	No flywheel is associated with the provided API key.
`ERR_BATCH_EXECUTE_FAILED`	500	Failed to execute the batch. Check the response for detailed failure information.

Example Error Response

{
  "error": "ERR_BATCH_EXECUTE_FAILED",
  "message": "Bundle execution failed: insufficient funds"
}

Workflow Summary

Call /flywheel/batch/init with your pipelines
Sign the returned proposalApproveTx with your registered wallet
Wait for required approvals (company + project approver)
Call /flywheel/batch/execute with the batchId and signed transaction
Monitor execution results and handle any partial failures as needed

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.

Body

application/json

Batch execution details with signed transaction.

batchId

string<uuid>

required

The unique identifier (UUID) of the batch to execute.

signedTx

string

required

Base64-encoded signed transaction (the proposalApproveTx from batch init, signed by you).

Response

Batch execution completed (may include partial failures).

batchId

string

required

The batch ID (UUID) that was executed.

result

object

required

Show child attributes

Initialize Batch Transaction Get Batch Status

API Documentation

Flywheel V1

Tokenomics (Deprecated)

Execute Batch Transaction

Overview

Authentication

Rate Limiting

Request Body

Example Request

Response Body

Execution Result Object

Successful Execution Object

Example Response (Success)

Example Response (Partial Failure)

Execution Process

Important Notes

Error Codes

Example Error Response

Workflow Summary

Authorizations

Headers

Body

Response

​Overview

​Authentication

​Rate Limiting

​Request Body

​Example Request

​Response Body

​Execution Result Object

​Successful Execution Object

​Example Response (Success)

​Example Response (Partial Failure)

​Execution Process

​Important Notes

​Error Codes

​Example Error Response

​Workflow Summary

Authorizations

Headers

Body

Response

Overview

Authentication

Rate Limiting

Request Body

Example Request

Response Body

Execution Result Object

Successful Execution Object

Example Response (Success)

Example Response (Partial Failure)

Execution Process

Important Notes

Error Codes

Example Error Response

Workflow Summary