VoidAI Bridge SDK

TypeScript SDK for VoidAI Bridge - Cross-chain asset bridging and routing across Bittensor, Ethereum, Solana, and other supported chains.

🎯 What is VoidAI Bridge SDK?

The VoidAI Bridge SDK provides a unified interface to:

• Bridge assets between chains (TAO ↔ wTAO, Alpha ↔ wAlpha, cross-chain transfers)
• Route transactions via SWAP, BRIDGE, or CCIP operations
• Estimate fees before executing transactions
• Connect wallets (Bittensor, Ethereum/MetaMask, Solana/Phantom)
• Build EVM transactions automatically for bridge burn operations

Perfect for building DeFi applications, cross-chain DEXs, or any app that needs to move assets between Bittensor, EVM chains, and Solana.

📦 Installation

npm install @voidaisdk/bridge-sdk
# or
yarn add @voidaisdk/bridge-sdk
# or
pnpm add @voidaisdk/bridge-sdk

Requirements

• Node.js: ≥ 18 (for backend usage)
• Browser: Modern browsers with ES6+ support
• API Key: Get your VoidAI Bridge API key from the VoidAI Console

🚀 Quick Start

1. Initialize the SDK

import { BridgeSDK } from '@voidaisdk/bridge-sdk';

const sdk = new BridgeSDK({
    apiKey: process.env.VOIDAI_API_KEY!,
    environment: 'testnet', // 'devnet' | 'testnet' | 'mainnet'
});

// Wait for authentication & API key validation
await sdk.ready;

Backend? Use BridgeSDKServer instead – it requires apiKey + secretKey and has no wallet integrations. See Backend Usage below.

2. Fetch Supported Chains & Assets

// Get all active chains
const chains = await sdk.api.getSupportedChains({
    isActive: true,
    isCcipSupported: true,
});

// Get assets (optionally filtered by chain)
const assets = await sdk.api.getAssetList('ETHEREUM_SEPOLIA');

3. Connect Wallets (Browser Only)

// Connect MetaMask
const ethAccount = await sdk.wallets.ethereum.connect();
console.log('Connected:', ethAccount.address);

// Connect Bittensor wallet (Talisman/Subwallet/Polkadot.js)
const bittensorAccount = await sdk.wallets.bittensor.connect();
console.log('Connected:', bittensorAccount.address);

// Connect Phantom (Solana)
const solanaAccount = await sdk.wallets.solana.connect();
console.log('Connected:', solanaAccount.address);

4. Execute a Bridge Operation

// Bridge TAO from Bittensor to Ethereum
const result = await sdk.bridge.bridge({
    fromWallet: '5DqAEsZi...', // Bittensor address
    toWallet: '0x742d35...', // Ethereum address
    fromToken: 'tao',
    toToken: 'wtao',
    fromChain: 'BITTENSOR',
    toChain: 'ETHEREUM_SEPOLIA',
    amount: 1.0,
});

console.log('Bridge identifier:', result.identifier);

// For EVM burn flows (wTAO → TAO), use the pre-built transaction
if (result.evmTransaction) {
    const txHash = await window.ethereum.request({
        method: 'eth_sendTransaction',
        params: [
            {
                from: ethAccount.address,
                to: result.evmTransaction.to,
                data: result.evmTransaction.data,
                value: result.evmTransaction.value,
            },
        ],
    });
    console.log('Transaction sent:', txHash);
}

5. Route a Swap Transaction

const route = await sdk.bridge.routeSwap({
    operationType: 'SWAP',
    originAssetId: 1,
    destinationAssetId: 2,
    fromAddress: '0xSource...',
    toAddress: '0xDestination...',
    amount: 0.5,
});

if (route.success && route.data) {
    // Execute via MetaMask
    await window.ethereum.request({
        method: 'eth_sendTransaction',
        params: [
            {
                from: '0xSource...',
                to: route.data.to,
                data: route.data.data,
                value: route.data.value,
            },
        ],
    });
}

6. Estimate Fees

// Bridge fee estimate
const bridgeFee = await sdk.bridge.getBridgeFeeEstimate({
    fromToken: 'tao',
    toToken: 'wtao',
    amount: 2.5,
});

