> ## 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.

# Initialize Batch Transaction

> This endpoint compiles flywheel pipelines into Solana transaction instructions and creates a batch transaction for approval.

## Overview

The Initialize Batch Transaction endpoint compiles an array of flywheel pipelines into Solana transaction instructions and creates a batch transaction that requires approval from both company and project approvers. This endpoint is used to prepare complex multi-action operations that can include token burns, airdrops, buybacks, locks, unlocks, and memo attachments.

Each pipeline automatically gets a proof memo prepended to verify the authenticity of the operation based on the provided type and payload.

## 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                                              |
| ----------- | ----- | -------- | -------------------------------------------------------- |
| `pipelines` | Array | Yes      | Array of pipeline objects containing actions to execute. |

### Pipeline Object

| Field     | Type   | Required | Description                                                                     |
| --------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `type`    | string | Yes      | The type identifier for this pipeline (e.g., "WATCH\_AD", "PRODUCT\_PURCHASE"). |
| `payload` | string | Yes      | JSON string containing the proof data for this pipeline.                        |
| `actions` | Array  | Yes      | Array of action objects to execute in this pipeline.                            |

### Action Types

#### BURN Action

Burns a specified amount of tokens.

| Field    | Type   | Required | Description                                |
| -------- | ------ | -------- | ------------------------------------------ |
| `action` | string | Yes      | Must be "BURN"                             |
| `amount` | number | Yes      | Amount of tokens to burn (in whole tokens) |

#### AIRDROP Action

Sends tokens to a specified wallet address.

| Field       | Type   | Required | Description                                   |
| ----------- | ------ | -------- | --------------------------------------------- |
| `action`    | string | Yes      | Must be "AIRDROP"                             |
| `toAddress` | string | Yes      | Solana wallet address to send tokens to       |
| `amount`    | number | Yes      | Amount of tokens to airdrop (in whole tokens) |

#### BUYBACK Action *(Coming Soon)*

Executes a token buyback operation.

| Field    | Type   | Required | Description                                   |
| -------- | ------ | -------- | --------------------------------------------- |
| `action` | string | Yes      | Must be "BUYBACK"                             |
| `amount` | number | Yes      | Amount of tokens to buyback (in whole tokens) |

*Note: BUYBACK action is not yet implemented.*

#### LOCK Action *(Coming Soon)*

Locks tokens with vesting parameters.

| Field     | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `action`  | string | Yes      | Must be "LOCK"                             |
| `amount`  | number | Yes      | Amount of tokens to lock (in whole tokens) |
| `vesting` | Object | Yes      | Vesting parameters for the locked tokens   |

*Note: LOCK action is not yet implemented.*

#### UNLOCK Action *(Coming Soon)*

Unlocks previously locked tokens.

| Field    | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `action` | string | Yes      | Must be "UNLOCK" |

*Note: UNLOCK action is not yet implemented.*

#### MEMO Action

Adds a memo message to the transaction.

| Field     | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `action`  | string | Yes      | Must be "MEMO"             |
| `message` | string | Yes      | The memo message to attach |

### Example Request

```json theme={null}
{
  "pipelines": [
    {
      "type": "WATCH_AD",
      "payload": "{\"adId\":\"123\",\"adProvider\":\"google\",\"platform\":\"ios\"}",
      "actions": [
        {
          "action": "BURN",
          "amount": 100
        },
        {
          "action": "AIRDROP",
          "toAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
          "amount": 50
        }
      ]
    }
  ]
}
```

## Response Body

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

| Field               | Type   | Description                                                                                                                               |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `proposalApproveTx` | string | Base64-encoded serialized transaction that must be signed with your registered wallet address (the one used during flywheel registration) |
| `batch`             | Object | The batch object containing details about the compiled pipelines                                                                          |

### Example Response (Success)

```json theme={null}
{
  "proposalApproveTx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDAbc9WnXF...",
  "batch": {
    "id": "batch_xyz789",
    "flywheelId": "flywheel_abc123",
    "status": "PENDING_APPROVAL",
    "pipelines": [
      {
        "type": "WATCH_AD",
        "payload": "{\"adId\":\"ca-app-pub-6628751172535228/7816916817\",\"adProvider\":\"google\",\"platform\":\"ios\"}",
        "actions": [
          {
            "action": "BURN",
            "amount": 100
          },
          {
            "action": "AIRDROP",
            "toAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
            "amount": 50
          }
        ],
        "instructions": ["base64_encoded_instruction_1", "base64_encoded_instruction_2"]
      }
    ],
    "dateCreated": "2025-01-27T12:00:00.000Z"
  }
}
```

## Important Notes

1. **Proof Memos**: Each pipeline automatically gets a proof memo prepended to its actions. This memo contains a hash of the type and payload for verification purposes.

2. **Transaction Size Limits**: Each pipeline must fit within a single Solana transaction (max \~900 bytes of instruction data). Pipelines that are too large will be rejected.

3. **Approval Required**: The returned `proposalApproveTx` must be signed with your registered wallet address (the wallet address you provided during flywheel registration). This transaction requires approval from both the company approver and your project approver wallet before execution.

4. **Action Limitations**: Currently, only `BURN`, `AIRDROP`, and `MEMO` actions are fully implemented. `BUYBACK`, `LOCK`, and `UNLOCK` actions are coming soon.

5. **Associated Token Accounts**: For `AIRDROP` actions, the endpoint automatically creates associated token accounts for recipients if they don't exist.

