Most Common Error: Adding approve() calls to your transaction array will cause failures.
OneBalance automatically handles all token approvals through the allowanceRequirements field. Including manual approve() calls in your transaction array conflicts with this system and will cause the request to fail.
wrong-approval-approach.ts
// ❌ WRONG - This will failconst badRequest = { calls: [ { to: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC data: encodeFunctionData({ abi: parseAbi(['function approve(address spender, uint256 amount)']), functionName: 'approve', args: [spenderAddress, amount] }), value: '0' }, { to: spenderAddress, data: actualCallData, value: '0' } ] // This causes "Invalid call data" errors};
This error occurs when the quote structure is modified after preparation. The tamper-proof signature validates the exact quote structure, so any changes will invalidate it.
Common Causes:
JSON key ordering changed during serialization
Extra fields added to the quote object
Quote passed through JSON.stringify/parse incorrectly
Account validation ensures all required addresses are present and properly formatted. Missing or invalid addresses will cause authentication failures during quote preparation.
account-validation.ts
// ✅ Validate account before usingfunction validateAccount(account: Account) { if (!account.sessionAddress || !account.adminAddress || !account.accountAddress) { throw new Error('Missing required account addresses'); } if (!isAddress(account.sessionAddress)) { throw new Error('Invalid session address format'); } if (account.sessionAddress === account.adminAddress) { throw new Error('Session and admin addresses must be different'); } return true;}
This error indicates missing or invalid API key configuration. Verify your environment variables are set correctly.
api-key-check.ts
// Check your API key configurationconst headers = { 'x-api-key': process.env.ONEBALANCE_API_KEY};if (!headers['x-api-key']) { throw new Error('OneBalance API key not configured');}
This error indicates missing or invalid API key configuration. Verify your environment variables are set correctly.
api-key-check.ts
// Check your API key configurationconst headers = { 'x-api-key': process.env.ONEBALANCE_API_KEY};if (!headers['x-api-key']) { throw new Error('OneBalance API key not configured');}
Token amounts must be calculated using the correct decimal places. Using wrong decimals is a common cause of “insufficient balance” or “amount too small” errors.
Common Token Decimals
USDC: 6 decimals
ETH/WETH: 18 decimals
WBTC: 8 decimals
DAI: 18 decimals
Amount Validation
Always use parseUnits() and verify the token’s actual decimals before calculations.
Implement proper status polling to track transaction progress and handle different completion states. This provides users with real-time feedback on their transactions.
status-monitoring.ts
async function waitForTransactionCompletion( quoteId: string, timeoutMs = 60000): Promise<QuoteStatus> { const startTime = Date.now(); while (Date.now() - startTime < timeoutMs) { const status = await apiGet('/status/get-execution-status', { quoteId }); switch (status.status.status) { case 'COMPLETED': return status; case 'FAILED': throw new Error(`Transaction failed: ${status.quoteId}`); case 'REFUNDED': throw new Error(`Transaction refunded - likely amount too small or gas costs too high`); case 'PENDING': // Continue polling await new Promise(resolve => setTimeout(resolve, 2000)); break; default: throw new Error(`Unknown status: ${status.status.status}`); } } throw new Error('Transaction timeout');}
DEX protocols have specific parameter requirements that must be validated before execution. Common issues include expired deadlines and invalid fee tiers.
dex-troubleshooting.ts
// Common Uniswap V3 issuesfunction validateUniswapV3Call(params: any) { // Check deadline is in future const now = Math.floor(Date.now() / 1000); if (params.deadline <= now) { throw new Error('Deadline must be in the future'); } // Validate fee tier const validFees = [100, 500, 3000, 10000]; if (!validFees.includes(params.fee)) { throw new Error(`Invalid fee tier: ${params.fee}`); } // Check recipient matches account if (params.recipient !== account.accountAddress) { console.warn('Recipient does not match account address'); }}
NFT purchases require additional validation for contract addresses and reasonable price limits. This helps prevent accidental overpayments or invalid transactions.
nft-troubleshooting.ts
// Common NFT purchase validationfunction validateNFTPurchase(contractAddress: string, tokenId: string, price: bigint) { if (!isAddress(contractAddress)) { throw new Error('Invalid NFT contract address'); } // Check if price seems reasonable (basic sanity check) const maxReasonablePrice = parseUnits('1000', 6); // $1000 USDC if (price > maxReasonablePrice) { console.warn('Price seems unusually high - please verify'); } return true;}
Run this function before implementing your main logic to verify all components are working correctly. It tests API connectivity, account prediction, and balance retrieval.