🚀Getting Started

fairydust makes it simple to add AI-powered micropayments to your app. Users pay with DUST tokens for AI actions, and you handle everything in the browser—no backend required.

Quick Integration

Get started in just a few lines of code:

<!-- Include fairydust SDK -->
<script src="https://fairydust.fun/sdk/simple.js"></script>
<link rel="stylesheet" href="https://fairydust.fun/sdk/fairydust.css">

<!-- Add components to your HTML -->
<div id="fairydust-account"></div>
<button id="ai-action" class="fairydust-button" data-cost="5">
  Generate with AI
</button>

<script>
// Initialize fairydust
const fairydust = new Fairydust({
    appId: 'YOUR-APP-ID'
});

// The SDK automatically enhances your buttons!
document.getElementById('ai-action').addEventListener('click', () => {
    // This runs after successful payment
    performAIAction();
});
</script>

👤Account Component

The Account Component displays the user's connection status and DUST balance. It's the primary way users interact with their fairydust account.

Basic Usage

<!-- Automatic initialization -->
<div id="fairydust-account"></div>

<!-- Or create programmatically -->
<script>
fairydust.createAccountComponent('#account-widget', {
    onConnect: (user) => console.log('User connected:', user),
    onDisconnect: () => console.log('User disconnected'),
    onBalanceUpdate: (balance) => console.log('Balance:', balance)
});
</script>

Component Props

User Experience

💰Action Button

Action Buttons are the core of fairydust payments. They handle the entire payment flow and execute your AI actions after successful DUST transactions.

Automatic Enhancement

The simplest way to add payments is with automatic button enhancement:

<button class="fairydust-button" data-cost="5" onclick="generateJoke()">
  Tell me a dad joke
</button>

The SDK automatically finds buttons with the fairydust-button class and enhances them with payment functionality.

Programmatic Creation

fairydust.createButtonComponent('#generate-button', {
    dustCost: 5,
    label: 'Generate Recipe',
    onSuccess: (transaction) => {
        console.log('Payment successful:', transaction);
        generateRecipe();
    },
    onError: (error) => {
        console.error('Payment failed:', error);
    }
});

Component Props

Payment Flow

Skip Confirmations

Users can choose to skip payment confirmations for a smoother experience. This setting is stored per-app and remembered across sessions.

🔐Authentication Experience

fairydust uses a smooth two-step authentication process that works with both email and phone numbers.

Authentication Flow

Modal Branding

The authentication modal shows "Powered by fairydust" and explains that new users get 25 DUST for free when they provide their phone or email.

// Programmatic authentication
fairydust.createAuthenticationComponent('#auth-modal', {
    appName: 'Your App Name',
    onSuccess: (authResponse) => {
        console.log('User authenticated:', authResponse.user);
        // Refresh account components
        fairydust.refreshAccountComponents();
    },
    onCancel: () => {
        console.log('Authentication cancelled');
    }
});

Key Features

• Auto-detection: Automatically detects email vs phone number
• Validation: Real-time format validation with helpful error messages
• Auto-focus: Automatically focuses inputs for better UX
• Auto-submit: OTP form submits automatically when complete
• Error handling: Clear error messages that auto-hide
• Back navigation: Users can go back to change their identifier

💳Purchase Experience

When users need more DUST, they'll have a seamless purchase experience integrated directly into your app.

Planned Purchase Flow

Integration Points

// This API is planned for the purchase experience
fairydust.createPurchaseComponent('#purchase-modal', {
    packages: [
        { dust: 100, price: 1.00 },
        { dust: 500, price: 4.00 },
        { dust: 1000, price: 7.00 }
    ],
    onSuccess: (purchase) => {
        console.log('DUST purchased:', purchase);
        // Continue with the original action
    },
    onCancel: () => {
        console.log('Purchase cancelled');
    }
});

📚API Reference

Fairydust Class

The main SDK class for creating and managing components.

Constructor

const fairydust = new Fairydust({
    appId: 'your-app-id',           // Required: Your registered app ID
    apiUrl: 'custom-api-url',       // Optional: Custom API endpoint
    ledgerUrl: 'custom-ledger-url', // Optional: Custom ledger endpoint
    debug: true                     // Optional: Enable debug logging
});

Methods

Events

The SDK dispatches custom events for integration with your app:

// Listen for successful payments
document.addEventListener('fairydust:success', (event) => {
    console.log('Payment successful:', event.detail);
});

// Listen for payment errors
document.addEventListener('fairydust:error', (event) => {
    console.error('Payment failed:', event.detail);
});

CSS Classes

Key CSS classes for styling customization:

Available SDK Files

🎯Next Steps

Ready to add magical AI payments to your app?

Coming Soon

• NPM package: @fairydust/sdk
• React components and hooks
• Sandbox environment for testing
• Builder dashboard for app management
• Webhook notifications for server-side integration
• Advanced purchase flow with multiple payment methods