Get Current Batch

Overview

The Get Current Batch endpoint retrieves the currently active flywheel batch for a specified token. This is useful for checking if there’s already an ongoing batch operation before creating a new one, or for getting the status of the current batch without needing to know the specific batch ID. Returns null if no current batch exists for the token.

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 second per API key.

Request

This endpoint requires no request body. The current batch is determined based on the authenticated API key.

Example Request

GET /v1/flywheel/batch/current
x-believe-api-key: your_actual_api_key_here

Response Body

On success, the API returns either:

A JSON object containing the current batch information (same structure as /batch/{batchId})
null if no current batch exists for the token

Example Response (Current Batch Exists)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "flywheelId": "flywheel_abc123",
  "tokenId": "token_def456",
  "mintAddress": "So11111111111111111111111111111111111111112",
  "status": "FINALIZED",
  "batchIndex": "42",
  "vaultIndex": "0",
  "multisig": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "vaultAddress": "HF8dF3nXy48op4dgdNPc86vqG79JTta7wvEbAWW8NXKv",
  "initResult": {
    "total": 3,
    "totalSuccessful": 3,
    "totalFailed": 0,
    "successfulExecutions": [
      {
        "bundleId": "a1b2c3d4e5f6789012345678901234567890abcdef",
        "txHashes": ["3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1JqJ8LoX2GbM4aC9eR", "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC"]
      }
    ],
    "batchIndex": 42
  },
  "dateCreated": "2025-01-27T12:00:00.000Z",
  "dateUpdated": "2025-01-27T12:05:00.000Z"
}

Example Response (No Current Batch)

null

Batch Status Values

When a current batch exists, it will have one of these status values:

Status	Description
`AVAILABLE_TO_QUEUE`	Batch has been created but not yet finalized for execution.
`FINALIZED`	Batch has been finalized and is ready for execution approval.
`EXECUTED`	Batch has been successfully executed (may still be “current” briefly).
`FAILED`	Batch execution failed.

Use Cases

Pre-Creation Check: Verify no active batch exists before creating a new one.
Status Monitoring: Get the current batch status without needing to store batch IDs.
Workflow Management: Determine if your application should wait for current operations to complete.
Error Recovery: Check if a batch is stuck in a particular state and needs intervention.
Dashboard Display: Show users the current state of their token’s flywheel operations.

Integration Patterns

Before Creating New Batch

// Check for current batch before creating new one
const currentBatch = await getCurrentBatch(tokenId);

if (currentBatch) {
  if (currentBatch.status === "FINALIZED") {
    // Wait for execution or execute it
    console.log("Batch ready for execution:", currentBatch.id);
  } else if (currentBatch.status === "EXECUTED") {
    // Previous batch completed, safe to create new one
    await createNewBatch(pipelines);
  } else {
    // Batch still in progress
    console.log("Batch in progress:", currentBatch.status);
  }
} else {
  // No current batch, safe to create new one
  await createNewBatch(pipelines);
}

Status Monitoring Loop

// Monitor current batch until completion
let currentBatch;
do {
  currentBatch = await getCurrentBatch(tokenId);
  if (currentBatch && currentBatch.status === "FINALIZED") {
    console.log("Batch ready for execution");
    break;
  }
  await sleep(5000); // Wait 5 seconds
} while (currentBatch && currentBatch.status !== "EXECUTED");

Error Codes

The current batch endpoint can return specific error codes.

Error Code	Status	Description
`ERR_BATCH_CURRENT_FAILED`	500	Failed to retrieve current batch information.

Example Error Response

{
  "error": "ERR_BATCH_CURRENT_FAILED",
  "message": "Database connection failed"
}

Important Notes

Null Response: A null response is normal and indicates no current batch exists for the token.
Current Definition: A batch is considered “current” if it’s the most recent batch that hasn’t reached a final state.
State Transitions: Once a batch reaches EXECUTED or FAILED status, it may no longer be considered “current” depending on your implementation.
Race Conditions: In high-frequency applications, check for current batch immediately before creating new ones to avoid conflicts.
Token Scoping: This endpoint only returns batches for the specific token ID provided, ensuring proper isolation between different tokens.

Authorizations

x-believe-api-key

string

header

required

Response

Current batch information or null if no current batch exists.

string

required

The unique batch identifier (UUID).

flywheelId

string

required

The flywheel this batch belongs to.

tokenId

string

required

The token ID associated with this batch.

mintAddress

string

required

The Solana mint address for the token.

status

enum<string>

required

Current batch status.

Available options:

AVAILABLE_TO_QUEUE,

FINALIZED,

EXECUTED,

FAILED

batchIndex

string

required

The multisig batch index used for execution.

vaultIndex

string

required

The vault index within the multisig.

multisig

string

required

The multisig wallet address.

vaultAddress

string

required

The vault address for token operations.

dateCreated

string<date-time>

required

ISO 8601 timestamp when the batch was created.

dateUpdated

string<date-time>

required

ISO 8601 timestamp when the batch was last updated.

initResult

object

Results from the batch initialization process (optional).

Show child attributes

executeResult

object

Results from the batch execution process (optional).

Show child attributes

API Documentation

Flywheel V1

Tokenomics (Deprecated)

Overview

Authentication

Rate Limiting

Request

Example Request

Response Body

Example Response (Current Batch Exists)

Example Response (No Current Batch)

Batch Status Values

Use Cases

Integration Patterns

Before Creating New Batch

Status Monitoring Loop

Error Codes

Example Error Response

Important Notes

Authorizations

Response

API Documentation

Flywheel V1

Tokenomics (Deprecated)

​Overview

​Authentication

​Rate Limiting

​Request

​Example Request

​Response Body

​Example Response (Current Batch Exists)

​Example Response (No Current Batch)

​Batch Status Values

​Use Cases

​Integration Patterns

​Before Creating New Batch

​Status Monitoring Loop

​Error Codes

​Example Error Response

​Important Notes

Authorizations

Response

Overview

Authentication

Rate Limiting

Request

Example Request

Response Body

Example Response (Current Batch Exists)

Example Response (No Current Batch)

Batch Status Values

Use Cases

Integration Patterns

Before Creating New Batch

Status Monitoring Loop

Error Codes

Example Error Response

Important Notes