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

​
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"
  }]
}