Initialize Batch Transaction

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

{
  "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)

{
  "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

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.
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.
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.
Action Limitations: Currently, only BURN, AIRDROP, and MEMO actions are fully implemented. BUYBACK, LOCK, and UNLOCK actions are coming soon.
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

{
  "error": "ERR_FLYWHEEL_PIPELINE_TOO_BIG",
  "message": "Pipeline has too many actions to fit in a single transaction"
}

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

Array of flywheel pipelines to compile into batch transaction.

pipelines

object[]

required

Array of pipeline objects containing actions to execute.

Show child attributes

pipelines.type

string

required

The type identifier for this pipeline (e.g., "WATCH_AD", "PRODUCT_PURCHASE").

pipelines.payload

string

required

JSON string containing the proof data for this pipeline.

pipelines.actions

object[]

required

Array of action objects to execute in this pipeline.

Show child attributes

pipelines.actions.action

enum<string>

required

Must be "BURN"

Available options:

BURN

pipelines.actions.amount

number

required

Amount of tokens to burn (in whole tokens)

Response

Successful batch initialization.

proposalApproveTx

string

required

Base64-encoded serialized transaction that must be signed with your registered wallet address.

batch

object

required

Show child attributes

batch.id

string

required

The unique batch identifier (UUID).

batch.flywheelId

string

required

The flywheel this batch belongs to.

batch.status

enum<string>

required

Current batch status.

Available options:

AVAILABLE_TO_QUEUE,

FINALIZED,

EXECUTED,

FAILED

batch.pipelines

object[]

required

Array of compiled pipeline objects.

Show child attributes

batch.pipelines.type

string

required

The type identifier for this pipeline.

batch.pipelines.payload

string

required

JSON string containing the proof data for this pipeline.

batch.pipelines.actions

object[]

required

Array of action objects to execute in this pipeline.

Show child attributes

batch.pipelines.actions.action

enum<string>

required

Must be "BURN"

Available options:

BURN

batch.pipelines.actions.amount

number

required

Amount of tokens to burn (in whole tokens)

batch.pipelines.instructions

string[]

required

Array of base64-encoded Solana transaction instructions.

batch.dateCreated

string<date-time>

required

ISO 8601 timestamp when the batch was created.

API Documentation

Flywheel V1

Tokenomics (Deprecated)

Initialize Batch Transaction

Overview

Authentication

Rate Limiting

Request Body

Pipeline Object

Action Types

BURN Action

AIRDROP Action

BUYBACK Action (Coming Soon)

LOCK Action (Coming Soon)

UNLOCK Action (Coming Soon)

MEMO Action

Example Request

Response Body

Example Response (Success)

Important Notes

Error Codes

Example Error Response

Authorizations

Headers

Body

Response

API Documentation

Flywheel V1

Tokenomics (Deprecated)

​Overview

​Authentication

​Rate Limiting

​Request Body

​Pipeline Object

​Action Types

​BURN Action

​AIRDROP Action

​BUYBACK Action (Coming Soon)

​LOCK Action (Coming Soon)

​UNLOCK Action (Coming Soon)

​MEMO Action

​Example Request

​Response Body

​Example Response (Success)

​Important Notes

​Error Codes

​Example Error Response

Authorizations

Headers

Body

Response

Overview

Authentication

Rate Limiting

Request Body

Pipeline Object

Action Types

BURN Action

AIRDROP Action

BUYBACK Action (Coming Soon)

LOCK Action (Coming Soon)

UNLOCK Action (Coming Soon)

MEMO Action

Example Request

Response Body

Example Response (Success)

Important Notes

Error Codes

Example Error Response