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.

​
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

Working Examples

Complete code examples for all Solana operations

API Reference

Full API documentation with endpoint details
For additional support, use the Intercom chat widget in the bottom right corner, join our Discord, or reach out via support.