> ## 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.

# FAQ: API

> Common questions about OneBalance API usage, authentication, rate limits, error handling, and integration patterns

## How can I generate an API access token?

The OneBalance API uses API keys to authenticate requests. All API requests require authentication using an API key passed in the `x-api-key` header:

```bash Terminal theme={null}
curl -X 'GET' \
  'https://be.onebalance.io/api/assets/list' \
  -H 'x-api-key: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11'
```

<Tip>
  A public API key is available for testing purposes with limited usage:
  **42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11**
</Tip>

For production use, use the **Intercom chat widget** in the bottom right corner or contact [support@onebalance.io](mailto:support@onebalance.io) to get your custom API token with higher rate limits and full access to all features.

All API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP will fail. API requests without authentication will also fail.

Learn more in our [Authentication](/api-reference/authentication) guide.

## What is a base URL?

OneBalance API is built on REST principles and is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

The Base URL for all API endpoints is:

```bash Terminal theme={null}
https://be.onebalance.io/api
```

See our [API Reference Introduction](/api-reference/introduction) for more details.

## How to fix CORS errors?

OneBalance API implements Cross Origin Resource Sharing (CORS) to allow requests from browsers on different domains.

CORS is generally handled by the server, not the client. If you're experiencing CORS errors in your browser application, you have several options:

1. **Use a server-side proxy** - Create a backend service that makes requests to OneBalance API and returns the data to your frontend
2. **Implement a middleware in Next.js** - If using Next.js, create route handlers that proxy the requests to the API
3. **Contact us** - Use the Intercom chat widget or email support if you need your domain allowed for direct browser access

Learn more about CORS in the [API Reference](/api-reference/cors).

## What are the rate limits?

The OneBalance API implements rate limiting to ensure fair usage and availability of the service for all users:

* Public API Key: 100 requests per minute
* Authenticated Users: 400 requests per minute

If you exceed the rate limit, the API will return a `429 Too Many Requests` response. To handle rate limits effectively, monitor the rate limit headers in your API responses:

```bash Terminal theme={null}
X-RateLimit-Limit: 400
X-RateLimit-Remaining: 397
X-RateLimit-Reset: 1678364102
```

Learn more in the [Rate Limits](/api-reference/rate-limits) documentation.

## How do I handle API errors?

The API uses standard HTTP status codes to indicate success or failure:

* `2xx` - Success
* `4xx` - Client error (like invalid parameters)
* `5xx` - Server error

For errors, the API returns a JSON response with details about what went wrong:

```json Error Response theme={null}
{
  "id": "some_error_id",
  "error": "ErrorType",
  "message": "A description of what went wrong",
  "statusCode": 400,
  "timestamp": "2024-12-18T14:38:24.793Z",
  "path": "/api/endpoint"
}
```

Always check the `message` field for details on how to resolve the issue, and include the `id` when using the **Intercom chat widget** or contacting support.

See the [Errors](/api-reference/errors) documentation for more information.

## What are quote execution failures and how do I handle them?

Quote execution failures occur when a quote request succeeds (returns 200) but the actual execution fails due to business logic reasons. These failures are marked as `REFUNDED` and include a `failReason` field.

**Common fail reasons include:**

* **SLIPPAGE**: Price moved beyond tolerance
* **TRANSFER\_AMOUNT\_EXCEEDS\_BALANCE**: Insufficient token balance
* **TRANSFER\_AMOUNT\_EXCEEDS\_ALLOWANCE**: Token approval needed
* **ORDER\_EXPIRED**: Quote validity period expired
* **NO\_QUOTES**: No liquidity available for the token pair
* **EXECUTION\_REVERTED**: On-chain execution failed

**How to handle execution failures:**

