🪄 Magic Wallet SDK

One-click wallets for the Stacks blockchain - Instant onboarding with upgrade paths to permanent wallets.

Perfect for exploring any dApp without friction. Get users onboarded and transacting in seconds, not minutes.

✨ Features

🚀 One-Click Integration

• Instant wallet creation - No downloads, no setup required
• Auto-funded testnet wallets - Ready to transact immediately
• Seamless dApp connection - oneClickConnect() for instant onboarding
• Smart session management - Returning users connect instantly with quickConnect()
• Manual transaction signing - Users control and approve all transactions

🔒 Secure & User-Friendly

• Client-side security - Private keys never leave the browser
• Session persistence - Wallets persist across browser sessions
• Full transaction support - Send STX, interact with smart contracts
• Multiple export formats - JSON, mnemonic, private key, PDF backup

� Upgrade Path to Permanent Wallets

• Zero-friction migration - Export to Hiro, Xverse, Leather, and more
• Asset preservation - All tokens and NFTs transfer safely
• Guided upgrade flow - Step-by-step migration instructions
• Complete wallet backup - Mnemonic phrases, PDF exports, QR codes

🚀 Quick Start

Installation

npm install magic-wallet-sdk

🪄 One-Click dApp Integration

The fastest way to onboard users - perfect for demos, games, and onboarding flows:

import { MagicWallet } from 'magic-wallet-sdk';

const magicWallet = new MagicWallet({
  network: 'testnet',
  autoFund: true
});

// 🚀 One-click onboarding for new users
const wallet = await magicWallet.oneClickConnect();
console.log('User onboarded! Address:', wallet.address);

// ⚡ Instant connection for returning users  
const existingWallet = await magicWallet.quickConnect();
if (existingWallet) {
  console.log('Welcome back! Address:', existingWallet.address);
}

💸 Start Transacting Immediately

// Wallet is auto-created and funded, but transactions require user approval
const txid = await magicWallet.sendSTX(
  'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
  0.1, // STX amount
  { memo: 'User-approved payment!' }
);
// Note: User will be prompted to approve this transaction

console.log('Transaction sent:', txid);

🎮 Standard dApp Integration

For apps that need more control over the wallet creation process:

// Create wallet manually
const wallet = await magicWallet.createTemporaryWallet();

// Get wallet provider interface for existing dApp integrations
const provider = magicWallet.getWalletProvider();
// Use with existing Stacks.js or other wallet libraries

📚 API Reference

Core Classes

MagicWallet

The main SDK class for wallet management and dApp integration.

const magicWallet = new MagicWallet(config?: MagicWalletConfig);

Configuration

interface MagicWalletConfig {
  network: 'mainnet' | 'testnet' | 'devnet';
  autoFund?: boolean;        // Auto-request faucet funds (testnet only)
  fundAmount?: number;       // Amount in micro-STX (default: 1 STX)
  persistSession?: boolean;  // Save wallet to localStorage (default: true)
  storage?: StorageAdapter;  // Custom storage implementation
}

Key Methods

oneClickConnect()

🚀 NEW! Instant user onboarding - creates wallet, funds it, and returns ready-to-use wallet.

const wallet = await magicWallet.oneClickConnect();
// Perfect for demos, games, and frictionless onboarding
// Note: Creates and funds wallet automatically, but transactions still require user approval

quickConnect()

⚡ NEW! Instant connection for returning users with existing wallets.

const wallet = await magicWallet.quickConnect();
if (wallet) {
  console.log('Welcome back!', wallet.address);
} else {
  // First-time user, use oneClickConnect()
  const newWallet = await magicWallet.oneClickConnect();
}

getWalletProvider()

🔌 NEW! Get a standard wallet provider interface for existing dApp integrations.

const provider = magicWallet.getWalletProvider();
// Compatible with @stacks/connect and other wallet libraries

createTemporaryWallet()

Creates a new temporary wallet with automatic funding (testnet only).

const wallet = await magicWallet.createTemporaryWallet();
// Returns: TemporaryWallet with address, privateKey, and mnemonic

sendSTX(recipient, amount, options?)

Send STX tokens to another address.

const txid = await magicWallet.sendSTX(
  'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
  1.5, // STX amount
  { memo: 'Payment' }
);

exportWallet(format?, options?)

Export wallet data for migration to permanent wallets.

// Export as mnemonic phrase
const mnemonic = magicWallet.exportWallet('mnemonic');

// Export as JSON with metadata
const jsonData = magicWallet.exportWallet('json');

// Export as PDF backup with QR codes
const pdfBlob = magicWallet.exportWallet('pdf', {
  includeQR: true,
  filename: 'my-wallet-backup.pdf'
});

// Formats: 'json' | 'mnemonic' | 'privatekey' | 'pdf'

getUpgradeInstructions(providerId)

Get step-by-step instructions for upgrading to a permanent wallet.

const upgrade = magicWallet.getUpgradeInstructions('hiro');
console.log(upgrade.steps); // Array of instructions
console.log(upgrade.exportData); // Wallet data for import

restoreFromMnemonic(mnemonic)

