This guide covers common issues you might encounter when working with Solana and OneBalance, along with their solutions.
All TypeScript examples assume you have the required dependencies installed:npm install @solana/web3.js bs58
Wallet Connection Issues
Wallet Not Connected Properly
// Check if wallet is connected and supports signing
if (!wallet.connected || !wallet.signTransaction) {
throw new Error('Wallet not properly connected');
}
Solution: Ensure the wallet is connected and has the required methods before attempting to sign transactions.
Asset Configuration Issues
Invalid Asset IDs
// Ensure you're using correct Solana asset IDs
const SOL_ASSET_ID = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501";
const USDC_SOLANA_ASSET_ID = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
Solution: Use the correct CAIP-19 format for Solana asset identifiers. Check the Aggregated Assets API for supported assets.
Signature Encoding Issues
// Always use base58 encoding for Solana signatures
const signature = bs58.encode(Buffer.from(signedTransaction.signatures[signedTransaction.signatures.length - 1]));
// NOT: signedTransaction.signatures[0].toString()
Solution: Solana signatures must be base58-encoded, not converted to strings.
API Key Configuration Issues
Custom API Key Not Working with Solana
{
"error": "Chain not supported",
"message": "Solana operations not enabled for this API key",
"statusCode": 400
}
Root Cause: Solana support must be explicitly enabled for custom API keys.
Solutions:
-
Contact support to enable Solana:
- Email: support@onebalance.io
- Include your API key prefix (first 6 characters)
- Request “Solana enablement”
-
Use public API key for testing:
# Public test key (development only)
x-api-key: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11
-
Verify enablement with a simple balance check:
curl -X GET 'https://be.onebalance.io/api/v3/balances/aggregated-balance?account=solana:J5CCzBULFax899tcirb6wMbenQUd8whbaetG7EfSick5&aggregatedAssetId=ob:sol' \
-H 'x-api-key: YOUR_API_KEY'
Public Key Limitations: The public API key has rate limits and should only be used for development and testing, never in production.
Common Operation Issues
Insufficient Balance
// Always check balances before creating quotes
const balances = await fetch('/api/v3/balances/aggregated-balance?account=solana:J5CCzBULFax899tcirb6wMbenQUd8whbaetG7EfSick5', {
headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const balanceData = await balances.json();
const availableSOL = balanceData.balanceByAggregatedAsset
.find(asset => asset.aggregatedAssetId === 'ob:sol')?.balance;
if (!availableSOL || parseInt(availableSOL) < requiredAmount) {
throw new Error('Insufficient SOL balance for operation');
}
Solution: Always verify balance before operations to avoid quote failures.
Invalid Account Address
// Ensure Solana addresses are valid base58
import { PublicKey } from '@solana/web3.js';
try {
new PublicKey(accountAddress);
console.log('Valid Solana address');
} catch (error) {
throw new Error('Invalid Solana address format');
}
Solution: Validate Solana addresses using PublicKey constructor before making API calls.
Signing Failures
// Handle wallet connection and signing errors
try {
const signature = await signSolanaOperation(dataToSign, wallet);
} catch (error) {
if (error.code === 4001) {
console.error('User rejected signing');
} else if (error.message?.includes('wallet')) {
console.error('Wallet connection issue:', error.message);
}
throw error;
}
Solution: Handle common wallet errors including user rejection and connection issues.
Contract Call Operation Errors
Missing Delegation Signature (EIP-7702)
{
"error": "Validation failed",
"message": "Delegation signature required for EIP-7702 account. Sign delegation object from prepare-call-quote response.",
"statusCode": 400
}
Solution: Always sign the delegation object from prepare-call-quote before calling call-quote when using EIP-7702 accounts.
Insufficient Balance for Contract Call
// Verify you have enough of the fromAssetId before preparing
const balanceResponse = await fetch(
'https://be.onebalance.io/api/v3/balances/aggregated-balance?aggregatedAssetId=ob:usdc,ob:sol&account=solana:YOUR_ACCOUNT',
{ headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const balance = await balanceResponse.json();
const requiredAsset = balance.balanceByAggregatedAsset.find(b => b.aggregatedAssetId === 'ob:usdc');
if (parseInt(requiredAsset.balance) < requiredAmount) {
throw new Error('Insufficient balance for contract call');
}
Solution: Check aggregated balances before attempting contract calls to ensure sufficient funds.
Invalid Target Chain Configuration
// Ensure target chain supports the contract address
const supportedChains = ['eip155:1', 'eip155:42161', 'eip155:137']; // etc.
if (!supportedChains.includes(targetChain)) {
throw new Error(`Unsupported target chain: ${targetChain}`);
}
Solution: Verify the target chain is supported and the contract address exists on that chain.
Address Lookup Table Issues (SOL Operations)
// SOL operations may fail if lookup tables are unavailable
// This is handled automatically by OneBalance, but can cause delays
console.log('Address lookup tables:', operation.addressLookupTableAddresses);
Solution: SOL operations with complex swaps may require address lookup tables. OneBalance handles this automatically, but it can cause additional processing time.
Multi-Account Operation Debugging
Account Type Mismatch
// Verify account types match your setup
const expectedTypes = ['solana', 'kernel-v3.3-ecdsa'];
const actualTypes = accounts.map(acc => acc.type);
if (!expectedTypes.every(type => actualTypes.includes(type))) {
throw new Error('Missing required account types');
}
Solution: Ensure all required account types are included in multi-account operations.
Signature Order Issues
// Sign operations in the correct order
const signedOps = await Promise.all(
quote.originChainsOperations.map(async (op, index) => {
console.log(`Signing operation ${index + 1} of type: ${op.type}`);
return await signOperation(op);
})
);
Solution: Sign operations in the order they appear in the quote response and handle each operation type appropriately.
Common Debugging Steps
Check Transaction Status
// Check quote execution status
const statusResponse = await fetch(
`https://be.onebalance.io/api/v3/status/get-execution-status?quoteId=${quoteId}`,
{ headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const status = await statusResponse.json();
console.log('Status:', status.status.status);
Validate Account Address
import { PublicKey } from '@solana/web3.js';
// Ensure Solana address is valid
try {
new PublicKey(accountAddress);
console.log('Valid Solana address');
} catch (error) {
throw new Error('Invalid Solana address format');
}
Getting Help
For additional support, use the Intercom chat widget in the bottom right corner, join our Discord, or reach out via support.