Skip to main content
POST
/
v1
/
flywheel
/
batch
/
init
Initialize Batch Transaction
curl --request POST \
  --url https://public.believe.app/v1/flywheel/batch/init \
  --header 'Content-Type: application/json' \
  --header 'x-believe-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '{
  "pipelines": [
    {
      "type": "<string>",
      "payload": "<string>",
      "actions": [
        {
          "action": "BURN",
          "amount": 123
        }
      ]
    }
  ]
}'
{
  "proposalApproveTx": "<string>",
  "batch": {
    "id": "<string>",
    "flywheelId": "<string>",
    "status": "AVAILABLE_TO_QUEUE",
    "pipelines": [
      {
        "type": "<string>",
        "payload": "<string>",
        "actions": [
          {
            "action": "BURN",
            "amount": 123
          }
        ],
        "instructions": [
          "<string>"
        ]
      }
    ],
    "dateCreated": "2023-11-07T05:31:56Z"
  }
}

​
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

FieldTypeRequiredDescription
pipelinesArrayYesArray of pipeline objects containing actions to execute.

​
Pipeline Object

FieldTypeRequiredDescription
typestringYesThe type identifier for this pipeline (e.g., “WATCH_AD”, “PRODUCT_PURCHASE”).
payloadstringYesJSON string containing the proof data for this pipeline.
actionsArrayYesArray of action objects to execute in this pipeline.

​
Action Types

​
BURN Action

Burns a specified amount of tokens.
FieldTypeRequiredDescription
actionstringYesMust be “BURN”
amountnumberYesAmount of tokens to burn (in whole tokens)

​
AIRDROP Action

Sends tokens to a specified wallet address.
FieldTypeRequiredDescription
actionstringYesMust be “AIRDROP”
toAddressstringYesSolana wallet address to send tokens to
amountnumberYesAmount of tokens to airdrop (in whole tokens)

​
BUYBACK Action (Coming Soon)

Executes a token buyback operation.
FieldTypeRequiredDescription
actionstringYesMust be “BUYBACK”
amountnumberYesAmount of tokens to buyback (in whole tokens)
Note: BUYBACK action is not yet implemented.

​
LOCK Action (Coming Soon)

Locks tokens with vesting parameters.
FieldTypeRequiredDescription
actionstringYesMust be “LOCK”
amountnumberYesAmount of tokens to lock (in whole tokens)
vestingObjectYesVesting parameters for the locked tokens
Note: LOCK action is not yet implemented.

​
UNLOCK Action (Coming Soon)

Unlocks previously locked tokens.
FieldTypeRequiredDescription
actionstringYesMust be “UNLOCK”
Note: UNLOCK action is not yet implemented.

​
MEMO Action

Adds a memo message to the transaction.
FieldTypeRequiredDescription
actionstringYesMust be “MEMO”
messagestringYesThe 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:
FieldTypeDescription
proposalApproveTxstringBase64-encoded serialized transaction that must be signed with your registered wallet address (the one used during flywheel registration)
batchObjectThe 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

  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 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_INIT_FAILED500Failed to compile pipelines or initialize the batch transaction.
ERR_FLYWHEEL_ACTIONS_EMPTY400One or more pipelines contain no actions.
ERR_FLYWHEEL_INVALID_ACTION400One or more actions in the pipelines are invalid or unsupported.
ERR_FLYWHEEL_NO_INSTRUCTIONS400Pipeline compilation resulted in no transaction instructions.
ERR_FLYWHEEL_PIPELINE_TOO_BIG400Pipeline 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.

Response

Successful batch initialization.

​
proposalApproveTx
string
required

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

​
batch
object
required