Restore a wallet from a 12-word mnemonic phrase.

const wallet = await magicWallet.restoreFromMnemonic(
  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
);

🎯 Use Cases

🎮 Gaming & NFT dApps

// Instant player onboarding - no wallet installation required
const magicWallet = new MagicWallet({ 
  network: 'testnet', 
  autoFund: true 
});

// Player can start playing immediately
const player = await magicWallet.oneClickConnect();
console.log('Player ready! Address:', player.address);

// Buy items, earn tokens, mint NFTs instantly
const txid = await magicWallet.sendSTX(gameContract, 0.5, { memo: 'Buy sword' });

// Later: upgrade to permanent wallet to keep assets long-term
magicWallet.showSeedPhraseModal(); // Built-in UI for seed phrase backup

💰 DeFi Protocols & Trading

// Frictionless DeFi onboarding
const defiWallet = new MagicWallet({
  network: 'testnet',
  fundAmount: 5000000 // 5 STX for testing
});

// User can start trading immediately
const trader = await defiWallet.oneClickConnect();

// Immediate liquidity provision, swapping, staking
const swapTx = await defiWallet.sendSTX(dexContract, 2.0, { memo: 'Swap STX->USDC' });

🛠 Developer Tools & Demos

// Perfect for hackathons, MVPs, and prototypes
const demoWallet = new MagicWallet({ 
  network: 'testnet',
  autoFund: true 
});

// Instant demo without asking users to install wallets
const demo = await demoWallet.oneClickConnect();

// Show off your dApp features immediately
console.log('Demo wallet ready with funds:', demo.balance);

🚀 Onboarding Funnels & Education

// Reduce onboarding friction by 90%
const onboardingWallet = new MagicWallet({ network: 'testnet' });

// New users can experience your dApp first
const newUser = await onboardingWallet.oneClickConnect();

// After they're convinced, guide them to permanent wallets
const upgrade = onboardingWallet.getUpgradeInstructions('hiro');
// Show upgrade.steps to guide them through migration

🔄 Wallet Upgrade Flow

1. Export Wallet Data

// Multiple export formats available
const mnemonic = magicWallet.exportWallet('mnemonic');
const jsonBackup = magicWallet.exportWallet('json');
const pdfBackup = magicWallet.exportWallet('pdf', { 
  includeQR: true,
  filename: 'wallet-backup.pdf' 
});

console.log('12-word phrase:', mnemonic);

2. Built-in Seed Phrase UI

// Show secure seed phrase modal with copy/download options
magicWallet.showSeedPhraseModal();
// User can copy phrase or download PDF backup

3. Get Available Providers

const providers = magicWallet.getAvailableProviders();
console.log('Available wallets:', providers);
// Returns: Array of {id, name, installed, downloadUrl} objects

4. Guided Migration

const upgrade = magicWallet.getUpgradeInstructions('hiro');
upgrade.steps.forEach((step, i) => {
  console.log(`${i + 1}. ${step}`);
});

// Example output:
// 1. Install Hiro Wallet from https://wallet.hiro.so/
// 2. Open the wallet and select "Import Wallet"  
// 3. Choose "Import from seed phrase"
// 4. Enter your 12-word recovery phrase: abandon abandon...
// 5. Set up a password for your new wallet
// 6. Your assets are now in a permanent wallet!

🔧 Advanced Usage

Custom Storage

class CustomStorage implements StorageAdapter {
  async getItem(key: string): Promise<string | null> {
    // Your custom storage logic (e.g., encrypted storage)
    return localStorage.getItem(key);
  }
  
  async setItem(key: string, value: string): Promise<void> {
    // Your custom storage logic
    localStorage.setItem(key, value);
  }
  
  async removeItem(key: string): Promise<void> {
    // Your custom storage logic
    localStorage.removeItem(key);
  }
}

const magicWallet = new MagicWallet({
  storage: new CustomStorage()
});

Event Handling

// Listen to wallet events for analytics, UI updates, etc.
magicWallet.on('wallet_created', (event) => {
  console.log('New wallet created:', event.data.wallet.address);
  analytics.track('wallet_created', { address: event.data.wallet.address });
});

magicWallet.on('transaction_broadcast', (event) => {
  console.log('Transaction sent:', event.data.txid);
  showNotification(`Transaction sent: ${event.data.txid}`);
});

magicWallet.on('wallet_exported', (event) => {
  console.log('Wallet exported for upgrade');
  analytics.track('wallet_upgrade_started');
});

magicWallet.on('funds_received', (event) => {
  console.log('Wallet funded:', event.data.amount, 'STX');
  updateBalanceDisplay(event.data.amount);
});

React Integration

import React, { useState, useEffect } from 'react';
import { MagicWallet } from 'magic-wallet-sdk';

