> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebalance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana Troubleshooting

> Common issues and solutions when integrating Solana with OneBalance

This guide covers common issues you might encounter when working with Solana and OneBalance, along with their solutions.

<Info>
  All TypeScript examples assume you have the required dependencies installed:

  ```bash theme={null}
  npm install @solana/web3.js bs58
  ```
</Info>

## Wallet Connection Issues

### Wallet Not Connected Properly

```typescript theme={null}
// 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

```typescript theme={null}
// 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](/api-reference/assets/list) for supported assets.

### Signature Encoding Issues

```typescript theme={null}
// 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

```json theme={null}
{
  "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](mailto:support@onebalance.io)
   * Include your API key prefix (first 6 characters)
   * Request "Solana enablement"

2. **Use public API key for testing**:
   ```bash theme={null}
   # Public test key (development only)
   x-api-key: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11
   ```

3. **Verify enablement** with a simple balance check:
   ```bash theme={null}
   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'
   ```

<Warning>
  **Public Key Limitations**: The public API key has rate limits and should only be used for development and testing, never in production.
</Warning>

## Common Operation Issues

### Insufficient Balance

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// 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)

```json theme={null}
{
  "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

```typescript theme={null}
// 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

```typescript theme={null}
// 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)

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
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

<CardGroup cols={3}>
  <Card title="Solana FAQ" icon="message-question" href="/faq/solana">
    Token discovery, API keys, limitations, and common questions
  </Card>

  <Card title="Working Examples" icon="code" href="/guides/solana/examples">
    Complete code examples for all Solana operations
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Full API documentation with endpoint details
  </Card>
</CardGroup>

<Info>
  For additional support, use the **Intercom chat widget** in the bottom right corner, join our [Discord](https://discord.com/invite/vHkw7rpdT8), or reach out via [support](mailto:support@onebalance.io).
</Info>