General

Bitso’s APIs conform to the principles and constraints of the REST architectural style. They rely on the HTTP client-server protocol to fetch resources and have predictable, resource-oriented URLs. The requests and responses are JSON-encoded exclusively, including error responses, and they use traditional HTTP methods to perform actions for a given resource.

HTTP API Responses

Successful API calls return the following JSON response object:

{ "success": true, "payload": {RELEVANT_DATA_HERE} }

Whereas, unsuccessful calls return the JSON response object that follows:

{ "success": false, "error": {"message": ERROR_MESSAGE, "code": ERROR_CODE} }

Number Precision

Responses return decimal numbers as strings to preserve full precision across platforms. Bitso recommends converting your numbers to type string to avoid undesired consequences derived from precision and truncation errors.

Rate Limits

Bitso's APIs establish rate limits based on one-minute windows. The limit for public API requests (no need for authentication) is by IP address, which allows 60 requests per minute (RPM). While the limit is by user account for private API requests, allowing 300 RPM. However, you need to be a verified user to have a 300-RPM limit, and a verified user means the account has fully completed the KYC process.

If you exceed these limits, then the system locks you out for one minute. Continuous one-minute lockouts might result in a 24-hour block. Order cancellations are not subject to API rate limiting.

📘

Custom Limits

Contact [email protected] for more information on custom API rate limits for your account.

Notation

Our documentation uses the following terminology:

• Major: Denotes the cryptocurrency, such as bitcoin (BTC) or ether (ETH).
• Minor: Denotes fiat currencies, such as Mexican peso (MXN).
• Major_Minor: It is how our APIs always refer to an order book, for example, btc_mxn.

Developer Testing Server

When working on integrations, Bitso recommends using our sandbox server before running your code on production. The server's URL is as follows: https://api-sandbox.bitso.com/api/v3/

You can fund accounts on the testing server with Bitcoin Testnet and Ethereum's Ropsten Testnet.

Language Detection

If you use API keys, then the initial detection phase is the language configured in your settings. The language setting defaults to a predefined value depending on your country of residence when you sign up for a Bitso account.

To force a specific language, use the Accept-Language header on your request, which overrides the default setting.

When none of these settings are configured, then the default language is English, en.