```typescript theme={null}
const status = await getExecutionStatus(quoteId);

if (status.status === 'REFUNDED' && status.failReason) {
  switch (status.failReason) {
    case 'SLIPPAGE':
      // Retry with higher slippage tolerance
      console.log('Price changed, retrying with updated quote');
      break;
    case 'TRANSFER_AMOUNT_EXCEEDS_BALANCE':
      // Inform user about insufficient balance
      console.log('Insufficient balance for this transaction');
      break;
    case 'TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE':
      // Request token approval
      console.log('Token approval needed');
      break;
    case 'ORDER_EXPIRED':
      // Generate fresh quote
      console.log('Quote expired, generating new quote');
      break;
    default:
      console.log(`Quote failed: ${status.failReason}`);
  }
}
```

For a complete list of fail reasons with detailed explanations, see [Error Codes](/api-reference/error-codes) and [Refund Reasons Guide](/guides/quotes/refund-reasons).

## How can I paginate results?

For endpoints that return large collections of items, the API uses cursor-based pagination. To paginate results:

1. Specify a `limit` parameter to control the number of items per page
2. Use the `continuation` token from the response to fetch the next page

```bash theme={null}
// First request
GET /api/status/get-tx-history?user=0x123...&limit=10

// Next page - use continuation token from previous response
GET /api/status/get-tx-history?user=0x123...&limit=10&continuation=txn_abc123
```

Check the [Pagination](/api-reference/pagination) documentation for details.

## How do I work with aggregated assets?

Aggregated assets are OneBalance's unified representation of tokens across multiple chains. For example, `ob:usdc` represents USDC across all supported networks.

Key endpoints for working with aggregated assets:

* [List Assets](/api-reference/assets/list) - Get all supported aggregated assets
* [Aggregated Balance](/api-reference/balances/aggregated-balance) - Check balances across chains
* [Get Quote](/api-reference/quotes/get-quote) - Create quotes using aggregated assets

Learn more about how aggregated assets work in our [Aggregated Assets](/concepts/aggregated-assets) guide.

## What does `ob:single` mean in API responses?

`ob:single` is a display identifier for non-aggregated tokens in API responses. It appears when you request a quote to a specific CAIP format asset instead of an aggregated asset.

**When you'll see `ob:single`:**

```json theme={null}
{
  "destinationToken": {
    "aggregatedAssetId": "ob:single",
    "assetType": "eip155:59144/erc20:0x1789e0043623282d5dcc7f213d703c6d8bafbb04",
    "amount": "64631578570695154591",
    "fiatValue": "1.78"
  }
}
```

<Info>
  `ob:single` is only a representation identifier. You cannot use it to request quotes or swaps. Use the actual CAIP format asset ID from the `assetType` field instead.
</Info>

**Example scenario:**

When you swap from an aggregated asset to a specific token:

* **From**: `ob:usdc` (aggregated)
* **To**: `eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831` (specific CAIP format)
* **Response shows**: `ob:single` as the `aggregatedAssetId` with the actual token in `assetType`

This helps you identify non-aggregated assets in responses from endpoints like transaction history and quote status.

## How do I track transaction status?

OneBalance provides transaction tracking through our Status API:

* [Get Quote Status](/api-reference/status/get-quote-status) - Track individual quote execution
* [Get Transaction History](/api-reference/status/get-transaction-history) - View complete transaction history

Understanding the [Transaction Lifecycle](/concepts/transaction-lifecycle) will help you better interpret status responses and execution paths.

## What is slippage tolerance and when should I use it?

Slippage tolerance defines the acceptable price movement between quote generation and execution. When prices move beyond your tolerance, the transaction will fail rather than execute at an unfavorable rate.

**When to use slippage tolerance:**

* **High-volume applications** - Reduce operational overhead from failed quotes
* **Volatile market conditions** - Prevent unnecessary failures from minor price movements
* **User-facing applications** - Give users control over their risk tolerance

Add slippage tolerance to any quote request:

```json theme={null}
{
  "from": {
    "account": { "sessionAddress": "0x...", "adminAddress": "0x...", "accountAddress": "0x..." },
    "asset": { "assetId": "ob:usdc" },
    "amount": "1000000"
  },
  "to": {
    "asset": { "assetId": "ob:eth" }
  },
  "slippageTolerance": 100
}
```

