​
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:
Terminal
curl -X 'GET' \
  'https://be.onebalance.io/api/assets/list' \
  -H 'x-api-key: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11'
A public API key is available for testing purposes with limited usage: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11
For production use, use the Intercom chat widget in the bottom right corner or contact 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. Calls made over plain HTTP will fail. API requests without authentication will also fail. Learn more in our 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:
Terminal
https://be.onebalance.io/api
See our 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.

​
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:
Terminal
X-RateLimit-Limit: 400
X-RateLimit-Remaining: 397
X-RateLimit-Reset: 1678364102
Learn more in the 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:
Error Response
{
  "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 documentation for more information.

​
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
// 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 documentation for details.

​
How do I work with aggregated assets?

Aggregated assets are OneBalance’s unified representation of tokens across multiple chains. For example, ds:usdc represents USDC across all supported networks. Key endpoints for working with aggregated assets: Learn more about how aggregated assets work in our Aggregated Assets guide.

​
How do I track transaction status?

OneBalance provides transaction tracking through our Status API: Understanding the Transaction Lifecycle will help you better interpret status responses and execution paths.

​
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: 
{
  "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 calls and RPC methods. See our troubleshooting guide.

​
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: 
{
  "from": {
    "accounts": [{
      "type": "solana",
      "accountAddress": "J5CCzBULFax899tcirb6wMbenQUd8whbaetG7EfSick5"
    }],
    "asset": { "assetId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501" },
    "amount": "10000000"
  }
}
Key v3 endpoints:

​
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: 
{
  "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
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 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: 
{
  "accounts": [{
    "type": "solana",
    "accountAddress": "J5CCzBULFax899tcirb6wMbenQUd8whbaetG7EfSick5"
  }]
}