Skip to main content
POST
/
v1
/
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>"
}'
{
  "batchId": "<string>",
  "result": {
    "total": 123,
    "totalSuccessful": 123,
    "totalFailed": 123,
    "successfulExecutions": [
      {
        "bundleId": "<string>",
        "txHashes": [
          "<string>"
        ]
      }
    ],
    "failedOnTransactionIndex": 123,
    "failedStartTransactionIndex": 123,
    "failedTxMsg": "<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

FieldTypeRequiredDescription
batchIdstringYesThe unique identifier (UUID) of the batch to execute (returned from batch init).
signedTxstringYesBase64-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:
FieldTypeDescription
batchIdstringThe batch ID (UUID) that was executed.
resultObjectDetailed execution results for all transactions in the batch.

​
Execution Result Object

FieldTypeDescription
totalnumberTotal number of pipeline transactions in the batch.
totalSuccessfulnumberNumber of pipeline transactions that executed successfully.
totalFailednumberNumber of pipeline transactions that failed to execute.
successfulExecutionsArrayArray of successful bundle executions with their details.
failedOnTransactionIndexnumber(Optional) Transaction index where failure occurred.
failedStartTransactionIndexnumber(Optional) Starting transaction index of the failed batch.
failedTxMsgstring(Optional) Error message describing the failure.

​
Successful Execution Object

FieldTypeDescription
bundleIdstringJito bundle ID (hex string) for this group of transactions.
txHashesArrayArray 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

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

​
Important Notes

  1. 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
  2. Execution Order: Pipeline transactions are executed in the order they were submitted in the batch init call.
  3. Partial Success: If some transactions succeed and others fail, you’ll receive detailed results showing which transactions completed successfully.
  4. Transaction Finality: All returned transaction hashes represent confirmed transactions on the Solana blockchain.
  5. 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 CodeStatusDescription
ERR_TOKEN_NOT_FOUND404The token associated with the API key could not be found.
ERR_KEY_NOT_FOUND404The API key could not be found or is invalid.
ERR_FLYWHEEL_NOT_FOUND404No flywheel is associated with the provided API key.
ERR_BATCH_EXECUTE_FAILED500Failed 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

  1. Call /flywheel/batch/init with your pipelines
  2. Sign the returned proposalApproveTx with your registered wallet
  3. Wait for required approvals (company + project approver)
  4. Call /flywheel/batch/execute with the batchId and signed transaction
  5. 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