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