Learn more in our [Slippage Tolerance Overview](/guides/slippage/overview).

## What slippage tolerance values should I use?

Slippage tolerance is specified in basis points as a positive integer:

**Recommended values by asset type:**

* **Stablecoins** (USDC ↔ USDT): `10-25` basis points (0.1-0.25%)
* **Major tokens** (ETH ↔ USDC): `50-100` basis points (0.5-1%)
* **Volatile assets** (altcoins): `100-500` basis points (1-5%)

**Start with 100 basis points (1%)** for most use cases, then adjust based on:

* Asset volatility
* Market conditions
* User preferences
* Success rate monitoring

See [working examples](/guides/slippage/examples) for different scenarios and implementation patterns.

## My transactions still fail despite setting slippage tolerance. What should I do?

If transactions continue to fail with slippage tolerance, implement progressive retry logic:

```typescript theme={null}
async function executeWithRetry(baseRequest) {
  const slippageValues = [50, 100, 200]; // 0.5%, 1%, 2%
  
  for (const slippage of slippageValues) {
    try {
      const quote = await getQuote({
        ...baseRequest,
        slippageTolerance: slippage
      });
      
      return await executeQuote(quote);
      
    } catch (error) {
      console.log(`Failed at ${slippage / 100}% slippage`);
      if (slippage === 200) {
        throw error; // Final attempt failed
      }
    }
  }
}
```

**Common causes and solutions:**

* **Slippage too low** → Increase tolerance or use adaptive values
* **Network congestion** → Wait for lower congestion periods
* **Large trade size** → Break into smaller trades
* **Volatile market** → Use higher slippage for volatile periods

Check our [troubleshooting guide](/guides/slippage/troubleshooting) for more solutions.

## EIP-7702 Implementation

### Should I choose EIP-7702 for my app?

**EIP-7702 is designed for apps with existing EOA users.** It provides:

* **Address preservation** - users keep their familiar addresses
* **Single-click experience** with automatic delegation
* **Gas abstraction** - sponsored transactions hide complexity
* **Seamless integration** - existing endpoints remain unchanged

Choose EIP-7702 if you have existing EOA users who need smart account benefits without changing addresses.

### What is the difference between EIP-7702 and ERC-4337 accounts?

**EIP-7702 accounts** (For existing EOA users):

* Use your existing EOA address - users keep familiar addresses
* Seamless user experience with address preservation
* Automatic delegation bundled with first transaction
* Gas abstraction built-in
* Cannot use Resource Locks with EOA-based setup

**ERC-4337 accounts**:

* Use a new Smart Contract Account address
* Established standard with broad compatibility
* More straightforward technical integration
* Full Resource Lock compatibility

### Do users need to do anything special for EIP-7702 accounts?

**No - it's completely automatic.** Users only see their intended action (swap, transfer, etc.). OneBalance automatically bundles the delegation with their first transaction on each chain. From the user's perspective, it's a single click with no gas fees.

### Do I need to change my existing code for EIP-7702?

**No additional engineering work required.** All existing OneBalance endpoints remain unchanged. EIP-7702 support is handled automatically by the platform when you configure your account type:

```json theme={null}
{
  "account": {
    "type": "kernel-v3.3-ecdsa",
    "deploymentType": "EIP7702"
  }
}
```

### What about multi-input scenarios with EIP-7702?

The delegation process currently supports only one source chain asset different from the destination chain asset. For complex scenarios requiring multiple input assets from different chains, you can manually submit delegations ahead of requesting quotes.

**Coverage**: Majority of flows work in single transactions, remainder require manual delegation fallback.

