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

# Getting Started

> Complete guide to setting up and using the Believe API

## Welcome to Flywheel

The Believe Flywheel API transforms your project's tokenomics into a self-reinforcing cycle where user actions automatically trigger tokens operations, creating sustainable engagement and value.

## How Flywheel Works

### The Concept

Think of a flywheel as a perpetual motion machine for your token economy:

1. **User performs action** (buys product, views ad, engages with content)
2. **Your app calls Flywheel API** with proof of the action
3. **Tokens are automatically burned/airdropped** based on your configuration
4. **Token utility increases**, encouraging more user actions
5. **Cycle continues**, creating sustained engagement

### Security & Transparency

* **Multi-signature protection**: Requires approval from both you and Believe
* **Public vault address**: Anyone can view and verify all transactions
* **Proof-based actions**: Every token operation includes verifiable proof data
* **Daily limits**: Configurable caps prevent excessive token movements

## Funding Your Flywheel

<Warning>
  **Important**: After registering your flywheel, you must fund the vault address with SOL and your project tokens before any actions can be executed.
</Warning>

### Initial Funding (Required)

As the project owner, you're responsible for:

1. **SOL for transaction fees**: Send SOL to cover Solana network fees
2. **Project tokens**: Deposit tokens that will power your flywheel actions
3. **Minimum balances**: Ensure sufficient funds for your planned operations

### Community Funding (Optional)

The flywheel wallet address is **public and transparent**, enabling:

* **Community contributions**: Anyone can send tokens to support your flywheel
* **Transparent operations**: All transactions are visible on Solana explorers
* **Plug-and-play experience**: Community members can "plug" tokens into your flywheel
* **Shared incentives**: More funding enables more rewards and engagement

### Example Funding Strategy

```
Initial Setup:
├── 10 SOL (transaction fees)
├── 1,000,000 PROJECT_TOKENS (for burns/airdrops)
└── Daily limits: 10,000 tokens max

Community Growth:
├── Supporters add more PROJECT_TOKENS
├── Increased capacity for rewards
└── Sustainable long-term operations
```

## API Endpoint Flow

**Base URL**: `https://public.believe.app/v1/`

The Flywheel API follows a specific sequence that ensures security and proper setup:

### 1. Register Flywheel (One-time Setup)

**Platform**: [Believe Web App](https://believe.app/projects)

**When to use**: Only once per project (web app only)

* Sets up your flywheel configuration
* Creates multisig wallet and vault address
* Generates API key with scopes
* Defines proof types for your project

**After registration**: Fund the vault address with SOL + tokens

### 2. Initialize Batch

**Endpoint**: `POST https://public.believe.app/v1/flywheel/batch/init`

**When to use**: Every time you want to execute flywheel actions

* Compile your pipelines into a batch transaction
* Get approval transaction to sign
* Validate all actions and proof data

### 3. Execute Batch

**Endpoint**: `POST https://public.believe.app/v1/flywheel/batch/execute`

**When to use**: After signing the approval transaction

* Process the approved batch
* Execute all pipeline actions
* Receive detailed execution results

### Optional: Monitor Status

**Endpoints**:

* `GET https://public.believe.app/v1/flywheel/batch/{batchId}` - Check specific batch
* `GET https://public.believe.app/v1/flywheel/batch/current` - Check current batch for tokens

## Complete Example Walkthrough

Let's walk through setting up a flywheel for an e-commerce store:

### Step 1: Register Your Flywheel

Registration is now done exclusively through the [Believe web app](https://believe.app/projects):

1. **Navigate to**: [https://believe.app/projects](https://believe.app/projects)
2. **Create or select your project**
3. **Configure your flywheel**:
   * Select your token
   * Provide your wallet address (for signing transactions)
   * Set daily limits (burn/airdrop amounts)
   * Choose API scopes (burn, airdrop, etc.)
   * Define proof types for your use cases
4. **Save configuration** and receive your API key
5. **Note your vault address** for funding

```javascript theme={null}
// After web app registration, you'll have:
const flywheelApiKey = "your_generated_api_key";
const vaultAddress = "your_vault_address_from_web_app";
// Use these for all subsequent API calls
```

### Step 2: Fund Your Vault

```javascript theme={null}
// Send SOL for transaction fees
await sendSol(vaultAddress, 10); // 10 SOL

// Send your project tokens
await sendTokens(vaultAddress, 1000000); // 1M tokens
```

### Step 3: Create and Execute Batches

When a customer makes a purchase:

```javascript theme={null}
async function handlePurchase(customerId, productId, amount) {
  // 1. Initialize batch with burn + airdrop actions
  const batchInit = await fetch("https://public.believe.app/v1/flywheel/batch/init", {
    method: "POST",
    headers: {
      "x-believe-api-key": "your_flywheel_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pipelines: [
        {
          type: "PRODUCT_PURCHASE",
          payload: JSON.stringify({
            customerId,
            productId,
            amount,
            timestamp: new Date().toISOString(),
          }),
          actions: [
            { action: "BURN", amount: 100 },
            { action: "AIRDROP", toAddress: customerId, amount: 50 },
          ],
        },
      ],
    }),
  });

  const { proposalApproveTx, batch } = await batchInit.json();

  // 2. Sign the approval transaction with your registered wallet
  const signedTx = await signTransaction(proposalApproveTx);

  // 3. Execute the batch
  const execution = await fetch("https://public.believe.app/v1/flywheel/batch/execute", {
    method: "POST",
    headers: {
      "x-believe-api-key": "your_flywheel_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      batchId: batch.id,
      signedTx: signedTx,
    }),
  });

  const result = await execution.json();
  console.log("Flywheel executed:", result);
}
```

## Best Practices

### Funding Management

* **Monitor balances**: Check vault SOL and token levels regularly
* **Set up alerts**: Get notified when balances are low
* **Community engagement**: Share vault address for community support
* **Emergency reserves**: Keep extra funds for high-activity periods

### Batch Operations

* **Group related actions**: Combine multiple user actions into single batches
* **Monitor daily limits**: Stay within your configured limits
* **Handle failures gracefully**: Check execution results and retry if needed
* **Use proof data effectively**: Include rich context for auditability

### Security

* **Keep wallet private**: Never share your signing wallet private key
* **Verify transactions**: Always review approval transactions before signing
* **Monitor vault activity**: Watch for unexpected transactions
* **Use appropriate scopes**: Only request API key scopes you need

## Next Steps

1. [**Register your flywheel**](https://believe.app/projects) via the web app
2. **Fund your vault** with SOL and project tokens
3. [**Review Use Cases**](/api-reference/use-cases) for specific implementation patterns
4. [**Check Error Codes**](/api-reference/error-codes) for troubleshooting
5. **Join the community** to share experiences and get support

## Need Help?

* **Technical questions**: Review the detailed endpoint documentation
* **Business strategy**: Explore the use cases for inspiration
* **Troubleshooting**: Check the error codes reference
* **Community**: Connect with other projects using Flywheel

Your flywheel journey starts with a single registration - but grows into a powerful, community-supported tokenomic engine! 🚀