console.log('Bridge fee:', bridgeFee.data.fee);
console.log('Recipient will receive:', bridgeFee.data.recipientAmount);

// Router swap fee estimate
const swapFee = await sdk.bridge.getRouterSwapFeeEstimate({
    originAssetId: 1,
    destinationAssetId: 2,
    amount: 0.75,
    operationType: 'SWAP',
    toAddress: '0xDestination...',
});

console.log('Total fee:', swapFee.totalFee);

📚 Documentation

📖 Full Documentation - Complete API reference, guides, and examples

• Getting Started – Installation, authentication, configuration
• Wallets – Bittensor, EVM, Solana wallet connections
• Bridge Operations – Cross-chain bridging
• Router Swaps – Token swaps via VoidAI Router
• CCIP Routing – Cross-chain CCIP operations
• Transactions – History, cancel, confirm
• Server-Side Usage – Backend integration with BridgeSDKServer
• API Reference – SDK methods and types
• FAQ – Frequently asked questions
• Error Handling – Troubleshooting and error codes

💡 Key Features

✅ Multi-Chain Support

• Bittensor (TAO, Alpha)
• Ethereum (Mainnet, Sepolia)
• Base (Mainnet, Sepolia)
• Solana
• More chains added regularly

✅ Wallet Integration

• Bittensor: Talisman, Subwallet, Polkadot.js
• Ethereum: MetaMask
• Solana: Phantom

✅ Bridge Operations

• TAO ↔ wTAO (Bittensor ↔ Ethereum)
• Alpha ↔ wAlpha
• Cross-chain asset transfers
• Automatic EVM transaction building for burn operations

✅ Routing & Swaps

• Unified route-transaction API
• SWAP, BRIDGE, and CCIP operations
• Fee estimation before execution

✅ Frontend vs Backend

• BridgeSDK – Frontend usage (apiKey only, no secretKey)
• BridgeSDKServer – Backend usage (apiKey + secretKey for JWT auth, no wallets)

✅ Production Ready

• TypeScript-first with full type definitions
• Automatic JWT refresh on token expiry
• Normalized error messages
• Environment-aware configuration
• Works in Node.js and browsers

🖥️ Backend Usage (Node.js)

For server-side or backend integrations, use BridgeSDKServer with both apiKey and secretKey:

import { BridgeSDKServer } from '@voidaisdk/bridge-sdk';

const sdk = new BridgeSDKServer({
    apiKey: process.env.VOIDAI_API_KEY!,
    secretKey: process.env.VOIDAI_SECRET_KEY!,
    environment: 'mainnet', // 'devnet' | 'testnet' | 'mainnet'
});

await sdk.ready;

// Same bridge/api API, no wallets
const chains = await sdk.api.getSupportedChains();
const result = await sdk.bridge.bridge({
    /* ... */
});

BridgeSDKServer exposes config, api, bridge, and ready – no wallets (use BridgeSDK in frontend for that).

🔧 Environment Configuration

The SDK supports three environments. The base URL and EVM bridge contract address are set per environment in the SDK config.

| Environment | Base URL | Bridge Contract (EVM) | Use Case | | ----------- | ------------------------------------------------------ | ------------------------------------------- | -------------------------- | | devnet | https://api-sdk-dev.voidai.envistudios.com/api | 0x6266ce15aC4f32F096Ff91881dd887a0F4bBa569 | Development & testing | | testnet | https://sdk-backend.voidai.com/sdk | 0x4aA4396BfD6F268b427077079800F420dF947b63 | Staging / pre-production | | mainnet | https://sdk.voidai.com/sdk | 0x604e8Ef901C0E69E79463D997ba7D0724A909b84 | Production |

📝 Example: Complete Bridge Flow

import { BridgeSDK } from '@voidaisdk/bridge-sdk';

