> ## Documentation Index > Fetch the complete documentation index at: https://docs.believe.app/llms.txt > Use this file to discover all available pages before exploring further. # Execute Batch Transaction > This endpoint executes a flywheel batch after approval, processing all pipeline transactions and returning detailed execution results. ## 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 ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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 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 ```json theme={null} { "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 ## OpenAPI ````yaml POST /v1/flywheel/batch/execute openapi: 3.1.0 info: title: OpenAPI Plant Store description: >- A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification license: name: MIT version: 1.0.0 servers: - url: https://public.believe.app security: - bearerAuth: [] paths: /v1/flywheel/batch/execute: post: tags: - Flywheel summary: Execute Batch Transaction description: >- This endpoint executes a flywheel batch after approval, processing all pipeline transactions and returning detailed execution results. parameters: - name: x-idempotency-key in: header description: >- A unique key generated by the client to ensure a request is processed at most once. required: true schema: type: string format: uuid requestBody: description: Batch execution details with signed transaction. required: true content: application/json: schema: $ref: '#/components/schemas/BatchExecuteRequest' responses: '200': description: Batch execution completed (may include partial failures). content: application/json: schema: $ref: '#/components/schemas/BatchExecuteResponse' '401': description: Unauthorized - API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found - Token or flywheel not found. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error - Batch execution failed. content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKeyAuth: [] components: schemas: BatchExecuteRequest: type: object required: - batchId - signedTx properties: batchId: type: string format: uuid description: The unique identifier (UUID) of the batch to execute. signedTx: type: string description: >- Base64-encoded signed transaction (the proposalApproveTx from batch init, signed by you). BatchExecuteResponse: type: object required: - batchId - result properties: batchId: type: string description: The batch ID (UUID) that was executed. result: $ref: '#/components/schemas/ExecutionResult' Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string ExecutionResult: type: object required: - total - totalSuccessful - totalFailed - successfulExecutions properties: total: type: number description: Total number of pipeline transactions in the batch. totalSuccessful: type: number description: Number of pipeline transactions that executed successfully. totalFailed: type: number description: Number of pipeline transactions that failed to execute. successfulExecutions: type: array description: Array of successful bundle executions with their details. items: $ref: '#/components/schemas/SuccessfulExecution' failedOnTransactionIndex: type: number description: Transaction index where failure occurred (optional). failedStartTransactionIndex: type: number description: Starting transaction index of the failed batch (optional). failedTxMsg: type: string description: Error message describing the failure (optional). SuccessfulExecution: type: object required: - bundleId - txHashes properties: bundleId: type: string description: Jito bundle ID (hex string) for this group of transactions. txHashes: type: array description: >- Array of Solana transaction signatures (base58 strings) for executed transactions. items: type: string securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-believe-api-key ````