We provide clear code examples for this approach using [viem library](https://viem.sh) calls and RPC methods. See our [troubleshooting guide](/guides/eip-7702/troubleshooting).

### Can I use Resource Locks with EIP-7702?

Not with EOA-based EIP-7702 accounts. Resource Locks require security guarantees that are impossible when users control the private key directly.

However, a **WaaS/Turnkey pathway** is in development that enables Resource Locks with EIP-7702 by using managed wallets with proper security controls.

For applications requiring Resource Locks today, use ERC-4337 accounts.

### Is EIP-7702 production ready?

**Yes, EIP-7702 support is live in production** on all supported EVM chains.

Technical capabilities:

* Majority of cross-chain flows complete in single transactions
* Single-transaction bundling prevents stuck funds
* Works with existing wallet infrastructure
* Supports all EVM chains in OneBalance network

### What are common EIP-7702 use cases?

EIP-7702 is used for:

* **Cross-chain DeFi operations** (lending, DEX, derivatives)
* **Multi-asset transactions** with single-transaction execution
* **EOA migration to smart accounts** without address changes
* **Gas-sponsored transactions** for improved user experience

**Technical scope**: Majority of complex flows can execute in single transactions, with fallback options for edge cases requiring multiple input chains.

## Solana Support

### How do I use Solana with OneBalance?

Solana operations require **v3 API endpoints** which support multiple blockchain accounts. Use the accounts array format with Solana account type:

```json theme={null}
{
  "from": {
    "accounts": [{
      "type": "solana",
      "accountAddress": "J5CCzBULFax899tcirb6wMbenQUd8whbaetG7EfSick5"
    }],
    "asset": { "assetId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501" },
    "amount": "10000000"
  }
}
```

Key v3 endpoints:

* [Get Quote v3](/api-reference/quotes/get-quote-v3) - `POST /api/v3/quote`
* [Execute Quote v3](/api-reference/quotes/execute-quote-v3) - `POST /api/v3/quote/execute`
* [Aggregated Balance v3](/api-reference/balances/aggregated-balance-v3) - `GET /api/v3/balances/aggregated-balance`

### Can I swap between Solana and EVM chains?

Yes! OneBalance supports cross-chain operations between Solana and EVM chains. You can:

* **Solana → EVM**: Swap SOL to USDC on Arbitrum
* **EVM → Solana**: Swap USDC on Ethereum to SOL
* **Multi-account**: Use aggregated balances from both chains

Example cross-chain swap:

```json theme={null}
{
  "from": {
    "accounts": [{ "type": "solana", "accountAddress": "..." }],
    "asset": { "assetId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501" },
    "amount": "10000000"
  },
  "to": {
    "asset": { "assetId": "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831" },
    "account": "eip155:42161:0x895Cf62399bF1F8b88195E741b64278b41EB7F09"
  }
}
```

### How is Solana signing different from EVM?

Solana uses a different transaction signing process:

1. **Data format**: Solana operations provide base64 encoded `dataToSign`
2. **Message format**: Convert to `MessageV0` using `@solana/web3.js`
3. **Transaction format**: Create `VersionedTransaction`
4. **Signature format**: Return base58 encoded signature

```typescript theme={null}
import { MessageV0, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';

// Convert OneBalance data to Solana transaction
const message = MessageV0.deserialize(Buffer.from(dataToSign, 'base64'));
const transaction = new VersionedTransaction(message);

// Sign and encode
const signedTx = await wallet.signTransaction(transaction);
const signature = bs58.encode(Buffer.from(signedTx.signatures[signedTx.signatures.length - 1]));
```

### What Solana tokens are supported?

Currently supported on Solana:

* **SOL** (native token)
* **USDC** (SPL token)

More tokens will be added based on demand. Check our [assets list](/api-reference/assets/list) for the most current supported tokens.

### Are call data operations supported on Solana?

**Not yet.** Call data operations (contract interactions) are coming soon but currently not supported on Solana.

Current Solana support includes:

* ✅ Swaps and transfers
* ✅ Cross-chain operations
* ✅ Balance queries
* 🚧 Call data (coming soon)

### Can I use only Solana accounts without EVM?

Yes! You can use Solana-only operations by providing just a Solana account in the accounts array:

```json theme={null}
{
  "accounts": [{
    "type": "solana",
    "accountAddress": "J5CCzBULFax899tcirb6wMbenQUd8whbaetG7EfSick5"
  }]
}
```