async function bridgeTAO() {
    // 1. Initialize SDK
    const sdk = new BridgeSDK({
        apiKey: process.env.VOIDAI_API_KEY!,
        environment: 'testnet', // or 'mainnet' for production
    });

    await sdk.ready;

    // 2. Connect wallets
    const bittensorAccount = await sdk.wallets.bittensor.connect();
    const ethAccount = await sdk.wallets.ethereum.connect();

    // 3. Estimate fees
    const fee = await sdk.bridge.getBridgeFeeEstimate({
        fromToken: 'tao',
        toToken: 'wtao',
        amount: 1.0,
    });

    console.log(`Fee: ${fee.data.fee}, You'll receive: ${fee.data.recipientAmount}`);

    // 4. Execute bridge
    const result = await sdk.bridge.bridge({
        fromWallet: bittensorAccount.address,
        toWallet: ethAccount.address,
        fromToken: 'tao',
        toToken: 'wtao',
        fromChain: 'BITTENSOR',
        toChain: 'ETHEREUM_SEPOLIA',
        amount: 1.0,
    });

    console.log('Bridge initiated:', result.identifier);

    // 5. Execute on-chain transaction (if EVM burn flow)
    if (result.evmTransaction) {
        const txHash = await window.ethereum.request({
            method: 'eth_sendTransaction',
            params: [
                {
                    from: ethAccount.address,
                    ...result.evmTransaction,
                },
            ],
        });
        console.log('On-chain tx:', txHash);
    }
}

bridgeTAO().catch(console.error);

🛠️ Development

Build

# Build for Node.js
npm run build

# Build for browser
npm run build:browser

# Build both
npm run build:all

Test

npm test

Lint

npm run lint

📁 Project Structure

bridge-sdk/
├── src/                    # SDK source code
│   ├── api/               # HTTP client
│   ├── config.ts          # Configuration
│   ├── core/              # Bridge domain logic
│   ├── types/             # TypeScript types
│   ├── utils/             # Utilities
│   ├── wallet/            # Wallet integrations
│   └── index.ts           # Main entry point
├── dist/                  # Compiled SDK (Node.js)
├── dist-browser/          # Browser bundle
├── docs/                  # Full documentation (mdBook)
├── test/                  # Test suite
├── examples/              # Example applications
│   └── frontend/          # Frontend demo app
└── package.json

🌐 Browser Usage

ES Modules

<script type="module">
    import { BridgeSDK } from './node_modules/@voidaisdk/bridge-sdk/dist-browser/voidai-sdk.js';

    const sdk = new BridgeSDK({
        apiKey: 'your-api-key',
        environment: 'mainnet', // 'devnet' | 'testnet' | 'mainnet'
    });
</script>

Bundler (Webpack/Vite/Rollup)

import { BridgeSDK } from '@voidaisdk/bridge-sdk';

// Use normally - bundler will handle it
const sdk = new BridgeSDK({ apiKey, environment: 'mainnet' }); // 'devnet' | 'testnet' | 'mainnet'

⚠️ Error Handling

The SDK throws Error instances with user-friendly messages:

try {
    await sdk.bridge.bridge({
        /* ... */
    });
} catch (error) {
    // error.message contains a clear, actionable message
    console.error('Bridge failed:', error.message);

    // Common errors:
    // - "Session expired or unauthorized..." → Check API key
    // - "Failed to execute bridge swap" → Check parameters
    // - "User rejected the connection request" → User cancelled wallet
}

See Error Handling Guide for detailed patterns.

🔐 Security Best Practices

• ✅ Never commit API keys - Use environment variables
• ✅ Use BridgeSDKServer for backend - Pass secretKey only in server code; use BridgeSDK (no secretKey) in frontend
• ✅ Validate user inputs before passing to SDK
• ✅ Keep dependencies updated - Monitor security advisories

See Full Documentation for more guidance.

📖 Examples

Check out the example frontend app for a complete integration example including:

• SDK initialization
• Wallet connections
• Bridge operations
• Swap routing
• Fee estimation
• Error handling

🤝 Support

• Documentation: Full docs
• Issues: GitHub Issues
• FAQ: FAQ

📄 License

MIT

🙏 Contributing

Contributions are welcome! Please ensure all tests pass before submitting a pull request.

# Run tests
npm test

# Run linter
npm run lint

# Build before committing
npm run build:all