Skip to main content
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:
  1. Contact support to enable Solana:
    • Email: support@onebalance.io
    • Include your API key prefix (first 6 characters)
    • Request “Solana enablement”
  2. Use public API key for testing:
    # Public test key (development only)
    x-api-key: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11
    
  3. 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.
I