Quick Start Guide
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)
Contact the DeFindex team on Discord to request API access
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/withdrawTypescript 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>headerUsing 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!
Last updated