function MyDApp() {
  const [wallet, setWallet] = useState(null);
  const [magicWallet] = useState(() => new MagicWallet({ 
    network: 'testnet', 
    autoFund: true 
  }));

  const handleConnect = async () => {
    try {
      // Try quick connect first (returning users)
      let userWallet = await magicWallet.quickConnect();
      
      if (!userWallet) {
        // First-time user, use one-click onboarding
        userWallet = await magicWallet.oneClickConnect();
      }
      
      setWallet(userWallet);
    } catch (error) {
      console.error('Connection failed:', error);
    }
  };

  return (
    <div>
      {!wallet ? (
        <button onClick={handleConnect}>
          🪄 Connect Wallet (Instant)
        </button>
      ) : (
        <div>
          <p>Connected: {wallet.address}</p>
          <button onClick={() => magicWallet.showSeedPhraseModal()}>
            📱 Upgrade to Permanent Wallet
          </button>
        </div>
      )}
    </div>
  );
}

🌍 Networks & Environment

Supported Networks

• 🧪 Testnet (Recommended): Full functionality with automatic faucet funding
• 🔧 Devnet: Local development environment with faucet support
• 🚀 Mainnet: Production environment (manual funding required)

Network Configuration

// Testnet (recommended for development & demos)
const testnetWallet = new MagicWallet({
  network: 'testnet',
  autoFund: true,        // Auto-request testnet STX
  fundAmount: 1000000    // 1 STX (in micro-STX)
});

// Mainnet (production)
const mainnetWallet = new MagicWallet({
  network: 'mainnet',
  autoFund: false        // No auto-funding on mainnet
});

🔒 Security & Best Practices

Security Features

• ✅ Client-side key generation - Private keys never leave the browser
• ✅ Encrypted session storage - Wallet data encrypted before localStorage
• ✅ Secure randomness - Uses Web Crypto API for key generation
• ✅ No server dependencies - Fully decentralized operation

Best Practices

• 🎯 Use for onboarding - Perfect for demos, trials, and initial user experience
• 💰 Limit amounts - Temporary wallets are ideal for small amounts and testing
• 🔄 Encourage upgrades - Guide users to permanent wallets for long-term storage
• 📱 Provide backups - Always offer seed phrase export before users invest significantly

Security Recommendations

// Good: Use for onboarding and small amounts
const demoWallet = new MagicWallet({ 
  network: 'testnet', 
  autoFund: true 
});

// Always provide upgrade path for users with significant assets
if (userBalance > 10) { // More than 10 STX
  magicWallet.showSeedPhraseModal(); // Encourage backup
  const upgrade = magicWallet.getUpgradeInstructions('hiro');
  showUpgradeModal(upgrade.steps);
}

🛠 Development & Examples

Build the SDK

# Install dependencies
npm install

# Build for production
npm run build

# Development with auto-rebuild
npm run dev

Run Examples

Check out the /examples folder for complete integration examples:

• dapp-integration-demo.html - Complete one-click integration demo
• real-sdk-test.html - Feature testing and wallet export demo
• MagicWalletReactDemo.jsx - React component integration
• integration-example.mjs - Node.js usage example

# Serve examples locally
npx serve examples
# Open http://localhost:3000/dapp-integration-demo.html

Testing

# Run one-click integration test
node test-one-click.mjs

# Run comprehensive SDK test
node test-sdk.mjs

# Test wallet creation and funding
npm run test

Example Projects

• 🎮 Gaming dApp - Instant player onboarding with asset earning
• 💱 DeFi demo - Frictionless trading and liquidity provision
• 🎨 NFT marketplace - One-click minting and trading
• 📚 Educational tool - Learn blockchain without setup friction

🤝 Contributing

We welcome contributions! The Magic Wallet SDK is perfect for:

• 🚀 Hackathon projects - Skip wallet setup, focus on your dApp
• 🎮 Gaming integrations - Instant player onboarding
• 💰 DeFi onboarding flows - Reduce user friction by 90%
• 📚 Educational demos - Teach blockchain without barriers
• ⚡ Rapid prototyping - Test ideas without infrastructure setup

Development Setup

git clone <repository-url>
cd magic-wallet-sdk
npm install
npm run build

Guidelines

• Follow TypeScript best practices
• Add examples for new features
• Test on testnet before proposing changes
• Update documentation for API changes

📖 Documentation

• 📋 dApp Integration Guide - Complete integration walkthrough
• 📁 File Structure - SDK architecture overview
• 💻 Examples - Live demos and code samples
• 🧪 Tests - Integration test scripts

📄 License

MIT License - see LICENSE for details.

🔗 Resources & Links

Stacks Ecosystem

• Stacks Documentation - Complete Stacks development guide
• Stacks.js - JavaScript SDK for Stacks
• Clarity Language - Smart contract language for Stacks

Recommended Wallet Partners

• Hiro Wallet - Official Stacks web wallet
• Xverse Wallet - Mobile-first Bitcoin & Stacks wallet
• Leather Wallet - Privacy-focused wallet with advanced features

Developer Tools

• Stacks Explorer - Blockchain explorer for Stacks
• Stacks Faucet - Get testnet STX
• Clarinet - Clarity smart contract development

🚀 Built for the Stacks ecosystem • ⚡ Perfect for Bitcoin L2 development • 🪄 One-click onboarding magic

Reduce user onboarding friction by 90%. Get them playing, trading, and exploring your dApp in seconds, not minutes.