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 developers@bitso.com for more information on custom API rate limits for your account.

Notation

Our documentation uses the following terminology:

• Major: Denotes the primary currency in the trade, usually the base currency (the first currency in the pair). It represents the quantity being bought or sold.
• Minor: Denotes the secondary currency, usually the quote currency (the second currency in the pair). It represents the equivalent value in the base currency.
• Major_Minor: It is how our APIs always refer to an order book, for instance, btc_mxn.

Example

Let's take the MXN/Digital Dollars (USDC) currency pair as an example:

If you buy 5,000 MXN/USDC, the amounts break down as follows:

• Major amount: 5,000 MXN (the base currency you are trading).
• Minor amount: The equivalent in USDC, calculated using the exchange rate

If the exchange rate is MXN/USDC = 0.050, then: 5,000 MXN × 0.050 = 250 USDC (minor amount)

It means you are exchanging 5,000 Mexican Pesos for 250 Digital Dollars at the given exchange rate.

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.