## Error Codes

The batch init endpoint can return specific error codes related to the compilation and validation 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_INIT_FAILED`         | 500    | Failed to compile pipelines or initialize the batch transaction.          |
| `ERR_FLYWHEEL_ACTIONS_EMPTY`    | 400    | One or more pipelines contain no actions.                                 |
| `ERR_FLYWHEEL_INVALID_ACTION`   | 400    | One or more actions in the pipelines are invalid or unsupported.          |
| `ERR_FLYWHEEL_NO_INSTRUCTIONS`  | 400    | Pipeline compilation resulted in no transaction instructions.             |
| `ERR_FLYWHEEL_PIPELINE_TOO_BIG` | 400    | Pipeline contains too many actions to fit in a single Solana transaction. |

### Example Error Response

```json theme={null}
{
  "error": "ERR_FLYWHEEL_PIPELINE_TOO_BIG",
  "message": "Pipeline has too many actions to fit in a single transaction"
}
```


## OpenAPI

````yaml POST /v1/flywheel/batch/init
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/init:
    post:
      tags:
        - Flywheel
      summary: Initialize Batch Transaction
      description: >-
        This endpoint compiles flywheel pipelines into Solana transaction
        instructions and creates a batch transaction for approval.
      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: Array of flywheel pipelines to compile into batch transaction.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInitRequest'
      responses:
        '200':
          description: Successful batch initialization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchInitResponse'
        '400':
          description: Bad Request - Invalid input or compilation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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 initialization failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    BatchInitRequest:
      type: object
      required:
        - pipelines
      properties:
        pipelines:
          type: array
          description: Array of pipeline objects containing actions to execute.
          items:
            $ref: '#/components/schemas/Pipeline'
    BatchInitResponse:
      type: object
      required:
        - proposalApproveTx
        - batch
      properties:
        proposalApproveTx:
          type: string
          description: >-
            Base64-encoded serialized transaction that must be signed with your
            registered wallet address.
        batch:
          $ref: '#/components/schemas/BatchObject'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    Pipeline:
      type: object
      required:
        - type
        - payload
        - actions
      properties:
        type:
          type: string
          description: >-
            The type identifier for this pipeline (e.g., "WATCH_AD",
            "PRODUCT_PURCHASE").
        payload:
          type: string
          description: JSON string containing the proof data for this pipeline.
        actions:
          type: array
          description: Array of action objects to execute in this pipeline.
          items:
            $ref: '#/components/schemas/Action'
    BatchObject:
      type: object
      required:
        - id
        - flywheelId
        - status
        - pipelines
        - dateCreated
      properties:
        id:
          type: string
          description: The unique batch identifier (UUID).
        flywheelId:
          type: string
          description: The flywheel this batch belongs to.
        status:
          type: string
          enum:
            - AVAILABLE_TO_QUEUE
            - FINALIZED
            - EXECUTED
            - FAILED
          description: Current batch status.
        pipelines:
          type: array
          description: Array of compiled pipeline objects.
          items:
            $ref: '#/components/schemas/CompiledPipeline'
        dateCreated:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the batch was created.
    Action:
      oneOf:
        - $ref: '#/components/schemas/BurnAction'
        - $ref: '#/components/schemas/AirdropAction'
        - $ref: '#/components/schemas/BuybackAction'
        - $ref: '#/components/schemas/LockAction'
        - $ref: '#/components/schemas/UnlockAction'
        - $ref: '#/components/schemas/MemoAction'
    CompiledPipeline:
      type: object
      required:
        - type
        - payload
        - actions
        - instructions
      properties:
        type:
          type: string
          description: The type identifier for this pipeline.
        payload:
          type: string
          description: JSON string containing the proof data for this pipeline.
        actions:
          type: array
          description: Array of action objects to execute in this pipeline.
          items:
            $ref: '#/components/schemas/Action'
        instructions:
          type: array
          description: Array of base64-encoded Solana transaction instructions.
          items:
            type: string
    BurnAction:
      type: object
      required:
        - action
        - amount
      properties:
        action:
          type: string
          enum:
            - BURN
          description: Must be "BURN"
        amount:
          type: number
          description: Amount of tokens to burn (in whole tokens)
    AirdropAction:
      type: object
      required:
        - action
        - toAddress
        - amount
      properties:
        action:
          type: string
          enum:
            - AIRDROP
          description: Must be "AIRDROP"
        toAddress:
          type: string
          description: Solana wallet address to send tokens to
        amount:
          type: number
          description: Amount of tokens to airdrop (in whole tokens)
    BuybackAction:
      type: object
      required:
        - action
        - amount
      properties:
        action:
          type: string
          enum:
            - BUYBACK
          description: Must be "BUYBACK"
        amount:
          type: number
          description: Amount of tokens to buyback (in whole tokens)
    LockAction:
      type: object
      required:
        - action
        - amount
        - vesting
      properties:
        action:
          type: string
          enum:
            - LOCK
          description: Must be "LOCK"
        amount:
          type: number
          description: Amount of tokens to lock (in whole tokens)
        vesting:
          type: object
          description: Vesting parameters for the locked tokens
          additionalProperties: true
    UnlockAction:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum:
            - UNLOCK
          description: Must be "UNLOCK"
    MemoAction:
      type: object
      required:
        - action
        - message
      properties:
        action:
          type: string
          enum:
            - MEMO
          description: Must be "MEMO"
        message:
          type: string
          description: The memo message to attach
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-believe-api-key

````