Quick Start

Get your DeFindex API integration running in under 5 minutes. This guide is for developers who want to integrate yield-generating vaults quickly.

📚 Documentation Hierarchy

Choose your path:

🐶 New to blockchain/Stellar? → Start with beginner-guide.md
🎮 Want to see it working? → Try beginner-example.html
⚡ Experienced developer? → Continue with this Quick Start
📖 Full API reference? → See api.defindex.io/docs

Prerequisites

JavaScript/TypeScript experience
Wallet integration knowledge (Freighter/StellarWalletsKit)
API integration experience
3-5 minutes of your time

🚀 Step 1: Get Your API Key (1 minute)

Go to Generate API Key
You'll receive an API key (starts with sk_)
Copy and store securely

⚠️ Authentication Format

// ✅ CORRECT - Use Bearer authentication
const headers = {
  'Authorization': 'Bearer sk_test_1234567890abcdef',
  'Content-Type': 'application/json'
}

// ❌ WRONG - These will result in 403 Forbidden
const wrongHeaders = {
  'X-API-Key': 'sk_test_1234567890abcdef',    // Wrong header name
  'Authorization': 'sk_test_1234567890abcdef', // Missing 'Bearer'
  'Authorization': 'Bearer sk_expiredApiKey', // Expired key
}

🔧 Step 2: Environment Setup (2 minutes)

const CONFIG = {
    API_BASE_URL: 'https://api.defindex.io',  // Production
    API_KEY: 'sk_your_api_key_here',
    NETWORK: 'testnet', // or 'mainnet'

    // Example vault address (replace with actual vault)
    VAULT_ADDRESS: 'CAQEPGA3XDBZSWHYLBUSH2UIP2SHHTEMXMHFPLIEN6RYH7G6GEGJWHGN',

    // Testnet token addresses
    TOKENS: {
        XLM: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC',
        USDC: 'CBBHRKEP5M3NUDRISGLJKGHDHX3DA2CN2AZBQY6WLVUJ7VNLGSKBDUCM'
    }
};

Quick Testnet Setup

# Get testnet XLM
curl "https://friendbot.stellar.org?addr=YOUR_ADDRESS"

# Get test tokens at:
# https://app.soroswap.finance (testnet mode)

💱 Step 3: Core Integration (2 minutes)

Essential API Flow

4-step process: Get Vault Info → Build Deposit → Sign → Send

// Minimal DeFindex vault client implementation
class DeFindexClient {
    constructor(apiKey, network = 'testnet') {
        this.apiKey = apiKey;
        this.network = network;
        this.baseUrl = 'https://api.defindex.io';
    }

    async apiRequest(endpoint, data, method = 'POST') {
        const url = `${this.baseUrl}${endpoint}?network=${this.network}`;
        const options = {
            method,
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            }
        };

        if (method === 'POST' && data) {
            options.body = JSON.stringify(data);
        }

        const response = await fetch(url, options);

        if (!response.ok) {
            const error = await response.json();
            throw new Error(`API Error: ${error.message}`);
        }

        return response.json();
    }

    // 1. Get vault information
    async getVaultInfo(vaultAddress) {
        return this.apiRequest(`/vault/${vaultAddress}`, null, 'GET');
    }

    // 2. Get user's vault balance
    async getVaultBalance(vaultAddress, userAddress) {
        return this.apiRequest(`/vault/${vaultAddress}/balance?from=${userAddress}`, null, 'GET');
    }

    // 3. Build deposit transaction
    async deposit(vaultAddress, amounts, callerAddress, invest = true, slippageBps = 0) {
        return this.apiRequest(`/vault/${vaultAddress}/deposit`, {
            amounts,
            caller: callerAddress,
            invest,
            slippageBps
        });
    }

    // 4. Build withdraw transaction
    async withdraw(vaultAddress, amounts, callerAddress, slippageBps = 0) {
        return this.apiRequest(`/vault/${vaultAddress}/withdraw`, {
            amounts,
            caller: callerAddress,
            slippageBps
        });
    }

    // 5. Submit signed transaction
    async sendTransaction(signedXdr, launchtube = false) {
        return this.apiRequest('/send', {
            xdr: signedXdr,
            launchtube
        });
    }
}

