### Example GET Request Path Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-status This shows the path for a GET request to retrieve the status of a batch, including a placeholder for the batch ID. This path is used in conjunction with the base URL to form the complete API endpoint. ```text GET /flywheel/batch/550e8400-e29b-41d4-a716-446655440000 ``` -------------------------------- ### Example API Request for Transaction Pipelines Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-init This example shows a complete API request body for processing transaction pipelines. It includes a WATCH_AD pipeline with BURN and AIRDROP actions. ```json { "pipelines": [ { "type": "WATCH_AD", "payload": "{\"adId\":\"123\",\"adProvider\":\"google\",\"platform\":\"ios\"}", "actions": [ { "action": "BURN", "amount": 100 }, { "action": "AIRDROP", "toAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "amount": 50 } ] } ] } ``` -------------------------------- ### Example API Success Response Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-init This is an example of a successful API response, containing a base64-encoded transaction and batch details including pipeline status and creation date. ```json { "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" } } ``` -------------------------------- ### Error Response Example Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-status This JSON object shows an example error response when a batch is not found, including an error code and a descriptive message. ```json { "error": "ERR_BATCH_NOT_FOUND", "message": "Batch not found" } ``` -------------------------------- ### Example API Error Response Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-init This example demonstrates an API error response, specifically for a pipeline that is too large to fit within a single transaction. ```json { "error": "ERR_FLYWHEEL_PIPELINE_TOO_BIG", "message": "Pipeline has too many actions to fit in a single transaction" } ``` -------------------------------- ### Example Error Response (JSON) Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-current This is an example of an error response that might be returned by the batch endpoint, indicating a failure to retrieve current batch information. ```json { "error": "ERR_BATCH_CURRENT_FAILED", "message": "Database connection failed" } ``` -------------------------------- ### Proof Data Example Source: https://believe.mintlify.app/api-reference/glossary Illustrates the structure of proof data used to justify flywheel actions. This data is recorded on-chain for transparency and auditability. ```json { "orderId": "12345", "amount": 99.99, "customerId": "user123" } ``` -------------------------------- ### Burn Tokens Request Body Example Source: https://believe.mintlify.app/api-reference/endpoint/tokenomics/burn An example of the JSON request body for the Burn Tokens API, demonstrating the structure and types of data required for a token burn operation, including proof details. ```JSON { "type": "PRODUCT_BUY", "proof": { "transactionId": "237892372", "value": "100" }, "burnAmount": 10000, "persistOnchain": true } ``` -------------------------------- ### API Key Authentication Example Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-init Demonstrates how to include the API key in the request header for authentication. The API key must possess 'burn' or 'airdrop' scopes to successfully authenticate. ```Header x-believe-api-key: your_actual_api_key_here ``` -------------------------------- ### Example Proof Schema: Product Purchase Source: https://believe.mintlify.app/api-reference/proof-schema A sample JSON schema for product purchase proof data, including essential fields like transaction ID, user ID, product ID, amount, currency, timestamp, and platform. ```json { "transactionId": "txn_abc123", "userId": "user_456", "productId": "prod_789", "amount": 99.99, "currency": "USD", "timestamp": "2025-01-27T12:00:00Z", "platform": "web" } ``` -------------------------------- ### API Key Authentication Header Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-status This example demonstrates how to include the API key in the request header for authentication when calling the 'Get Batch Status' endpoint. The `x-believe-api-key` header is required and should contain a valid API key with `burn` or `airdrop` scopes. ```text x-believe-api-key: your_actual_api_key_here ``` -------------------------------- ### Example Proof Schema: Advertisement Viewing Source: https://believe.mintlify.app/api-reference/proof-schema A sample JSON schema for advertisement viewing proof data, including essential fields like ad ID, user ID, duration, completion rate, platform, and timestamp. ```json { "adId": "ad_123456", "adProvider": "google", "userId": "user_789", "duration": 30, "completionRate": 100, "platform": "mobile", "timestamp": "2025-01-27T12:00:00Z" } ``` -------------------------------- ### Example Request Body for Execute Batch Transaction Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-execute This JSON object shows an example of the request body required for the Execute Batch Transaction endpoint. It specifies the 'batchId' and the 'signedTx', which is the base64-encoded signed transaction. ```json { "batchId": "550e8400-e29b-41d4-a716-446655440000", "signedTx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDAbc9WnXF..." } ``` -------------------------------- ### Burn Batch Tokens Request Body Example Source: https://believe.mintlify.app/api-reference/endpoint/tokenomics/burn-batch This JSON array provides an example of the request body for the /v1/tokenomics/burn-batch endpoint. Each object in the array represents a single token burn operation, including the proof type, proof data, burn amount, and a flag to persist the proof on-chain. ```JSON [\n {\n "type": "PRODUCT_BUY",\n "proof": {\n "transactionId": "237892372",\n "value": "100"\n },\n "burnAmount": 10000,\n "persistOnchain": true\n },\n {\n "type": "PRODUCT_REFUND",\n "proof": {\n "transactionId": "23adadad7892372",\n "value": "100"\n },\n "burnAmount": 10000,\n "persistOnchain": true\n }\n] ``` -------------------------------- ### Get Market Summary Response (Error) Source: https://believe.mintlify.app/api-reference/endpoint/tokenomics/market-summary This JSON object illustrates an error response from the Get Market Summary endpoint, specifically when market data for the provided token address is not found. ```json { "error": "ERR_PRICE_TOKENS_NOT_FOUND", "message": "Token market data not available" } ``` -------------------------------- ### Base58 Encoding Example Source: https://believe.mintlify.app/api-reference/glossary Demonstrates the Base58 encoding format commonly used for Solana transaction signatures and addresses. This format is visible in transaction hashes. ```text 27FG487NDUAnrs79xRaycwtW3pCPb4G4664P2nFfmZkH1EEVJqmRoFEEHzXS6A6V2HsZ2bBU6QgP1JgfRx9cRPKh ``` -------------------------------- ### Get Market Summary Request Source: https://believe.mintlify.app/api-reference/endpoint/tokenomics/market-summary This cURL command demonstrates how to request market summary data for a specific token address. It includes the necessary API key and idempotency key headers. ```curl curl --request GET \ --url https://public.believe.app/v1/tokenomics/market-summary/{address} \ --header 'x-believe-api-key: ' \ --header 'x-idempotency-key: ' ``` -------------------------------- ### Funding the Flywheel Vault Source: https://believe.mintlify.app/api-reference/getting-started To power your flywheel actions, you must fund the generated vault address with SOL for transaction fees and your project's tokens. This example demonstrates sending SOL and project tokens using placeholder functions. ```javascript // Send SOL for transaction fees await sendSol(vaultAddress, 10); // 10 SOL // Send your project tokens await sendTokens(vaultAddress, 1000000); // 1M tokens ``` -------------------------------- ### Get Current Batch Request Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-current This cURL command demonstrates how to make a GET request to the /v1/flywheel/batch/current endpoint to retrieve the current batch information. It includes the necessary API key in the request header for authentication. ```cURL curl --request GET \ --url https://public.believe.app/v1/flywheel/batch/current \ --header 'x-believe-api-key: ' ``` -------------------------------- ### Burn Tokens Success Response Example Source: https://believe.mintlify.app/api-reference/endpoint/tokenomics/burn An example of a successful response from the Burn Tokens API, showing the expected JSON structure with fields like result, hash, txHash, type, and dateBurned. ```JSON { "result": "SUCCESS", "hash": "NEW_HASH_FOR_PRODUCT_BUY_EXAMPLE_TO_BE_CALCULATED", "txHash": "21RHE6MoxjjTHvKZ5X9hgGpS66CT7pikuL1AQmFXVPqHCxt2fQZaoj3WbYrJUzn1KxFNkFSF1Z4v7Mk4PRpWQx3J", "type": "PRODUCT_BUY", "dateBurned": "2025-05-20T01:56:40.169Z" } ``` -------------------------------- ### Handle Content Creation - Social Platform Source: https://believe.mintlify.app/api-reference/use-cases Manages rewards for content creation on a social platform. It calculates rewards based on content type and quality, airdropping tokens to creators. Dependencies include a social API key, vault address, and a function to get user wallets. ```javascript // Handle content creation async function handleContentCreation(creatorId, contentType, quality) { const baseReward = 50; const qualityMultiplier = quality > 0.8 ? 2 : 1; // High quality bonus const rewardAmount = baseReward * qualityMultiplier; const pipeline = { type: "CONTENT_CREATED", payload: JSON.stringify({ creatorId, contentType, qualityScore: quality, timestamp: new Date().toISOString(), }), actions: [ { action: "AIRDROP", toAddress: await getUserWallet(creatorId), amount: rewardAmount, }, ], }; return await executePipeline(pipeline); } ``` -------------------------------- ### Example Proof Schema: User Engagement Source: https://believe.mintlify.app/api-reference/proof-schema A sample JSON schema for user engagement proof data, including essential fields like user ID, action type, streak count, points earned, and timestamp. ```json { "userId": "user_abc", "actionType": "daily_check_in", "streakCount": 7, "pointsEarned": 100, "timestamp": "2025-01-27T12:00:00Z" } ``` -------------------------------- ### Example Error Response Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-execute This JSON object details an error encountered during the batch execution. It includes a specific error code and a descriptive message explaining the failure, such as 'insufficient funds'. ```json { "error": "ERR_BATCH_EXECUTE_FAILED", "message": "Bundle execution failed: insufficient funds" } ``` -------------------------------- ### Authentication Error Example Source: https://believe.mintlify.app/api-reference/error-codes This JSON object represents an authentication error returned by the API, indicating that the API key lacks the necessary scope permissions for the requested operation. ```json { "error": "ERR_KEY_SCOPES_UNAUTHORIZED", "message": "The provided API key doesn't have the required 'burn' scope to access this endpoint" } ``` -------------------------------- ### Transparent Vault Funding Source: https://believe.mintlify.app/api-reference/use-cases Enables community members to contribute tokens to a vault and retrieve funding status information. It requires functions to send tokens, get token balances, and retrieve community contributions. ```javascript const vaultAddress = "flywheel_vault_address_here"; // Community members can send tokens await sendTokens(vaultAddress, amount); // Project updates on funding status async function getFundingStatus() { const balance = await getTokenBalance(vaultAddress); const solBalance = await getSolBalance(vaultAddress); return { tokenBalance: balance, solBalance: solBalance, estimatedOperationsRemaining: balance / averageDailyUsage, communityContributions: await getCommunityContributions(), }; } ``` -------------------------------- ### Handle Viral Post - Social Platform Source: https://believe.mintlify.app/api-reference/use-cases Manages rewards for viral posts on a social platform. It calculates token burns based on interactions and airdrops rewards to creators. Dependencies include a social API key, vault address, and a function to get user wallets. ```javascript // Social platform flywheel (configured via web app) // Setup at https://believe.app/projects: // - Token: social_token_789 // - Daily Burn Limit: 200,000 tokens (high engagement platform) // - Daily Airdrop Limit: 150,000 tokens // - Proof Types: POST_VIRAL, CONTENT_CREATED, ENGAGEMENT_MILESTONE // From web app registration: const socialApiKey = "your_social_api_key"; const socialVaultAddress = "your_social_vault_address"; // Handle viral content async function handleViralPost(postId, creatorId, interactions) { const burnAmount = interactions * 2; // Burn based on engagement const creatorReward = interactions * 5; // Higher reward for creator const pipeline = { type: "POST_VIRAL", payload: JSON.stringify({ postId, creatorId, interactions: { likes: interactions.likes, shares: interactions.shares, comments: interactions.comments, }, totalEngagement: interactions.total, viralThreshold: 1000, timestamp: new Date().toISOString(), }), actions: [ { action: "BURN", amount: burnAmount }, { action: "AIRDROP", toAddress: await getUserWallet(creatorId), amount: creatorReward, }, { action: "MEMO", message: `Viral content reward: ${postId}` }, ], }; return await executePipeline(pipeline); } ``` -------------------------------- ### Example Partial Failure Response Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-execute This JSON object illustrates a partial failure during batch execution. It indicates the total number of transactions, the number successful and failed, details of successful executions, and specific information about the failure, including the index and reason. ```json { "batchId": "550e8400-e29b-41d4-a716-446655440000", "result": { "total": 8, "totalSuccessful": 4, "totalFailed": 4, "successfulExecutions": [ { "bundleId": "d0f38d76f53a94b1fa1a0e2c6be123da7ce634afa87733939e406d39f659e68e", "txHashes": [ "27FG487NDUAnrs79xRaycwtW3pCPb4G4664P2nFfmZkH1EEVJqmRoFEEHzXS6A6V2HsZ2bBU6QgP1JgfRx9cRPKh", "4KkFDQ1MBKHrvsNjbNWDttNdHq4f6bys7T5GUDc7Vb6Uv1hUGDVhHCQamnQFmFjnDTQxga6KMi9Yx6fru2sMucKa", "4E6vzH1ep75ArgxFpoXqWgkPinnuFq4kKp2EMnpjcDXKeW5PSfdqQeSusPaxHjf9qfk9ZGcoZkjvY2SzovGdd3Kf", "4pCsbF58DHVfpUZdzmBKimLrAPNE75cXf82FejmYvvxe2eUEXhBhV4RFV9btayMrLsA8QUY8ABed4MxXDUpoB9L3" ] } ], "failedOnTransactionIndex": 5, "failedStartTransactionIndex": 5, "failedTxMsg": "Bundle execution failed: insufficient funds" } } ``` -------------------------------- ### Example Success Response Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-execute This JSON object represents a successful execution of a batch of transactions. It includes a batch ID, total counts of successful and failed executions, and details of successful executions with their associated transaction hashes. ```json { "batchId": "550e8400-e29b-41d4-a716-446655440000", "result": { "total": 8, "totalSuccessful": 8, "totalFailed": 0, "successfulExecutions": [ { "bundleId": "d0f38d76f53a94b1fa1a0e2c6be123da7ce634afa87733939e406d39f659e68e", "txHashes": [ "27FG487NDUAnrs79xRaycwtW3pCPb4G4664P2nFfmZkH1EEVJqmRoFEEHzXS6A6V2HsZ2bBU6QgP1JgfRx9cRPKh", "4KkFDQ1MBKHrvsNjbNWDttNdHq4f6bys7T5GUDc7Vb6Uv1hUGDVhHCQamnQFmFjnDTQxga6KMi9Yx6fru2sMucKa", "4E6vzH1ep75ArgxFpoXqWgkPinnuFq4kKp2EMnpjcDXKeW5PSfdqQeSusPaxHjf9qfk9ZGcoZkjvY2SzovGdd3Kf", "4pCsbF58DHVfpUZdzmBKimLrAPNE75cXf82FejmYvvxe2eUEXhBhV4RFV9btayMrLsA8QUY8ABed4MxXDUpoB9L3" ] }, { "bundleId": "a3e27f45c92b8d1e0c6f4a8b2d7e9f1c8a4b5e6d9c2f1a7b3e8d4c9f2e5a1b6c", "txHashes": [ "5YL73XMzhRLa9CQe1CqxsW1XVt8W2xqEqj3HjZcmELeR22pGxg7rxojBViPw1U8k1cSTbpnhdvGTD1V8SZKao2kc", "3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1KqJ8LoX2GbM4aC9eR", "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC", "2P5mHnJsVxF8YqRpT9KwE6ZvB8TdN4PqJ7LoX1GbK3vC5sF" ] } ] } } ``` -------------------------------- ### Create and Execute Purchase Batch with Believe API Source: https://believe.mintlify.app/api-reference/getting-started This snippet demonstrates how to handle a customer purchase by initializing a batch with burn and airdrop actions, signing the transaction, and executing the batch using the Believe App API. It requires a valid API key and customer/product details. ```javascript 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); } ``` -------------------------------- ### Get Current Batch Response (No Batch) Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-current This represents the response from the Get Current Batch endpoint when no active batch is found for the specified token. The API returns 'null' in this scenario. ```JSON null ``` -------------------------------- ### Get Market Summary Response (Success) Source: https://believe.mintlify.app/api-reference/endpoint/tokenomics/market-summary This JSON object represents a successful response from the Get Market Summary endpoint, containing various market data points for the requested token address. ```json { "marketCap": 1250000.5, "liquidity": 450000.25, "price": 0.125, "totalSupply": 10000000, "circulatingSupply": 8500000, "address": "So11111111111111111111111111111111111111112", "holder": 1542 } ``` -------------------------------- ### Get Batch Status using cURL Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-status This snippet shows how to retrieve the status of a specific batch using the cURL command. It includes the GET request method, the endpoint URL with a placeholder for the batch ID, and the required API key in the headers. ```bash curl --request GET \ --url https://public.believe.app/v1/flywheel/batch/{batchId} \ --header 'x-believe-api-key: ' ``` -------------------------------- ### Implement E-Commerce Token Utility with JavaScript Source: https://believe.mintlify.app/api-reference/use-cases This JavaScript code demonstrates how to process customer purchases for an e-commerce store using the Believe Mintlify API. It includes functions to handle individual purchases and bulk orders, automatically burning tokens and airdropping loyalty rewards based on the order total. Configuration involves setting up a flywheel with token, wallet, and daily limits. ```javascript // Register flywheel (one-time setup via web app) // Configuration done at https://believe.app/projects: // - Token: ecommerce_token_123 // - Wallet: store_owner_wallet_address // - Daily Burn Limit: 50,000 tokens // - Daily Airdrop Limit: 25,000 tokens // - Scopes: burn, airdrop // - Proof Types: PRODUCT_PURCHASE, BULK_ORDER // After registration, you'll receive: const flywheelApiKey = "your_api_key_from_web_app"; const vaultAddress = "your_vault_address_from_web_app"; // Handle individual purchase async function processPurchase(order) { const burnAmount = Math.floor(order.total * 10); // 10 tokens per $1 const rewardAmount = Math.floor(order.total * 5); // 5 tokens reward per $1 const pipeline = { type: "PRODUCT_PURCHASE", payload: JSON.stringify({ orderId: order.id, customerId: order.customerId, total: order.total, products: order.items.map((item) => ({ id: item.productId, quantity: item.quantity, price: item.price, })), timestamp: new Date().toISOString(), }), actions: [ { action: "BURN", amount: burnAmount }, { action: "AIRDROP", toAddress: order.customerWallet, amount: rewardAmount, }, ], }; return await executePipeline(pipeline); } // Handle bulk orders with higher rewards async function processBulkOrder(order) { if (order.total < 1000) return processPurchase(order); // Use regular flow const burnAmount = Math.floor(order.total * 12); // Higher burn rate const rewardAmount = Math.floor(order.total * 8); // Higher reward rate const pipeline = { type: "BULK_ORDER", payload: JSON.stringify({ orderId: order.id, customerId: order.customerId, total: order.total, bulkDiscount: order.discount, timestamp: new Date().toISOString(), }), actions: [ { action: "BURN", amount: burnAmount }, { action: "AIRDROP", toAddress: order.customerWallet, amount: rewardAmount, }, { action: "MEMO", message: `Bulk order bonus: ${order.total}` }, ], }; return await executePipeline(pipeline); } ``` -------------------------------- ### Get Current Batch Response (Success) Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-current This JSON object represents a successful response from the Get Current Batch endpoint when a batch is active. It contains detailed information about the batch, including its ID, status, associated flywheel and token, mint address, and execution results. ```JSON { "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" } ``` -------------------------------- ### Handle Engagement Batch - Social Platform Source: https://believe.mintlify.app/api-reference/use-cases Processes multiple engagement milestones in a batch for a social platform. It maps engagement data to pipeline structures and executes them using a batch function. Dependencies include user wallet information and reward amounts. ```javascript // Batch multiple engagement actions async function handleEngagementBatch(engagements) { const pipelines = engagements.map((engagement) => ({ type: "ENGAGEMENT_MILESTONE", payload: JSON.stringify({ userId: engagement.userId, milestoneType: engagement.type, value: engagement.value, timestamp: new Date().toISOString(), }), actions: [ { action: "AIRDROP", toAddress: engagement.userWallet, amount: engagement.reward, }, ], })); // Execute multiple pipelines in a single batch return await executeBatch(pipelines); } ``` -------------------------------- ### Initialize Batch Transaction (cURL) Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-init Initializes a batch transaction by sending a POST request to the /v1/flywheel/batch/init endpoint. The request body contains an array of pipelines, each with a type, payload, and a list of actions like BURN. Authentication is handled via x-believe-api-key and x-idempotency-key headers. ```cURL curl --request POST \ --url https://public.believe.app/v1/flywheel/batch/init \ --header 'Content-Type: application/json' \ --header 'x-believe-api-key: ' \ --header 'x-idempotency-key: ' \ --data '{ \ "pipelines": [ \ { \ "type": "", \ "payload": "", \ "actions": [ \ { \ "action": "BURN", \ "amount": 123 \ } \ ] \ } \ ] \ }' ``` -------------------------------- ### Batch Status Response Body Structure Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-status This JSON object represents the successful response from the 'Get Batch Status' endpoint. It contains comprehensive details about the batch, including its ID, status, associated flywheel and token information, and results from initialization and execution processes. ```json { "id": "", "flywheelId": "", "tokenId": "", "mintAddress": "", "status": "AVAILABLE_TO_QUEUE", "batchIndex": "", "vaultIndex": "", "multisig": "", "vaultAddress": "", "initResult": { "total": 123, "totalSuccessful": 123, "totalFailed": 123, "successfulExecutions": [ { "bundleId": "", "txHashes": [ "" ] } ], "failedTxMsg": "", "batchIndex": 123 }, "executeResult": { "total": 123, "totalSuccessful": 123, "totalFailed": 123, "successfulExecutions": [ { "bundleId": "", "txHashes": [ "" ] } ], "failedOnTransactionIndex": 123, "failedStartTransactionIndex": 123, "failedTxMsg": "" }, "dateCreated": "2023-11-07T05:31:56Z", "dateUpdated": "2023-11-07T05:31:56Z" } ``` -------------------------------- ### Finalized Batch Response Source: https://believe.mintlify.app/api-reference/endpoint/flywheel/batch-status This JSON object represents the response when a batch operation has been finalized. It includes details about the batch, initialization results, and timestamps. ```json { "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": ["3M9kLp8sVxT2YhF6bE4CfN7ZvB5TdP1KqJ8LoX2GbM4aC9eR", "7Q6nMjKsEgC8WfYpR2CeL5ZhB3TdN9PqJ4LoX7GbV1bF2sC"] } ], "batchIndex": 42 }, "dateCreated": "2025-01-27T12:00:00.000Z", "dateUpdated": "2025-01-27T12:05:00.000Z" } ``` -------------------------------- ### Handle Subscription Renewal - Subscription Service Source: https://believe.mintlify.app/api-reference/use-cases Manages token utility for subscription renewals. It burns tokens based on the plan's value and rewards loyal customers with tokens. Dependencies include a subscription API key, vault address, and a function to retrieve customer wallets. ```javascript // Subscription flywheel (configured via web app) // Setup at https://believe.app/projects: // - Token: subscription_token_101 // - Daily Burn Limit: 30,000 tokens (monthly cycles) // - Daily Airdrop Limit: 20,000 tokens // - Proof Types: SUBSCRIPTION_RENEWAL, PLAN_UPGRADE, REFERRAL_SUCCESS // From web app registration: const subscriptionApiKey = "your_subscription_api_key"; const subscriptionVaultAddress = "your_subscription_vault_address"; async function handleSubscriptionRenewal( subscriptionId, customerId, plan, monthsRenewed ) { const burnAmount = plan.monthlyPrice * monthsRenewed * 10; const loyaltyReward = monthsRenewed * 100; // Bonus for longer commitments const pipeline = { type: "SUBSCRIPTION_RENEWAL", payload: JSON.stringify({ subscriptionId, customerId, plan: { name: plan.name, monthlyPrice: plan.monthlyPrice, features: plan.features, }, monthsRenewed, totalValue: plan.monthlyPrice * monthsRenewed, timestamp: new Date().toISOString(), }), actions: [ { action: "BURN", amount: burnAmount }, { action: "AIRDROP", toAddress: await getCustomerWallet(customerId), amount: loyaltyReward, }, ], }; return await executePipeline(pipeline); } ``` -------------------------------- ### Flywheel Error Example Source: https://believe.mintlify.app/api-reference/error-codes This JSON object illustrates a flywheel-specific error from the API, signaling that a pipeline exceeds the transaction size limits for a single Solana transaction. ```json { "error": "ERR_FLYWHEEL_PIPELINE_TOO_BIG", "message": "Pipeline contains too many actions to fit in a single transaction" } ``` -------------------------------- ### Create Flywheel Pipeline with Proof Data Source: https://believe.mintlify.app/api-reference/proof-schema Structure a flywheel pipeline by specifying the proof type and its associated payload, along with actions like BURN or AIRDROP. The payload should be a JSON string containing specific proof details. ```json { "type": "WATCH_AD", "payload": "{\"adId\":\"123\",\"adProvider\":\"google\",\"platform\":\"ios\",\"userId\":\"user456\",\"completionTime\":\"2025-01-27T12:00:00Z\"}", "actions": [ { "action": "BURN", "amount": 100 }, { "action": "AIRDROP", "toAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "amount": 50 } ] } ``` -------------------------------- ### Handle Gaming Events with Flywheel API Source: https://believe.mintlify.app/api-reference/use-cases Implement event handling for gaming scenarios using the Flywheel API. This includes managing level progression, tournament victories, and daily logins, with associated token burns and airdrops. ```javascript // Flywheel configuration for gaming (set up via web app) // Configuration at https://believe.app/projects: // - Token: game_token_456 // - Daily Burn Limit: 100,000 tokens (high limit for active gaming) // - Daily Airdrop Limit: 75,000 tokens // - Proof Types: LEVEL_UP, TOURNAMENT_WIN, DAILY_LOGIN, ACHIEVEMENT_UNLOCK // After web app setup: const gamingApiKey = "your_gaming_api_key"; const gamingVaultAddress = "your_gaming_vault_address"; // Handle level progression async function handleLevelUp(playerId, newLevel, experienceGained) { const burnAmount = newLevel * 100; // Progressive burn const rewardAmount = experienceGained * 2; // Experience-based reward const pipeline = { type: "LEVEL_UP", payload: JSON.stringify({ playerId, previousLevel: newLevel - 1, newLevel, experienceGained, totalExperience: await getPlayerExperience(playerId), timestamp: new Date().toISOString(), }), actions: [ { action: "BURN", amount: burnAmount }, { action: "AIRDROP", toAddress: await getPlayerWallet(playerId), amount: rewardAmount, }, ], }; return await executePipeline(pipeline); } // Handle tournament victories async function handleTournamentWin(tournamentId, winnerId, prize) { const burnAmount = prize * 0.1; // Burn 10% of prize value const rewardAmount = prize; // Full prize to winner const pipeline = { type: "TOURNAMENT_WIN", payload: JSON.stringify({ tournamentId, winnerId, prize, participants: await getTournamentParticipants(tournamentId), tournamentType: await getTournamentType(tournamentId), timestamp: new Date().toISOString(), }), actions: [ { action: "BURN", amount: burnAmount }, { action: "AIRDROP", toAddress: await getPlayerWallet(winnerId), amount: rewardAmount, }, { action: "MEMO", message: `Tournament champion: ${tournamentId}` }, ], }; return await executePipeline(pipeline); } // Daily engagement rewards async function handleDailyLogin(playerId, streakCount) { const baseReward = 100; const streakBonus = Math.min(streakCount * 10, 500); // Cap at 500 const rewardAmount = baseReward + streakBonus; // Only airdrop for daily logins, no burn const pipeline = { type: "DAILY_LOGIN", payload: JSON.stringify({ playerId, streakCount, previousLoginDate: await getLastLoginDate(playerId), timestamp: new Date().toISOString(), }), actions: [ { action: "AIRDROP", toAddress: await getPlayerWallet(playerId), amount: rewardAmount, }, ], }; return await executePipeline(pipeline); } ```