Getting Started

​

Welcome to Flywheel

​

How Flywheel Works

​

The Concept

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

​

Initial Funding (Required)

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)

• 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

​

1. Register Flywheel (One-time Setup)

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

​

2. Initialize Batch

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

​

3. Execute Batch

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

​

Optional: Monitor Status

• GET /v1/flywheel/batch/{batchId} - Check specific batch
• GET /v1/flywheel/batch/current - Check current batch for tokens

​

Complete Example Walkthrough

​

Step 1: Register Your Flywheel

1. Navigate to: 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

// 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

// 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

async function handlePurchase(customerId, productId, amount) {
  // 1. Initialize batch with burn + airdrop actions
  const batchInit = await fetch("/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("/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 via the web app
2. Fund your vault with SOL and project tokens
3. Review Use Cases for specific implementation patterns
4. Check 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