// Usage Example
const client = new DeFindexClient('sk_your_api_key');

async function executeDeposit() {
    try {
        // 1. Get Vault Info
        const vaultInfo = await client.getVaultInfo(CONFIG.VAULT_ADDRESS);
        console.log('Vault info:', vaultInfo);

        // 2. Check current balance
        const balance = await client.getVaultBalance(CONFIG.VAULT_ADDRESS, userAddress);
        console.log('Current vault shares:', balance.dfTokens);

        // 3. Build deposit transaction (1 XLM)
        const { xdr } = await client.deposit(
            CONFIG.VAULT_ADDRESS,
            [10000000], // 1 XLM (7 decimals)
            userAddress,
            true, // auto-invest
            50 // 0.5% slippage
        );

        // 4. Sign (using your preferred wallet)
        const signedXdr = await signWithWallet(xdr);

        // 5. Send
        const result = await client.sendTransaction(signedXdr);

        console.log('Deposit completed!', result.txHash);
    } catch (error) {
        console.error('Deposit failed:', error);
    }
}

Or you can just use the DeFindex SDK for a more streamlined experience.

Working Examples

📂 Complete examples available:

beginner-example.html - Full interactive tutorial with vault deposit/withdraw
Typescript SDK examples - Available in the DeFindex SDK repository

📤 Advanced Options

Gasless Transactions

// For users without XLM for fees (using Launchtube)
const result = await client.sendTransaction(signedXdr, true);

Custom Transaction Submission

// Submit through your own infrastructure
import { Server } from '@stellar/stellar-sdk';

const server = new Server('https://horizon-testnet.stellar.org');
const result = await server.submitTransaction(signedTransaction);

Request Parameters

Deposit Request

{
    amounts: [10000000],     // Array of amounts for each vault asset (7 decimals for XLM)
    caller: userAddress,     // User's wallet address
    invest: true,           // Auto-invest into strategies (recommended: true)
    slippageBps: 50         // 0.5% slippage tolerance (optional, default: 0)
}

Withdraw Request

{
    amounts: [5000000],      // Array of amounts to withdraw from each asset
    caller: userAddress,     // User's wallet address
    slippageBps: 50         // 0.5% slippage tolerance (optional, default: 0)
}

Send Request

{
    xdr: signedXdr,         // Signed transaction XDR
    launchtube: false       // Set true for gasless transactions
}

❓ Common Issues & Solutions

"403 Forbidden" errors

API key starts with sk_
Using Authorization: Bearer <key> header
Using correct base URL
API key hasn't been revoked

"Insufficient balance"

Ensure wallet has enough tokens for deposit
Check minimum deposit requirements
Verify vault is active and accepting deposits

Network mismatch

// Ensure vault exists on the correct network
const vaultUrl = `${API_BASE_URL}/vault/${vaultAddress}?network=testnet`;

Expected Response Times

/vault/{address}: 1-2 seconds
/vault/{address}/deposit: 2-5 seconds
/send: 3-10 seconds

🚨 Production Considerations

Security

Never expose API keys in frontend code for production
Use environment variables for sensitive data
Implement proper error handling and retry logic

Performance

Add request timeouts (30s recommended)
Implement exponential backoff for retries
Cache quotes for better UX (but respect freshness)

Monitoring

Track transaction success rates
Monitor API response times
Log error patterns for debugging

🎯 Next Steps

Explore full API: api.defindex.io/docs
Add error handling: Implement retry logic and user feedback
Production optimization: Proper state management and caching
Multi-vault support: Integrate multiple vaults and strategies
APY tracking: Use vault APY endpoints for performance metrics

📚 Additional Resources

🔗 API Documentation: api.defindex.io/docs
🌍 Stellar Expert (Testnet): https://stellar.expert/explorer/testnet
🏦 DeFindex Interface: https://app.defindex.io
💬 Discord Support: https://discord.gg/ftPKMPm38f
📚 SDK Documentation: DeFindex SDK

🎉 Ready to build? You now have everything needed for a production-ready DeFindex vault integration!

PreviousIntroduction NextGetting Started with API

Last updated 3 days ago