Introduction
The Bitso API allows you to integrate the Bitso trading platform with third party applications, such as trading applications, charting programs, point of sale systems, and much more. Below you will find details on how the system functions, along with examples in common programming languages.
Changelog
2020-06-11
Notification of deprecation of the WS orders channel scheduled to happen on October 1st, 2020
2020-06-10
Add the ability to query a withdrawal by its origin id
GET /v3/withdrawals?origin_ids=<origin_id>,<origin_id>,<origin_id>
2020-06-09
Deprecate /v3/<api_method>/client_id/<client_id>.
GET /v3/order_trades/client_id/<client_id>GET /v3/orders/client_id/<client_id>-<client_id>-<client_id>/DELETE /v3/orders/client_id/<client_id>-<client_id>-<client_id>/
General
HTTP API Responses
Our REST-like APIs will always return a JSON Object.
For successful API calls, our JSON response objects looks like:
{ "success": true,
"payload": {RELEVANT_DATA_HERE}
}
For unsuccessful API calls, our JSON response objects look like:
{
"success": false,
"error": {"message": ERROR_MESSAGE, "code": ERROR_CODE}
}
Developer Testing Server
When working on integrations, we recommend that you use our dev server
before running your code against production. The URL for this server
is https://api-dev.bitso.com/v3/
You can fund accounts on the dev server with Testnet Bitcoin and “Morden” test network Eth.
Notations
Major denotes the cryptocurrency, in our case Bitcoin (BTC) or Ether (ETH).
Minor denotes fiat currencies, in our case Mexican Peso (MXN)
An order book is always referred to in the API as “Major_Minor”. For example: “btc_mxn”
Precision
We return decimal numbers as strings to preserve full precision across platforms. We recommend you also convert your numbers to string in order to avoid undesired consequences from precision and truncation errors.
Rate Limits
Rate limits are based on one minute windows. For public API requests, the limit is by IP address and allows 60 requests per minute. For private API requests, the limit is by user and allows 300 requests per minute. If you exceed these limits, you will get locked out for one minute. Continuous one minute lockouts may result in a 24-hour block. Order cancellations aren’t subject to API rate limiting.
Error Codes
Error codes consist of four digits, first two digits correspond to error categories, the last two digits define specific errors.
Unknown Errors: 01 (HTTP 500)
- 0101: “Unknown Error”
- 0102: “Invalid Ripple Withdrawal”
Authentication Errors: 02 (HTTP 401)
- 0201: Invalid Nonce or Invalid Credentials
- 0202: API key is not authorized to execute the requested method
- 0203: Login token is invalid or expired
- 0204: Incorrect PIN
- 0205: Too many login attempts
- 0206: Invalid nonce type
- 0207: Invalid nonce value
- 0208: Authentication is required to execute requested operation
- 0209: Two Factor authentication required
- 0210: Device authentication required
- 0211: Device authentication failed (Invalid IP or expired Token)
Validation Errors: 03 (HTTP 400)
- 0301: Unknown Order book
- 0302: Incorrect time frame (not ‘hour’ or 'minute’)
- 0303: Required field missing
- 0304: Required field not valid (email, phone_number)
- 0305: Invalid SMS code (would also apply to correct code but not-correct client id)
- 0306: Order side not in (buy, sell)
- 0307: Order type not in (limit, market)
- 0308: Order request cannot include both minor and major
- 0309: Order request must include either minor or major
- 0310: Incorrect WID (non-existent or does not belong to user)
- 0311: Incorrect FID (non-existent or does not belong to user)
- 0312: Incorrect OID (non-existent or does not belong to user)
- 0313: Selected currency not in (mxn, btc, eth)
- 0314: Auto-trade not available for selected currencies
- 0315: Invalid address
- 0316: Invalid Ripple currency
- 0317: Invalid SPEI number
- 0318: Invalid SPEI numeric_ref
- 0319: Invalid SPEI notes_ref
- 0320: Invalid pagination parameters
- 0321: Incorrect TID (non-existent)
- 0322: Not a Valid URL
- 0323: No associated country code
- 0324: Number already in use
- 0325: Phone already verified
- 0326: API key is not active
- 0327: Service unavailable for requesting location
- 0328: Service unavailable for requesting country
- 0329: Market order type must be in (maj, min)
- 0330: Withdrawals locked for this account
- 0331: Invalid referral code for Bitso Transfer
- 0332: Empty PIN
- 0333: PIN locked. Too many attempts
- 0334: Bitso Transfers need either an email, phone_number, or refcode specified
- 0335: Invalid SPEI recipient name
- 0336: No data found for CURP
- 0337: No CURP found for data
- 0338: Multiple CURPs found for data
- 0339: Email is already in use
- 0340: Not supported country
- 0341: Invalid postal code
- 0342: Invalid CVU
- 0343: Incorrect amount
- 0344: Invalid BIND recipient name
- 0345: Quote is expired or invalid
- 0346: You need to agree to the new terms and condition
- 0347: Too many attempts to validate CURP
- 0348: CURP data did not match with user data
- 0349: Already in use
- 0350: Cannot disable a currency with positive balance
- 0351: Unable to generate CVU for user
- 0352: Disposable email not allowed
- 0353: Current withdrawal fee is higher than specified maximum
- 0354: No defined legal operation entity
- 0355: Incorrect hash (non-existent or does not belong to user)
- 0356: Duplicate origin id provided
- 0357: Incorrect origin id (non-existent or does not belong to user)
- 0358: The password must have at least 8 characters
- 0359: The password is too long
- 0360: At least one field is required but none was submitted
- 0361: Two or more fields were submitted when only one is required
- 0362: Invalid callback URL
- 0363: Invalid Transaction ID (Either non-existent or does not belong to the user)
- 0364: Password doesn’t meet security requirements
- 0365: Two factor authentication method is already enabled
- 0366: Two factor authentication method is not enabled
- 0367: Unable to generate quote at the present time
- 0368: Rejected withdrawal to restricted address
System Limit Errors: 04 (HTTP 400)
- 0401: Incorrect price, below the minimum
- 0402: Incorrect price, above than maximum
- 0403: Incorrect major, below the minimum
- 0404: Incorrect major, above the maximum
- 0405: Incorrect minor, below the minimum
- 0406: Incorrect minor, above the maximum
- 0407: Invalid precision
- 0408: Incorrect amount value, it must be a non-zero positive value.
User Limit Error: 05 (HTTP 400)
- 0501: Exceeds user limit for withdrawals
- 0502: Exceeds user limit for deposits
- 0503: Exceeds destination user limit for deposits
- 0504: Exceeds cashout withdrawal limit for phone number
Funds Error: 06 (HTTP 400)
- 0601: Not enough btc funds
- 0602: Not enough mxn funds
Errors related to an account: 07 (HTTP 400)
- 0701: Action not permitted for unverified account
- 0702: Action not permitted for unverified business account
- 0703: For your protection, your withdrawal ability has been suspended
- 0704: A specific feature is disabled as the user has decided to opt-out
- 0705: Your account is currently suspended
- 0706: You must accept the Terms of service
- 0707: 2FA Locked
- 0708: Max attempts reached to perform operation
- 0709: Action not permitted for missing KYC data
- 0710: Password must be updated
- 0711: Verification completed. No missing requirements to fill
- 0712: Error saving user beneficiary
- 0713: Error fetching user beneficiaries
- 0714: Invalid data for user beneficiary
Throttling Errors: 08 (HTTP 420)
- 0801: You have hit the request rate-limit
- 0802: Too many attempts to perform an operation
Unsupported HTTP method (400 error)
- 0901: Unsupported HTTP method
Miscellaneous Errors: 10 (400 error)
- 1000: API temporarily disabled (More info in error message)
- 1001: Too many open orders
- 1002: Unable to process order
- 1003: Operation timeout
- 1004: Deprecated functionality
- 1005: Invalid operation
Operation Errors: 11 (500 error)
- 1101: Error when processing the withdrawal
- 1102: Error registering callback URL
- 1103: System-wide method disabled
Phone related errors: 12 (400 error)
- 1201: The number provided is not a mobile number
- 1202: We cannot send an SMS to the number provided (out of jurisdiction)
- 1299: Unexpected error when trying to send SMS
Client Libraries
The following client libraries will allow you to integrate quickly with our APIs
Language detection
The initial phase of the detection if you are using API keys is the language you have on your settings. (This defaults depending on your country of residence the moment you sign up)
To force this to a specific language we then use Accept-Language header on the request to override this setting.
If none of these settings are set the default is en.
Public REST API
Available Books
curl "https://api.bitso.com/v3/available_books/"
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"book": "btc_mxn",
"minimum_amount": ".003",
"maximum_amount": "1000.00",
"minimum_price": "100.00",
"maximum_price": "1000000.00",
"minimum_value": "25.00",
"maximum_value": "1000000.00"
}, {
"book": "eth_mxn",
"minimum_amount": ".003",
"maximum_amount": "1000.00",
"minimum_price": "100.0",
"maximum_price": "1000000.0",
"minimum_value": "25.0",
"maximum_value": "1000000.0"
}]
}
This endpoint returns a list of existing exchange order books and their respective order placement limits.
HTTP Request
GET https://api.bitso.com/v3/available_books/
JSON Response Payload
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| minimum_amount | String | Minimum amount of major when placing orders | Major |
| maximum_amount | String | Maximum amount of major when placing orders | Major |
| minimum_price | String | Minimum price when placing orders | Minor |
| maximum_price | String | Maximum price when placing orders | Minor |
| minimum_value | String | Minimum value amount (amount*price) when placing orders | Minor |
| maximum_value | String | Maximum value amount (amount*price) when placing orders | Minor |
Ticker
curl "https://api.bitso.com/v3/ticker/?book=btc_mxn"
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"book": "btc_mxn",
"volume": "22.31349615",
"high": "5750.00",
"last": "5633.98",
"low": "5450.00",
"vwap": "5393.45",
"ask": "5632.24",
"bid": "5520.01",
"created_at": "2016-04-08T17:52:31.000+00:00"
}
}
This endpoint returns trading information from the specified book.
HTTP Request
GET https://api.bitso.com/v3/ticker/
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| book | YES | Specifies which book to use |
JSON Response Payload
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| volume | String | Last 24 hours volume | Major |
| high | String | Last 24 hours price high | Minor/Major |
| last | String | Last traded price | Minor/Major |
| low | String | Last 24 hours price low | Minor/Major |
| vwap | String | Last 24 hours volume weighted average price: vwap | Minor/Major |
| ask | String | Lowest sell order | Minor/Major |
| bid | String | Highest buy order | Minor/Major |
| created_at | String | Timestamp at which the ticker was generated | ISO 8601 timestamp |
Order Book
curl "https://api.bitso.com/v3/order_book/?book=btc_mxn"
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"asks": [{
"book": "btc_mxn",
"price": "5632.24",
"amount": "1.34491802"
},{
"book": "btc_mxn",
"price": "5633.44",
"amount": "0.4259"
},{
"book": "btc_mxn",
"price": "5642.14",
"amount": "1.21642"
}],
"bids": [{
"book": "btc_mxn",
"price": "6123.55",
"amount": "1.12560000"
},{
"book": "btc_mxn",
"price": "6121.55",
"amount": "2.23976"
}],
"updated_at": "2016-04-08T17:52:31.000+00:00",
"sequence": "27214"
}
}
curl "https://api.bitso.com/v3/order_book/?book=btc_mxn&aggregate=false"
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"asks": [{
"book": "btc_mxn",
"price": "5632.24",
"amount": "1.34491802",
"oid": "VN5lVpgXf02o6vJ6"
},{
"book": "btc_mxn",
"price": "5633.44",
"amount": "0.4259",
"oid": "RP8lVpgXf04o6vJ6"
},{
"book": "btc_mxn",
"price": "5642.14",
"amount": "1.21642",
"oid": "46efbiv72drbphig"
}],
"bids": [{
"book": "btc_mxn",
"price": "6123.55",
"amount": "1.12560000",
"oid": "11brtiv72drbphig"
},{
"book": "btc_mxn",
"price": "6121.55",
"amount": "2.23976",
"oid": "1ywri0yg8miihs80"
}],
"updated_at": "2016-04-08T17:52:31.000+00:00",
"sequence": "27214"
}
}
This endpoint returns a list of all open orders in the specified book. If the aggregate parameter is set to true, orders will be aggregated by price, and the response will only include the top 50 orders for each side of the book. If the aggregate parameter is set to false, the response will include the full order book.
HTTP Request
GET https://api.bitso.com/v3/order_book/
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| book | YES | Specifies which book to use | |
| aggregate | true | NO | Specifies if orders should be aggregated by price. |
JSON Response Payload
Returns JSON object with “bids” and “asks”. Each is a JSON Array of open orders and each open order is represented as a JSON object
| Field Name | Type | Description |
|---|---|---|
| asks | JSON Array | List of open asks |
| bids | JSON Array | List of open bids |
| updated_at | String | Timestamp at which the order was last updated |
| sequence | Long | Increasing integer value for each order book update. |
Asks and Bids in the aggregated order books are JSON Dictionaries with the following fields:
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| price | String | Price per unit of major | Minor |
| amount | String | Major amount in order | Major |
Asks and Bids in the unaggregated (full) order books are JSON Dictionaries with the following fields:
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| price | String | Price per unit of major | Minor |
| amount | String | Major amount in order | Major |
| oid | String | Order ID |
Trades
curl "https://api.bitso.com/v3/trades/?book=btc_mxn"
The JSON Array returned by the API looks like this:
{
"success": true,
"payload": [{
"book": "btc_mxn",
"created_at": "2016-04-08T17:52:31.000+00:00",
"amount": "0.02000000",
"maker_side": "buy",
"price": "5545.01",
"tid": 55845
}, {
"book": "btc_mxn",
"created_at": "2016-04-08T17:52:31.000+00:00",
"amount": "0.33723939",
"maker_side": "sell",
"price": "5633.98",
"tid": 55844
}]
}
This endpoint returns a list of recent trades from the specified book.
HTTP Request
GET https://api.bitso.com/v3/trades/
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| book | Yes | Specifies which book to use | |
| marker | No | Returns objects that are older or newer (depending on 'sort’) than the object with this ID | |
| sort | desc | No | Specifies ordering direction of returned objects ('asc’, 'desc’) |
| limit | 25 | No | Specifies number of objects to return. (Max is 100) |
JSON Response Payload
Returns descending JSON Array of transactions. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| created_at | String | Timestamp at which the trade was executed | ISO 8601 timestamp |
| amount | String | Major amount transacted | Major |
| maker_side | String | Indicates the maker order side (maker order is the order that was open on the order book) | |
| price | String | Price per unit of major | Minor |
| tid | Long | Trade ID |
Private REST API
The Private REST API is used to manage your account and your orders. These requests must be signed (more on this below).
Generating API Keys
Bitso uses API Keys to allow access to the API. You can register a new Bitso API key at our developer portal.
When setting up a new API, you will need to choose an API Name to identify your API. This name will never be shown anywhere apart from on your API Index page within your account. You have the option of adding a Withdrawal Bitcoin Address, which can be used to lock the API Withdrawal function to a specific Bitcoin address of your choosing. This field is optional.
The two elements you will need to sign requests are:
- Bitso API Key
- Bitso API Secret
Creating and Signing Requests
#!/bin/bash
# requires:
# -httpie: https://github.com/jkbrzt/httpie
URL=https://api.bitso.com/v3/balance/
API_KEY="BITSO_KEY"
API_SECRET="BITSO_SECRET"
DNONCE=$(date +%s)
HTTPmethod=GET
JSONPayload=""
RequestPath="/v3/balance/"
SIGNATURE=$(echo -n $DNONCE$HTTPmethod$RequestPath$JSONPayload | openssl dgst -hex -sha256 -hmac $API_SECRET )
AUTH_HEADER="Bitso $API_KEY:$DNONCE:$SIGNATURE"
http GET $URL Authorization:"$AUTH_HEADER"
// Define your request
var key = "BITSO API KEY";
var secret = "BITSO API SECRET";
var http_method="GET"; // Change to POST if endpoint requires data
var request_path="/v3/balance/"
var json_payload={}; // Needed for POST endpoints requiring data
// Create the signature
var nonce = new Date().getTime();
var message = nonce+http_method+request_path;
var payload = JSON.stringify(json_payload)
if (http_method == "POST")
message += payload;
var crypto = require('crypto');
var signature = crypto.createHmac('sha256', secret).update(message).digest('hex');
// Build the auth header
var auth_header = "Bitso "+key+":" +nonce+":"+signature;
// Send request
var options = {
host: 'api.bitso.com',
path: request_path,
method: http_method,
headers: {
'Authorization': auth_header,
'Content-Type': 'application/json'
}
};
// Send request
var http = require('https');
var req = http.request(options, function(res) {
console.log(`statusCode: ${res.statusCode}`);
console.log(`statusMessage: ${res.statusMessage}`);
res.on('data', function (chunk) {
console.log(`body: ${chunk}`);
});
});
req.on('error', (error) => {
console.error(error)
})
if (http_method == "POST") {
req.write(payload);
}
req.end();
#!/usr/bin/python
import time
import hmac
import hashlib
import requests
import json
bitso_key = "BITSO_KEY"
bitso_secret = "BITSO_SECRET"
http_method = "GET" # Change to POST if endpoint requires data
request_path = "/v3/balance/"
parameters = {} # Needed for POST endpoints requiring data
# Create signature
nonce = str(int(round(time.time() * 1000)))
message = nonce+http_method+request_path
if (http_method == "POST"):
message += json.dumps(parameters)
signature = hmac.new(bitso_secret.encode('utf-8'),
message.encode('utf-8'),
hashlib.sha256).hexdigest()
# Build the auth header
auth_header = 'Bitso %s:%s:%s' % (bitso_key, nonce, signature)
# Send request
if (http_method == "GET"):
response = requests.get("https://api.bitso.com" + request_path, headers={"Authorization": auth_header})
elif (http_method == "POST"):
response = requests.post("https://api.bitso.com" + request_path, json = parameters, headers={"Authorization": auth_header})
print response.content
#!/usr/bin/ruby
require 'date'
require 'json'
require 'openssl'
require 'typhoeus'
bitso_key = "API_KEY"
bitso_secret = "API_SECRET"
nonce = DateTime.now.strftime('%Q')
http_method = "POST"
request_path = "/v3/orders/"
payload_data = {"book" => "btc_mxn",
"side" => "buy",
"major" => ".01",
"price" => "1000",
"type" => "limit"}
json_payload = payload_data.to_json
# Create signature
message = nonce+http_method+request_path+json_payload
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), bitso_secret, message)
# Build the auth header
auth_header = "Bitso #{bitso_key}:#{nonce}:#{signature}"
# Send request
response = Typhoeus::Request.new(
"https://api.bitso.com/v3/orders/",
method: "POST",
body: json_payload,
headers: {"Authorization" => auth_header,
"Content-Type" => "application/json"}
).run
puts response.body
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.math.BigInteger;
import java.net.URL;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.HttpURLConnection;
public class BitsoJavaExample {
public static void main(String[] args) throws Exception {
String bitsoKey = "BITSO API KEY";
String bitsoSecret = "BITSO API SECRET";
long nonce = System.currentTimeMillis();
String HTTPMethod = "GET";
String RequestPath = "/v3/balance/";
String JSONPayload = "";
// Create the signature
String message = nonce + HTTPMethod + RequestPath + JSONPayload;
String signature = "";
byte[] secretBytes = bitsoSecret.getBytes();
SecretKeySpec localMac = new SecretKeySpec(secretBytes, "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(localMac);
byte[] arrayOfByte = mac.doFinal(message.getBytes());
BigInteger localBigInteger = new BigInteger(1, arrayOfByte);
signature = String.format("%0" + (arrayOfByte.length << 1) + "x", new Object[] { localBigInteger });
String authHeader = String.format("Bitso %s:%s:%s", bitsoKey, nonce, signature);
String url = "https://api.bitso.com/v3/balance/";
URL obj = new URL(url);
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestProperty("User-Agent", "Bitso Java Example");
con.setRequestMethod("GET");
con.setRequestProperty("Authorization", authHeader);
// Send request
int responseCode = con.getResponseCode();
System.out.println("\nSending 'GET' request to URL : " + url);
System.out.println("Response Code : " + responseCode);
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
<?php
$bitsoKey = "API_KEY";
$bitsoSecret = "API_SECRET"
$nonce = round(microtime(true) * 1000);
$HTTPMethod = "POST";
$RequestPath = "/v3/orders/";
$JSONPayload = json_encode(['book' => 'btc_mxn',
'side' => 'buy',
'major' => '.01',
'price' => '1000',
'type' => 'limit']);
// Create signature
$message = $nonce . $HTTPMethod . $RequestPath . $JSONPayload;
$signature = hash_hmac('sha256', $message, $bitsoSecret);
// Build the auth header
$format = 'Bitso %s:%s:%s';
$authHeader = sprintf($format, $bitsoKey, $nonce, $signature);
// Send request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.bitso.com/v3/orders/');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $JSONPayload);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: ' . $authHeader,
'Content-Type: application/json'));
$result = curl_exec($ch);
echo $result;
?>
All REST requests should be valid JSON. You must include 3 fields as a payload in the “Authorization” header for all Private API Endpoints in order to perform authentication:
- key – The API Key you generated
- nonce – An integer that must be unique and increasing for each API call (we recommend using a UNIX timestamp)
- signature – See below
Signature
The signature is generated by creating a SHA256 HMAC using the Bitso API Secret on the concatenation of nonce + HTTP method + requestPath + JSON payload (no ’+’ signs in the concatenated string) and hex encode the output. The nonce value should be the same as the nonce field in the Authorization header. The requestPath and JSON payload must, of course, be exactly as the ones used in the request.
Authorization Header
The header should be constructed, using the fields described above, in the following form:
Authorization: Bitso <key>:<nonce>:<signature>
Account Status
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"client_id": "1234",
"first_name": "Claude",
"last_name": "Shannon",
"status": "active",
"daily_limit": "5300.00",
"monthly_limit": "32000.00",
"daily_remaining": "3300.00",
"monthly_remaining": "31000.00",
"cash_deposit_allowance": "5300.00",
"cellphone_number": "verified",
"cellphone_number_stored":"+525555555555",
"email_stored":"[email protected]",
"official_id": "submitted",
"proof_of_residency": "submitted",
"signed_contract": "unsubmitted",
"origin_of_funds": "unsubmitted"
}
}
This endpoint returns information concerning the user’s account status, documents uploaded, and transaction limits.
HTTP Request
GET https://api.bitso.com/v3/account_status/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
JSON Response Payload
Returns a JSON Array. Every element in the array is a JSON object with the following fields.
| Field Name | Type | Description | Units |
|---|---|---|---|
| client_id | String | The user’s Client ID | |
| first_name | String | The user’s first name | |
| last_name | String | The user’s last name | |
| status | String | Total balance | Enum of (active, inactive) |
| daily_limit | String | The user’s total daily limit | MXN |
| daily_remaining | String | Remaining amount of user’s total daily limit | MXN |
| monthly_limit | String | The user’s total monthly limit | MXN |
| monthly_remaining | String | Remaining amount of user’s total monthly limit | MXN |
| cash_deposit_allowance | String | Remaining cash allowance today | MXN |
| cellphone_number | String | Status of user’s registered cellphone number | Enum of (unsubmitted, submitted, verified) |
| cellphone_number_stored | String | user’s registered cellphone number | |
| email_stored | String | user’s registered email | |
| official_id | String | Status of user’s official ID document | Enum of (unsubmitted, submitted, verified, rejected) |
| proof_of_residency | String | Status of user’s 'proof of residency’ document | Enum of (unsubmitted, submitted, verified, rejected) |
| signed_contract | String | Status of user’s 'signed contract’ document | Enum of (unsubmitted, submitted, verified, rejected) |
| origin_of_funds | String | Status of user’s 'origin of funds’ document | Enum of (unsubmitted, submitted, verified, rejected) |
Document Upload
The JSON object returned by the API looks like this:
{
"success": true
}
This endpoint is used to upload KYC documents for verification. [Coming Soon]
HTTP Request
GET https://api.bitso.com/v3/kyc_documents/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| document_type | - | Yes | Specifies what document you are uploading. Enum of (official_id, proof_of_residency, signed_contract, origin_of_fund) |
| filetype | - | Yes | Specifies filetype for this upload. Enum of (jpg, png) |
| file | - | Yes | Base64 encoded binary file. Max size is 7.5MB |
Mobile Phone Number Registration
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"phone": "5552525252"
}
}
This endpoint is used to register Mobile phone number for verification.
HTTP Request
POST https://api.bitso.com/v3/phone_number/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| phone_number | - | Yes | Mobile phone number to register (10 digits) |
JSON Response Payload
Returns a JSON Object with the following fields.
| Field Name | Type | Description | Units |
|---|---|---|---|
| client_id | String | User’s client ID | |
| phone | String | Registered phone number |
Mobile Phone Number Verification
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"phone": "5554181042"
}
}
This endpoint is used to verify a registered mobile phone number
HTTP Request
POST https://api.bitso.com/v3/phone_verification/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| verification_code | - | Yes | Verification code sent to registered mobile number |
JSON Response Payload
Returns a JSON Object with the following fields.
| Field Name | Type | Description | Units |
|---|---|---|---|
| client_id | String | User’s client ID | |
| phone | String | Registered phone number |
Account Balance
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"balances": [{
"currency": "mxn",
"total": "100.1234",
"locked": "25.1234",
"available": "75.0000"
}, {
"currency": "btc",
"total": "4.12345678",
"locked": "25.00000000",
"available": "75.12345678"
}, {
"currency": "eth",
"total": "50.1234",
"locked": "40.1234",
"available": "10.0000"
}]
}
}
This endpoint returns information concerning the user’s balances for all supported currencies.
HTTP Request
GET https://api.bitso.com/v3/balance/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
JSON Response Payload
Returns a JSON Array. Every element in the array is a JSON object with the following fields.
| Field Name | Type | Description | Units |
|---|---|---|---|
| currency | String | Currency symbol | |
| total | String | Total balance | Currency |
| locked | String | Currency balance locked in open orders | Currency |
| available | String | Currency balance available for use | Currency |
Fees
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"fees": [{
"book": "btc_mxn",
"taker_fee_decimal": "0.0001",
"taker_fee_percent": "0.01",
"maker_fee_decimal": "0.0001",
"maker_fee_percent": "0.01"
}, {
"book": "eth_mxn",
"taker_fee_decimal": "0.0001",
"taker_fee_percent": "0.01",
"maker_fee_decimal": "0.0001",
"maker_fee_percent": "0.01"
}],
"withdrawal_fees": {
"btc": "0.001",
"eth": "0.0025"
}
}
}
This endpoint returns information on customer fees for all available order books, and withdrawal fees for applicable currencies.
HTTP Request
GET https://api.bitso.com/v3/fees/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
JSON Response Payload
Returns a JSON object with keys, “fees” and “withdrawal_fees”.
“fees” contains a JSON Array. Every element in the array is a JSON object with the following fields.
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| taker_fee_decimal | String | Customer taker trading fee as a decimal | |
| taker_fee_percent | String | Customer taker trading fee as a percentage | |
| maker_fee_decimal | String | Customer maker trading fee as a decimal | |
| maker_fee_percent | String | Customer maker trading fee as a percentage | |
| fee_decimal | String | DEPRECATED Customer trading fee as a decimal (same as maker_fee_decimal). This was the field used before we had a Maker/Taker fee schedule. | |
| fee_percent | String | DEPRECATED Customer trading fee as a percentage (same as maker_fee_percent). This was the field used before we had a Maker/Taker fee schedule. |
“withdrawal_fees” is an object keyed by each curency and value of net amount withdrawal fees denominated in the corresponding currency.
Ledger
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"eid": "c4ca4238a0b923820dcc509a6f75849b",
"operation": "trade",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "btc",
"amount": "-0.25232073"
}, {
"currency": "mxn",
"amount": "1013.540958479115"
}],
"details": {
"tid": 51756,
"oid": "wri0yg8miihs80ngk"
}
}, {
"eid": "6512bd43d9caa6e02c990b0a82652dca",
"operation": "fee",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "mxn",
"amount": "-10.237787459385"
}],
"details": {
"tid": 51756,
"oid": "19vaqiv72drbphig"
}
}, {
"operation": "trade",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "eth",
"amount": "4.86859395"
}, {
"currency": "mxn",
"amount": "-626.77"
}],
"details": {
"tid": 51757,
"oid": "19vaqiv72drbphig"
}
}, {
"eid": "698d51a19d8a121ce581499d7b701668",
"operation": "fee",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "eth",
"amount": "0.04917771"
}],
"details": {
"tid": 51757,
"oid": "19vaqiv72drbphig"
}
}, {
"eid": "b59c67bf196a4758191e42f76670ceba",
"operation": "funding",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "btc",
"amount": "0.48650929"
}],
"details": {
"fid": "fc23c28a23905d8614499816c3ade455",
"method": "btc",
"funding_address": "18MsnATiNiKLqUHDTRKjurwMg7inCrdNEp"
}
}, {
"eid": "b0baee9d279d34fa1dfd71aadb908c3f",
"operation": "funding",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "mxn",
"amount": "300.15"
}],
"details": {
"fid": "3ef729ccf0cc56079ca546d58083dc12",
"method": "sp"
}
}, {
"eid": "96e79218965eb72c92a549dd5a330112",
"operation": "withdrawal",
"created_at": "2016-04-08T17:52:31.000+00:00",
"balance_updates": [{
"currency": "mxn",
"amount": "-200.15"
}],
"details": {
"wid": "c5b8d7f0768ee91d3b33bee648318688",
"method": "sp"
}
}]
}
Returns a list of all the user’s registered operations.
HTTP Request
GET https://api.bitso.com/v3/ledger/
GET https://api.bitso.com/v3/ledger/trades/
GET https://api.bitso.com/v3/ledger/fees/
GET https://api.bitso.com/v3/ledger/fundings/
GET https://api.bitso.com/v3/ledger/withdrawals/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| marker | No | Returns objects that are older or newer (depending on 'sort’) than the object with this ID | |
| sort | desc | No | Specifies ordering direction of returned objects |
| limit | 25 | No | Specifies number of objects to return. (Max is 100) |
JSON Response Payload
Returns a descending JSON Array of transactions. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| eid | String | Entry ID | - |
| operation | String | Indicates type of operation (funding, withdrawal, trade, fee) | - |
| created_at | String | Timestamp at which the operation was recorded | ISO 8601 timestamp |
| balance_updates | JSON object | Updates to user balances for this operation (See dictionary specification below) | - |
| details | JSON object | Specific operation details | - |
JSON Object for balance_updates
| Field Name | Type | Description | Units |
|---|---|---|---|
| currency | String | Currency for this balance update | - |
| amount | String | Amount added or subtracted to user balance | Currency |
Filter Ledger by operation type
You can specify that the ledger endpoint return only objects that are a specific operation type.
GET https://api.bitso.com/v3/ledger/trades/
GET https://api.bitso.com/v3/ledger/fundings/
GET https://api.bitso.com/v3/ledger/withdrawals/
GET https://api.bitso.com/v3/ledger/fees/
Withdrawals
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"wid": "c5b8d7f0768ee91d3b33bee648318688",
"status": "pending",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "btc",
"method": "Bitcoin",
"amount": "0.48650929",
"details": {
"withdrawal_address": "18MsnATiNiKLqUHDTRKjurwMg7inCrdNEp",
"tx_hash": "d4f28394693e9fb5fffcaf730c11f32d1922e5837f76ca82189d3bfe30ded433"
}
}, {
"wid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "complete",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "sp",
"amount": "2612.70",
"details": {
"beneficiary_name": "BERTRAND RUSSELL",
"beneficiary_bank": "BANAMEX",
"beneficiary_clabe": "002320700708015728",
"numeric_reference": "99548",
"concepto": "Por los 🌮 del viernes",
"clave_rastreo": "BNET01001604080002076841",
"cep": {
"return": {
"cda": {
"cadenaOriginal": "||1|13062016|13062016|172053|40002|STP|Bitso - BERTRAND RUSSELL|40|646180115400000002|BIT140123U70|BANAMEX|BERTRAND RUSSELL|40|002320700708015728|ND|-|0.00|2612.70|00001000000401205824||",
"conceptoPago": "-",
"cuentaBeneficiario": "002320700708015728",
"cuentaOrdenante": "646180115400000002",
"fechaCaptura": "20160613",
"fechaOperacion": "20160613",
"hora": "17:08:42",
"iva": "0.00",
"monto": "2612.70",
"nombreBeneficiario": "BERTRAND RUSSELL",
"nombreInstBeneficiaria": "BANAMEX",
"nombreInstOrdenante": "STP",
"nombreOrdenante": "Bitso - Russell",
"referenciaNumerica": "99548",
"rfcCurpBeneficiario": "ND",
"rfcCurpOrdenante": "BIT140123U70",
"selloDigital": "cd7yUrnmUQ7CG6M+LX7WOZeizOpkTyMlEAunJaP2j5MAaNPZxy+vAJtgiVL73i1LNSrwK10eBb66Rh4\/RxU6AT2S03chQ\/BS1beknH5xPpGQg+wEXeANtnF2lp71lAD6QZ2O0NE4MIDvLhGGjTGklSP+2fS6joTAaV+tLbtrIp8JiR0MOX1rGPC5h+0ZHNvXQkcHJz3s68+iUAvDnQBiSu768b2C4zpHzteGEnJhU8sAdk83spiWogKALAVAuN4xfSXni7GTk9HObTTRdY+zehfWVPdE\/7uQSmMTzOKfPbQU02Jn\/5DdE3gYk6JZ5m70JsUSFBTF\/EVX8hhg0pu2iA==",
"serieCertificado": "",
"tipoOperacion": "C",
"tipoPago": "1"
},
"estadoConsulta": "1",
"url": "http:\/\/www.banxico.org.mx\/cep?i=90646&s=20150825&d=viAKjS0GVYB8qihmG9I%2B9O1VUvrR2td%2Fuo3GyVDn8vBp371tVx5ltRnk4QsWP6KP%2BQvlWjT%2BzfwWWTA3TMk4tg%3D%3D"
}
}
}
}, {
"wid": "of40d7f0768ee91d3b33bee64831jg73",
"status": "complete",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "sp",
"amount": "500.00",
"details": {
"beneficiary_name": "ALFRED NORTH WHITEHEAD",
"beneficiary_bank": "BANAMEX",
"beneficiary_clabe": "5204165009315197",
"numeric_reference": "30535",
"concepto": "-",
"clave_rastreo": "BNET01001604080002076841",
"cep": {
"return": {
"cda": {
"cadenaOriginal": "||1|07042016|07042016|095656|40002|STP|Bitso - Al|40|646180115400000002|BIT140123U70|BANAMEX|ALFRED NORTH WHITEHEAD|3|5204165009315197|ND|-|0.00|500.00|00001000000401205824||",
"conceptoPago": "-",
"cuentaBeneficiario": "5204165009315197",
"cuentaOrdenante": "646180115400000002",
"fechaCaptura": "20160407",
"fechaOperacion": "20160407",
"hora": "09:56:51",
"iva": "0.00",
"monto": "500.00",
"nombreBeneficiario": "ALFRED NORTH WHITEHEAD",
"nombreInstBeneficiaria": "BANAMEX",
"nombreInstOrdenante": "STP",
"nombreOrdenante": "Bitso - RUSSELL",
"referenciaNumerica": "30535",
"rfcCurpBeneficiario": "ND",
"rfcCurpOrdenante": "BIT140123U70",
"selloDigital": "GaXpeaKgkc+gc0w9XgBbRCMmKWLNdSTV5C4CNQ4DL4ZVT+1OBSqNtX\/pv2IGjI7bKjCkaNrKUdaCdFwG6SdZ0nS9KtYSx1Ewg2Irg6x4kSzeHdlzBDr6ygT+bb+weizxcXMARKkciPuSQlyltCrEwSi07yVzachKfcEN8amj2fsEzim7gSyUc3ecKA1n8DX89158fwukKTIg4ECfOLsgueKF8unwbICWHXwRaaxIAA6PVw7O6WwGXxMtMBTCdiT202c8I2SnULFqK9QVJlQ\/YDRXFI4IMMAwGQZWbbmk8gf\/J3Fixy+0lcQV35TBBrbHyFPiaHaRN95yK\/BUxPOhag==",
"serieCertificado": "",
"tipoOperacion": "C",
"tipoPago": "1"
},
"estadoConsulta": "1",
"url": "http:\/\/www.banxico.org.mx\/cep?i=90646&s=20150825&d=3AeATtn9mM9yySMqwClgSTnKIddFN7JVwo38kDBVjOBRtcYVENx1LblV%2BXOHnKEGTfp0g%2BVLM76C3ewQ0c9vpA%3D%3D"
}
},
"folio_origen": "BITSO4405016499736144"
}
}]
}
Returns detailed info on a user’s fund withdrawals.
HTTP Request
GET https://api.bitso.com/v3/withdrawals/
GET https://api.bitso.com/v3/withdrawals/wid/
GET https://api.bitso.com/v3/withdrawals?wids=<wid>,<wid>,<wid>
GET https://api.bitso.com/v3/withdrawals?origin_ids=<origin_id>,<origin_id>,<origin_id>
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| wid | No | Specifies which withdrawal to obtain | |
| wids | No | Specifies which withdrawals to obtain (by wid) | |
| origin_ids | No | Specifies which withdrawals to obtain (by origin_id) |
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| limit | 25 | No | Specifies number of objects to return. (Max is 100) |
| marker | - | No | Returns objects that are older than the object with this WID (for pagination) |
| status | - | No | Restricts the withdrawals to those of the specified status (pending, processing, complete, failed) |
| method | - | No | Restricts the withdrawals to those of the specified method (SP, BTC, ETH, …) |
JSON Response Payload
Returns a JSON Array of open orders. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | The unique withdrawal ID | - |
| currency | String | Currency of the withdrawal | - |
| method | String | Method for this withdrawal (SP, BTC, ETH, …). | - |
| amount | String | The withdrawn amount | currency |
| status | String | The status for this withdrawal (pending, processing, complete, failed) | - |
| created_at | String | Timestamp at which the withdrawal as created | ISO 8601 timestamp |
| details | JSON object | Specific withdrawal details | - |
Fundings
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"fid": "c5b8d7f0768ee91d3b33bee648318688",
"status": "pending",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "btc",
"method": "btc",
"amount": "0.48650929",
"details": {
"funding_address": "18MsnATiNiKLqUHDTRKjurwMg7inCrdNEp",
"tx_hash": "d4f28394693e9fb5fffcaf730c11f32d1922e5837f76ca82189d3bfe30ded433"
}
}, {
"fid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "complete",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "sp",
"amount": "300.15",
"details": {
"sender_name": "BERTRAND RUSSELL",
"sender_bank": "BBVA Bancomer",
"sender_clabe": "012610001967722183",
"receive_clabe": "646180115400467548",
"numeric_reference": "80416",
"concepto": "Para el 🐖",
"clave_rastreo": "BNET01001604080002076841",
"beneficiary_name": "ALFRED NORTH WHITEHEAD"
}
}]
}
Returns detailed info on a user’s fundings.
HTTP Request
GET https://api.bitso.com/v3/fundings/
GET https://api.bitso.com/v3/fundings/fid/
GET https://api.bitso.com/v3/fundings/fid-fid-fid/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| limit | 25 | No | Specifies number of objects to return. (Max is 100) |
| marker | - | No | Returns objects that are older than the object with this FID (for pagination) |
| status | - | No | Restricts the fundings to those of the specified status (pending, in_progress, complete, failed) |
| method | - | No | Restricts the fundings to those of the specified method (SP, BTC, ETH, …) |
| txids | - | No | Allows lookups of specific Transaction IDs - comma delimited list possible. Please note that all other parameters will be ignored |
JSON Response Payload
Returns a JSON Array of fundings. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| fid | String | The unique funding ID | - |
| currency | String | Currency funded | - |
| method | String | Method for this funding (MXN, BTC, ETH). | - |
| amount | String | The funding amount | currency |
| status | String | The status for this funding (pending, complete, failed) | - |
| created_at | String | Timestamp at which the funding was received | ISO 8601 timestamp |
| details | JSON object | Specific funding details | - |
User Trades
curl "https://api.bitso.com/v3/user_trades/?book=btc_mxn"
The JSON Array returned by the API looks like this:
{
"success": true,
"payload": [{
"book": "btc_mxn",
"major": "-0.25232073",
"created_at": "2016-04-08T17:52:31.000+00:00",
"minor": "1013.540958479115",
"fees_amount": "-10.237787459385",
"fees_currency": "mxn",
"price": "4057.45",
"tid": 51756,
"oid": "g81d3y1ywri0yg8m",
"side": "sell",
"make_side": "sell"
}, {
"book": "eth_mxn",
"major": "4.86859395",
"created_at": "2016-04-08T17:52:31.000+00:00",
"minor": "-626.77",
"fees_amount": "-0.04917771",
"fees_currency": "btc",
"price": "127.45",
"tid": 51757,
"oid": "19vaqiv72drbphig",
"side": "buy",
"make_side": "sell"
}]
}
This endpoint returns a list of the user’s trades.
HTTP Request
GET https://api.bitso.com/v3/user_trades/
GET https://api.bitso.com/v3/user_trades/tid/
GET https://api.bitso.com/v3/user_trades/tid-tid-tid/
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| book | Yes | Specifies which book to use | |
| marker | No | Returns objects that are older or newer (depending on 'sort’) than the object with this ID | |
| sort | desc | No | Specifies ordering direction of returned objects |
| limit | 25 | No | Specifies number of objects to return. (Max is 100) |
JSON Response Payload
Returns descending JSON Array of transactions. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| major | String | Major amount traded | Major |
| minor | String | Minor amount traded | Minor |
| price | String | Price per unit of major | Minor |
| side | String | Indicates the user’s side for this trade (buy, sell) | |
| maker_side | String | Indicates the maker’s side for this trade (buy, sell), if it matches with side you’re maker |
|
| fees_currency | String | Indicates the currency in which the trade fee was charged | - |
| fees_amount | String | Indicates the amount charged as trade fee | |
| tid | Long | Trade ID | |
| oid | String | Users’ Order ID | |
| origin_id | String | Users’ Order 'origin_id’ (if any) | |
| created_at | String | Timestamp at which the trade was executed | ISO 8601 timestamp |
Order Trades
curl "https://api.bitso.com/v3/order_trades/Jvqrschkgdkc1go3"
The JSON Array returned by the API looks like this:
{
"success": true,
"payload": [{
"book": "btc_mxn",
"major": "-0.25232073",
"created_at": "2016-04-08T17:52:31.000+00:00",
"minor": "1013.540958479115",
"fees_amount": "-10.237787459385",
"fees_currency": "mxn",
"price": "4057.45",
"tid": 51756,
"oid": "Jvqrschkgdkc1go3",
"origin_id": "origin_id1",
"side": "sell",
"make_side": "sell"
},
{
"book": "btc_mxn",
"major": "-0.25",
"created_at": "2016-04-08T17:52:31.000+00:00",
"minor": "513.540958479115",
"fees_amount": "-10.237787459385",
"fees_currency": "mxn",
"price": "4057.45",
"tid": 51755,
"oid": "Jvqrschkgdkc1go3",
"origin_id": "origin_id1",
"side": "sell",
"make_side": "sell"
}
]
}
This endpoint returns a list of the user’s trades.
HTTP Request
GET https://api.bitso.com/v3/order_trades/<oid>/
GET https://api.bitso.com/v3/order_trades?origin_id=<origin_id>
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| oid | No | Specifies which order to get corresponding trades for | |
| origin_id | No | Specifies which order to get corresponding trades for (by origin_id) |
JSON Response Payload
Returns descending JSON Array of transactions. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| book | String | Order book symbol | Major_Minor |
| major | String | Major amount traded | Major |
| minor | String | Minr amount traded | Minor |
| price | String | Price per unit of major | Minor |
| side | String | Indicates the user’s side for this trade (buy, sell) | |
| maker_side | String | Indicates the maker’s side for this trade (buy, sell), if it matches with side you’re maker |
|
| fees_currency | String | Indicates the currency in which the trade fee was charged | - |
| fees_amount | String | Indicates the amount charged as trade fee | |
| tid | Long | Trade ID | |
| oid | String | Users’ Order ID | |
| origin_id | String | Users’ Order 'origin_id’ (if any) | |
| created_at | String | Timestamp at which the trade was executed | ISO 8601 timestamp |
Open Orders
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"book": "btc_mxn",
"original_amount": "0.01000000",
"unfilled_amount": "0.00500000",
"original_value": "56.0",
"created_at": "2016-04-08T17:52:31.000+00:00",
"updated_at": "2016-04-08T17:52:51.000+00:00",
"price": "5600.00",
"oid": "543cr2v32a1h68443",
"origin_id": "origin_id1",
"side": "buy",
"status": "partial-fill",
"type": "limit"
}, {
"book": "btc_mxn",
"original_amount": "0.12680000",
"unfilled_amount": "0.12680000",
"original_value": "507.2",
"created_at": "2016-04-08T17:52:31.000+00:00",
"updated_at": "2016-04-08T17:52:41.000+00:00",
"price": "4000.00",
"oid": "qlbga6b600n3xta7",
"side": "sell",
"status": "open",
"type": "limit"
}, {
"book": "btc_mxn",
"original_amount": "1.12560000",
"unfilled_amount": "1.12560000",
"original_value": "6892.66788",
"created_at": "2016-04-08T17:52:31.000+00:00",
"updated_at": "2016-04-08T17:52:41.000+00:00",
"price": "6123.55",
"oid": "d71e3xy2lowndkfm",
"side": "sell",
"status": "open",
"type": "limit"
}]
}
Returns a list of the user’s open orders.
HTTP Request
GET https://api.bitso.com/v3/open_orders?book=btc_mxn
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| book | all | No | Specifies which book to use |
| marker | No | Returns objects that are older or newer (depending on 'sort’) than the object with this ID | |
| sort | desc | No | Specifies ordering direction of returned objects |
| limit | 25 | No | Specifies number of objects to return. (Max is 100) |
JSON Response Payload
Returns a JSON Array of open orders. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| oid | String | The Order ID | - |
| book | String | Order book symbol | Major_Minor |
| original_amount | String | The order’s initial major currency amount | Major |
| unfilled_amount | String | The order’s unfilled major currency amount | Major |
| original_value | String | The order’s initial minor currency amount | Minor |
| created_at | String | Timestamp at which the trade was executed | ISO 8601 timestamp |
| updated_at | String | Timestamp at which the trade was updated (can be null) | ISO 8601 timestamp |
| price | String | The order’s price | Minor |
| side | String | The order side (buy, sell) | - |
| status | String | The order’s status (queued, open, partial-fill) | |
| type | String | The order type (will always be 'limit’ for open orders) | - |
Lookup Orders
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"book": "btc_mxn",
"original_amount": "0.01000000",
"unfilled_amount": "0.00500000",
"original_value": "56.0",
"created_at": "2016-04-08T17:52:31.000+00:00",
"updated_at": "2016-04-08T17:52:51.000+00:00",
"price": "5600.00",
"oid": "543cr2v32a1h6844",
"side": "buy",
"status": "partial-fill",
"type": "limit"
}, {
"book": "btc_mxn",
"original_amount": "0.12680000",
"unfilled_amount": "0.12680000",
"original_value": "507.2",
"created_at": "2016-04-08T17:52:31.000+00:00",
"updated_at": "2016-04-08T17:52:41.000+00:00",
"price": "4000.00",
"oid": "qlbga6b600n3xta7a",
"side": "sell",
"status": "open",
"type": "limit"
}]
}
Returns a list of details for 1 or more orders
HTTP Request
GET https://api.bitso.com/v3/orders/<oid>/
GET https://api.bitso.com/v3/orders?oids=<oid>,<oid>,<oid>
GET https://api.bitso.com/v3/orders?origin_ids=<origin_id>,<origin_id>,<origin_id>
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| oid | No | Specifies which order to obtain | |
| oids | No | Specifies which order to obtain (by order_id) | |
| origin_ids | No | Specifies which order to obtain (by origin_id) |
JSON Response Payload
Returns a JSON Array of open orders. Every element in the array is a JSON object:
| Field Name | Type | Description | Units |
|---|---|---|---|
| oid | String | The Order ID | - |
| book | String | Order book symbol | Major_Minor |
| original_amount | String | The order’s initial major currency amount | Major |
| unfilled_amount | String | The order’s unfilled major currency amount | Major |
| original_value | String | The order’s initial minor currency amount | Minor |
| created_at | String | Timestamp at which the order was created | ISO 8601 timestamp |
| updated_at | String | Timestamp at which the order was updated (can be null) | ISO 8601 timestamp |
| price | String | The order’s price | Minor |
| side | String | The order side (buy, sell) | - |
| status | String | The order’s status (queued, open, partial-fill, closed) | - |
| type | String | The order type (market, limit) | - |
| origin_id | String | The origin_id if any | - |
| time_in_force | String | The time in force paramater for limit orders | - |
| stop | String | The stop price for Stop orders | - |
| triggered_at | String | Timestamp at which a stop order was triggered | ISO 8601 timestamp |
Cancel Order
The string returned by the API looks like this:
{
"success": true,
"payload":[
"cME2F7uZKJcMKXqU",
"FwllxXRKvcgJmyFy",
"zhDI9iBRglW9s9Vu"
]
}
Cancels open order(s)
HTTP Request
DELETE https://api.bitso.com/v3/orders/<oid>/
DELETE https://api.bitso.com/v3/orders?oids=<oid>,<oid>,<oid>
DELETE https://api.bitso.com/v3/orders?origin_ids=<origin_id>,<origin_id>,<orgin_id>
DELETE https://api.bitso.com/v3/orders/all
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| oid | No | Specifies the order that should be cancelled | |
| oids | No | Specifies which orders should be cancelled (by order_id) | |
| origin_ids | No | Specifies which orders should be cancelled (by origin_id) | |
| all | No | Cancells all the open orders of the user |
JSON Response Payload
The response is a list of Order IDs (OIDs) for the canceled orders. Orders may not be successfully cancelled if they have been filled, have been already cancelled, or the OIDs are incorrect.
Place an Order
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"oid": "qlbga6b600n3xta7"
}
}
Places a buy or sell order (both limit and market orders are available)
HTTP Request
POST https://api.bitso.com/v3/orders/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| book | - | Yes | Specifies which book to use |
| side | - | Yes | The order side (buy, sell) |
| type | - | Yes | The order type (market, limit) |
| major | - | No | The amount of major currency for this order. An order must be specified in terms of major or minor, never both. |
| minor | - | No | The amount of minor currency for this order. An order must be specified in terms of major or minor, never both. |
| price | - | No | Price per unit of major. For use only with limit orders |
| stop | - | No | Price per unit of major at which to stop and place order. For use only with stop orders. |
| time_in_force | - | No | Indicates how long a limit order will remain active before it is executed or expires (goodtillcancelled, fillorkill, immediateorcancel, postonly) |
| origin_id | - | No | Client supplied unique ID. Can be used to lookup and cancel orders |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| oid | String | The Order ID | - |
Funding Destination
The JSON object returned by the API looks like this:
{
"success": true,
"payload": {
"account_identifier_name": "SPEI CLABE",
"account_identifier": "646180115400346012"
}
}
Returns account funding information for specified currencies.
HTTP Request
GET https://api.bitso.com/v3/funding_destination/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| fund_currency | - | Yes | Specifies which currency to fund with. |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| account_identifier_name | String | Account identifier name to fund with the specified currency. | - |
| account_identifier | String | Identifier to where the funds can be sent to. | - |
Crypto Withdrawals
The string returned by the API looks like this (example for BTC):
{
"success": true,
"payload": {
"wid": "c5b8d7f0768ee91d3b33bee648318688",
"status": "pending",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "btc",
"method": "btc",
"amount": "0.48650929",
"details": {
"withdrawal_address": "3EW92Ajg6sMT4hxK8ngEc7Ehrqkr9RoDt7",
"tx_hash": null
}
}
}
The following endpoints are available for making a cryptocurrency withdrawal from the user’s account:
HTTP Request
| Asset | Endpoint |
|---|---|
| all | POST https://api.bitso.com/v3/crypto_withdrawal/ |
| btc | POST https://api.bitso.com/v3/bitcoin_withdrawal/ |
| eth | POST https://api.bitso.com/v3/ether_withdrawal/ |
| xrp | POST https://api.bitso.com/v3/ripple_withdrawal/ |
| bch | POST https://api.bitso.com/v3/bcash_withdrawal/ |
| ltc | POST https://api.bitso.com/v3/litecoin_withdrawal/ |
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| currency | - | Yes | The currency to withdraw (only required for crypto_withdrawal endpoint) |
| amount | - | Yes | The amount of the asset to withdraw from your account |
| address | - | Yes | The address to send that amount to |
| max_fee | - | No | The maximum withdrawal you are willing to pay |
| destination_tag | - | No | Destination Tag (Ripple XRP only, optional) |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | Unique Withdrawal ID | - |
| status | String | Status of the withdrawal request (pending, complete) | - |
| created_at | String | Timestamp at which the withdrawal request was created | ISO 8601 timestamp |
| currency | String | Currency specified for this withdrawal (e.g. BTC) | - |
| method | String | Method for this withdrawal (e.g. BTC). | - |
| amount | String | Amount to withdraw. | units of e.g. BTC |
| details | String | Method specific details for this withdrawal | - |
SPEI Withdrawal
The string returned by the API looks like this:
{
"success": true,
"payload": {
"wid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "pending",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "sp",
"amount": "300.15",
"details": {
"sender_name": "JUAN ESCUTIA",
"receive_clabe": "012610001967722183",
"sender_clabe": "646180115400467548",
"numeric_reference": "80416",
"concepto": "Tacos del viernes",
"clave_rastreo": null,
"beneficiary_name": "FRANCISCO MARQUEZ"
}
}
}
Triggers a SPEI withdrawal from your account. These withdrawals are immediate during banking hours for some banks (M-F 9:00AM - 5:00PM Mexico City Time), 24 hours for others.
HTTP Request
POST https://api.bitso.com/v3/spei_withdrawal/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| amount | - | Yes | The amount of MXN to withdraw from your account |
| recipient_given_names | - | Yes | The recipient’s first and middle name(s) |
| recipient_family_names | - | Yes | The recipient’s last name |
| clabe | - | Yes | The CLABE number where the funds will be sent to |
| notes_ref | - | No | The alpha-numeric reference number for this SPEI (max. 40 characters) |
| numeric_ref | - | No | The numeric reference for this SPEI (max. 7 digits) |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | Unique Withdrawal ID | - |
| status | String | Status of the withdrawal request (pending, complete) | - |
| created_at | String | Timestamp at which the withdrawal request was created | ISO 8601 timestamp |
| currency | String | Currency specified for this withdrawal (MXN) | - |
| method | String | Method for this withdrawal (SPEI Transfer) | - |
| amount | String | Amount to withdraw | - |
| details | String | Method specific details for this withdrawal | - |
Bank Codes
The JSON object returned by the API looks like this:
{
"success": true,
"payload": [{
"code": "01",
"name": "Banregio"
}, {
"code": "02",
"name": "BBVA"
}]
}
This endpoint returns codes and bank names to be used in the Debit Card WIthdrawal and Phone Number Withdrawal endpoints
HTTP Request
GET https://api.bitso.com/v3/mx_bank_codes/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
JSON Response Payload
Returns a JSON Array. Every element in the array is a JSON object with the following fields.
| Field Name | Type | Description | Units |
|---|---|---|---|
| code | String | Corresponding bank’s code | |
| name | String | Corresponding bank’s name |
Debit Card Withdrawal
The string returned by the API looks like this:
{
"success": true,
"payload": {
"wid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "pending",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "sp",
"amount": "300.15",
"details": {
"sender_name": "JUAN ESCUTIA",
"receive_clabe": "012610001967722183",
"sender_clabe": "646180115400467548",
"numeric_reference": "80416",
"concepto": "Tacos del viernes",
"clave_rastreo": null,
"beneficiary_name": "FRANCISCO MARQUEZ"
}
}
}
Triggers a Debit Cards withdrawal from your account. These withdrawals are immediate during banking hours for some banks (M-F 9:00AM - 5:00PM Mexico City Time), 24 hours for others.
HTTP Request
POST https://api.bitso.com/v3/debit_card_withdrawal/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| amount | - | Yes | The amount of MXN to withdraw from your account |
| recipient_given_names | - | Yes | The recipient’s first and middle name(s) |
| recipient_family_names | - | Yes | The recipient’s last name |
| card_number | - | Yes | The debit card number where the funds will be sent to |
| bank_code | - | Yes | The bank code for this card’s issuer as returned by the “Bank Codes” endpoint |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | Unique Withdrawal ID | - |
| status | String | Status of the withdrawal request (pending, complete) | - |
| created_at | String | Timestamp at which the withdrawal request was created | ISO 8601 timestamp |
| currency | String | Currency specified for this withdrawal (MXN) | - |
| method | String | Method for this withdrawal (Debit Card Withdrawal) | - |
| amount | String | Amount to withdraw | - |
| details | String | Method specific details for this withdrawal | - |
Phone Number Withdrawal
The string returned by the API looks like this:
{
"success": true,
"payload": {
"wid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "pending",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "sp",
"amount": "300.15",
"details": {
"sender_name": "JUAN ESCUTIA",
"receive_clabe": "012610001967722183",
"sender_clabe": "646180115400467548",
"numeric_reference": "80416",
"concepto": "Tacos del viernes",
"clave_rastreo": null,
"beneficiary_name": "FRANCISCO MARQUEZ"
}
}
}
Triggers a withdrawal from your account to a phone number. (Phone number must be registered for SPEI Transfers with their corresponding bank) These withdrawals are immediate during banking hours for some banks (M-F 9:00AM - 5:00PM Mexico City Time), 24 hours for others.
HTTP Request
POST https://api.bitso.com/v3/phone_withdrawal/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| amount | - | Yes | The amount of MXN to withdraw from your account |
| recipient_given_names | - | Yes | The recipient’s first and middle name(s) |
| recipient_family_names | - | Yes | The recipient’s last name |
| phone_number | - | Yes | The phone number associated with the account where the funds will be sent to |
| bank_code | - | Yes | The bank code for this card’s issuer as returned by the “Bank Codes” endpoint |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | Unique Withdrawal ID | - |
| status | String | Status of the withdrawal request (pending, complete) | - |
| created_at | String | Timestamp at which the withdrawal request was created | ISO 8601 timestamp |
| currency | String | Currency specified for this withdrawal (MXN) | - |
| method | String | Method for this withdrawal (Debit Card Withdrawal) | - |
| amount | String | Amount to withdraw | - |
| details | String | Method specific details for this withdrawal | - |
WebSocket API
General
The Trades channel send a message whenever a new trade is executed in the corresponding order book.
The Orders channel maintains an up-to-date list of the top 20 asks and the top 20 bids, new messages are sent across the channel whenever there is a change in either top 20. This channel will be deprecated from October 1st, 2020.
The Diff-Orders channel will send across any modifications to the order book. Specifically, any state changes in existing orders (including orders not in the top 20), and any new orders. An order could be removed, in which case it won’t have an 'a’ field (amount), or an order could have been partially filled (you can look up an order’s state via the lookup_order endpoint) which will be reflected in the amount field. Each message contains a sequence number, which are increasing integer values, each new message incrementing the sequence number by one. If you see a sequence number that is more than one value that the previous, this means a message has been dropped and you need to update the order book to get to correct state. In theory, you can get a copy of the full order book via REST once, and keep it up to date by using the diff-orders channel with the following algorithm:
Algorithm
- Subscribe to the diff-orders channel.
- Queue any message that come in to this channel.
- Get the full orderbook from the REST orderbook endpoint.
- Playback the queued message, discarding the ones with sequence number below or equal to the one from the REST orderbook.
- Apply the next queued messages to your local order book data structure.
- Apply real-time messages to your local orderbook as they come in trough the stream.
An order’s timestamp field is immutable. Even if the amount field is mutated, or the order removed, the timestamp field remains as it was when the order was created. Note that a timestamp is not unique. Different orders can have the same timestamp.
How to connect
Create a WebSocket instance:
websocket = new WebSocket('wss://ws.bitso.com');
Subscribe to each channel you wish to connect to:
websocket.onopen = function() {
websocket.send(JSON.stringify({ action: 'subscribe', book: 'btc_mxn', type: 'trades' }));
websocket.send(JSON.stringify({ action: 'subscribe', book: 'btc_mxn', type: 'diff-orders' }));
websocket.send(JSON.stringify({ action: 'subscribe', book: 'btc_mxn', type: 'orders' }));
};
The server will acknowledge each subscription to a channel with a message. For example, a successful subscription to the 'trades’ channel will be acknowledged in the following manner:
{action: "subscribe", response: "ok", time: 1455831538045, type: "trades"}
Once you’ve succesfully subscribed to a channel, listen for messages and handle them appropriately:
websocket.onmessage = function(message){
var data = JSON.parse(message.data);
if (data.type == 'trades' && data.payload) {
}
else if (data.type == 'diff-orders' && data.payload) {
}
else if (data.type == 'orders' && data.payload) {
}
};
Keep alive messages look like this:
{"type":"ka"}
Example Implementation
Use this example native javascript implementation for your reference: https://bitso.com/demo_ws.html
Trades Channel
Messages on this channel look like this:
{
"type": "trades",
"book": "btc_mxn",
"payload": [
{
"i": 72022,
"a": "0.0035",
"r": "7190",
"v": "25.16"
}
]
}
Client subscription message
{ action: 'subscribe', book: 'btc_mxn', type: 'trades' }
Server subscription response message
{action: "subscribe", response: "ok", time: 1455831538045, type: "trades"}
Server JSON message
The payload contains an array with one or more trades of the following form:
| Field Name | Type | Description | Units |
|---|---|---|---|
| i | Number | A unique number identifying the transaction | - |
| a | String | Amount | Major |
| r | String | Rate | Minor |
| v | String | Value | Minor |
| t | Number | Maker side, 0 indicates buy 1, indicates sell | - |
| mo | String | Maker Order ID | - |
| to | String | Taker Order ID | - |
Diff-Orders
Messages on this channel look like this:
{
"type": "diff-orders",
"book": "btc_mxn",
"sequence": 2734,
"payload": [
{
"d": 1455315979682,
"r": "7251.1",
"t": 1,
"a": "0.29437179",
"v": "2134.51",
"o": 'VM7lVpgXf04o6vJ6'
}
]
}
Client subscription message
websocket.send(JSON.stringify({ action: 'subscribe', book: 'btc_mxn', type: 'diff-orders' }));
Server subscription response message
{action: "subscribe", response: "ok", time: 1455831538047, type: "diff-orders"}
Server JSON Message
The payload contains an array with one or more orders of the following form:
| Field Name | Type | Description | Units |
|---|---|---|---|
| d | Number | Unix timestamp | Milliseconds |
| r | String | Rate | Minor |
| t | Number | 0 indicates buy 1 indicates sell | - |
| a | String | Amount | Major |
| v | String | Value | Minor |
| o | String | Order ID | - |
Orders
Messages on this channel look like this:
{
"type": "orders",
"book": "btc_mxn",
"payload": {
"bids": [
{
"r": "7185",
"a": "0.001343",
"v": "9.64",
"t": 1,
"d": 1455315394039
},
{
"r": "7183.01",
"a": "0.007715",
"v": "55.41",
"t": 1,
"d": 1455314938419
},
{
"r": "7183",
"a": "1.59667303",
"v": "11468.9",
"t": 1,
"d": 1455314894615
}
],
"asks": [
{
"r": "7251.1",
"a": "0.29437179",
"v": "2134.51",
"t": 0,
"d": 1455315979682
},
{
"r": "7251.72",
"a": "1.32057812",
"v": "9576.46",
"t": 0,
"d": 1455303931277
}
]
}
}
Client Subscription message
{ websocket.send(JSON.stringify({ action: 'subscribe', book: 'btc_mxn', type: 'orders' }));
Server subscription response message
{action: "subscribe", response: "ok", time: 1455831538048, type: "orders"}
Server JSON message
The payload contains a JSON with two keys, one for the bids and the other for asks on the order book. Both bids and asks contain orders of the following form:
| Field Name | Type | Description | Units |
|---|---|---|---|
| r | String | Rate | Minor |
| a | String | Amount | Major |
| v | String | Value | Minor |
| t | Number | 0 indicates buy 1 indicates sell | - |
| d | Number | Unix timestamp | Milliseconds |
Transfer API
General
Bitso’s powerful Transfer API allows for simple integration for routing Bitcoin payments directly through to a choice of Mexican Peso end-points.
The workflow breaks down in the following steps:
- Request quote
- Create transfer using quote
- Send bitcoins to address given
- After 1 confirmation, pesos are delivered
The quote acquired in step #1 is valid for 60 seconds. Once this is used to create a transfer (#2), that transfer is then valid for 60 seconds from creation (within which time the Bitcoin transaction to satisfy it must be ‘seen’ by our servers – this typically happens within 20 seconds).
Once the transfer is satisfied, the Bitcoin transaction must be confirmed before a further action takes place. Typically this takes around a maximum of 10 minutes, but can be a little longer.
The transfer can be monitored throughout the process by making a request to the URL returned with the transfer creation.
Authentication
The Transfer API is accessible via an API key created for your account. For full details on creating an API key and how to sign your API requests, please refer to: the authentication section
Requesting a Quote
The JSON object returned by the API looks like this:
{
"success":true,
"payload":{
"btc_amount":"0.14965623",
"currency":"MXN",
"rate":"3340.99",
"gross":"500.00",
"outlets":{
"sp":{
"id":"sp",
"name":"SPEI Transfer",
"required_fields":[
"recipient_given_names",
"recipient_family_names",
"clabe",
"bank_name"
],
"minimum_transaction":"500.00",
"maximum_transaction":"2500000.00",
"daily_limit":"10000.00",
"fee":"12.00",
"net":"488.00",
"available":"1",
"verification_level_requirement":"0"
},
"vo":{
"id":"vo",
"name":"Voucher",
"required_fields":[
"email_address"
],
"minimum_transaction":"25.00",
"maximum_transaction":"9999.00",
"fee":"0.00",
"daily_limit":"0.00",
"net":"500.00",
"available":"1",
"verification_level_requirement":"0"
},
"bw":{
"id":"bw",
"name":"Bank Wire",
"required_fields":[
"recipient_full_name",
"account_holder_address",
"bank_name",
"bank_address",
"account_number",
"swift",
"other_instructions"
],
"minimum_transaction":"1000.00",
"maximum_transaction":"2500000.00",
"daily_limit":"2500000.00",
"fee":"500.00",
"net":"0.00",
"available":"1",
"verification_level_requirement":"0"
}
},
"created_at":"2016-04-08T17:52:31.000+00:00",
"expires_at":"2016-04-08T18:02:31.000+00:00"
}
}
HTTP Request
POST https://api.bitso.com/v3/transfer_quote
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Required | Description |
|---|---|---|
| from_currency | Yes | The cryptocurrency that you wish to send. This will be converted to the to_currency fiat currency |
| from_amount | No | Mutually exclusive with to_amount. Either this, or to_amount should be present in the request. The total amount in Crypto, as provided by the user. |
| to_amount | No | Mutually exclusive with from_amount. Either this, or from_amount should be present in the request. The total amount in Fiat currency. Use this if you prefer specifying amounts in fiat instead of cryptocurrency. |
| to_currency | Yes | An ISO 4217 fiat currency symbol (ie, “MXN”). This is the resulting currency from the transfer. |
| full | No | (optional, defaults to False) - Show the required_fields for each payment outlet as an array of {id, name} objects. This accepts either True or False. When not provided or if the value is False, the required_fields for each Payment Outlet are returned as an array of id strings. For more information about required_fields, please refer to the Payment Outlet Documentation. |
Creating a Transfer
The JSON object returned by the API looks like this:
{
"success":true,
"payload":{
"from_currency":"BTC",
"from_amount":"0.14965623",
"from_pending":"0",
"from_received":"0",
"confirmation_code":"9b2a4",
"created_at":"2016-04-08T17:52:31.000+00:0",
"currency":"MXN",
"currency_amount":"0",
"currency_fees":"0",
"currency_settled":"0",
"expires_epoch":"2016-04-08T18:02:31.000+00:0",
"fields":{
"phone_number":"5555252525"
},
"id":"9b2a431b98597312e99cbff1ba432cbf",
"payment_outlet_id":"pm",
"status":"pending",
"qr_img_uri":"https:\/\/chart.googleapis.com\/chart?chl=bitcoin%3AmgKZfNdFJgztvfvhEaGgMTQRQ2iHCadHGa%3Famount%3D0.14965623&chs=400x400&cht=qr&choe=UTF-8&chld=L%7C0",
"user_uri":"https:\/\/api.bitso.com\/v3\/transfer\/9b2a431b98597312e99cbff1ba432cbf",
"wallet_address":"3AmgKZfNdFJgztvfvhEaGgMTQRQ2iHCadHGa"
}
}
HTTP Request
POST https://api.bitso.com/v3/transfer_create
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Required | Description |
|---|---|---|
| from_currency | Yes | The cryptocurrency that you wish to send. This will be converted to the to_currency fiat currency |
| from_amount | No | Mutually exclusive with to_amount. Either this, or to_amount should be present in the request. The total amount in Crypto, as provided by the user. |
| to_amount | No | Mutually exclusive with from_amount. Either this, or from_amount should be present in the request. The total amount in Fiat currency. Use this if you prefer specifying amounts in fiat instead of cryptocurrency. |
| to_currency | Yes | An ISO 4217 fiat currency symbol (ie, “MXN”). This is the resulting currency from the transfer. |
| rate | Yes | This is the rate (e.g. BTC/MXN), as acquired from the transfer_quote method. You must request a quote in this way before creating a transfer. |
| payment_outlet | Yes | The outlet_id as provided by quote method. See below for more information on available outlets. |
| required_field1 | Yes | Each of the other ‘required fields’, as stipulated in the quote method for the chosen payment_outlet. |
| required_field2 | Yes |
Reviewing a Transfer
Make requests to the transfer review end point at any time to monitor the status of your transfer.
HTTP Request
GET https://api.bitso.com/v3/transfer/<transfer_id>
Response
| Parameter | Required | Description |
|---|---|---|
| status | Yes | pending: waiting for the bitcoin transaction to be seen, confirming: transaction has been seen, and now waiting for a network confirmation, completed: transaction has completed, and funds dispatched via the outlet specified. |
Currently Available Outlets
SPEI
SPEI is Mexico’s lightning fast and inexpensive inter-bank transfer system (akin to SEPA in Europe, and vastly superior to ACH).
All bank accounts in Mexico can be identified by their special 18-digit SPEI account number, otherwise known as a ‘CLABE’.
Transfers executed via SPEI are typically concluded within a few seconds (within banking hours).
Debit Cards
Send tansfers directly to debit cards from any mexican bank. Note that the “institution_code” is obtained from the bank_codes endpoint.
Voucher
Bitso offers the ability to issue voucher codes redeemable on Bitso.com, and delivered by email. Simply specify the amount and email address, and the recipient can at any time register on Bitso.com and redeem their code.
Bank Wire
Execute a standard international bank wire via this outlet.
Cash
Deliver cash for collection by a recipient at any of thousands of cash-out locations across Mexico
Remittance API
General
Using the Remittance API, partners can generate orders for cash pick-up at payment points across the length and breadth of Mexico.
Authentication
The Transfer API is accessible via an API key created for your account. For full details on creating an API key and how to sign your API requests, please refer to: the authentication section
Create Remittance
The string returned by the API looks like this:
{
"success": true,
"payload": {
"wid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "complete",
"created_at": "2016-04-08T17:52:31.000+00:00",
"currency": "mxn",
"method": "bt",
"amount": "300.15",
"details": {
"reference": "123451245",
"collection_reference": "XXXX123456789"
}
}
}
Triggers a withdrawal from your account to create a cash-out order for collection at a specified location.
HTTP Request
POST https://api.bitso.com/v3/remittance_create/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| amount | - | Yes | The amount of MXN to send for the remittance |
| sender_first_name | - | Yes | The sender’s first and middle name(s) |
| sender_last_name | - | Yes | The sender’s family name(s) |
| sender_address | - | Yes | The sender’s address |
| sender_phone | - | Yes | The sender’s phone number |
| sender_countycity | - | Yes | The sender’s county or city |
| sender_state | - | Yes | The sender’s state |
| receiver_first_name | - | Yes | The beneficiary’s first and middle name(s) |
| receiver_last_name | - | Yes | The beneficiary’s family name(s) |
| receiver_address | - | Yes | The beneficiary’s address |
| receiver_phone | - | Yes | The beneficiary’s phone number |
| receiver_city | - | Yes | The beneficiary’s city |
| receiver_state | - | Yes | The beneficiary’s state |
| payout_point_id | - | Yes | The specified payout point ID (taken from the remittance_locations endpoint) |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | Unique Withdrawal ID | - |
| status | String | Status of the withdrawal request (pending, complete) | - |
| created_at | String | Timestamp at which the withdrawal request was created | ISO 8601 timestamp |
| currency | String | Currency specified for this withdrawal (MXN) | - |
| method | String | Method for this withdrawal (Debit Card Withdrawal) | - |
| amount | String | Amount to withdraw | - |
| details | String | Contains the reference identifier for cash-out order, needed to alter the order and for recipient to collect payment. | - |
Cancel Remittance
The string returned by the API looks like this:
{
"success": true,
"payload": {
"reference": "XYZ123"
}
}
Triggers the cancellation of a previously created cash-out order.
HTTP Request
POST https://api.bitso.com/v3/remittance_cancel/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| reference | - | Yes | The reference code for the cash-out order |
| reason | - | Yes | The reason for cancellation |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| reference | String | Reference of the order in question | - |
Remittance Change Beneficiary Name
The string returned by the API looks like this:
{
"success": true,
"payload": {
"reference": "XYZ123"
}
}
Change the beneficiary name of a previously created cash-out order.
HTTP Request
POST https://api.bitso.com/v3/remittance_change_name/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| reference | - | Yes | The reference code for the cash-out order |
| new_name | - | Yes | The new name for the beneficiary |
| reason | - | Yes | The reason for change |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| reference | String | Reference of the order in question | - |
Remittance Change Beneficiary Phone
The string returned by the API looks like this:
{
"success": true,
"payload": {
"reference": "XYZ123"
}
}
Change the beneficiary phone number of a previously created cash-out order.
HTTP Request
POST https://api.bitso.com/v3/remittance_change_phone/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| reference | - | Yes | The reference code for the cash-out order |
| new_phone | - | Yes | The new phone number for the beneficiary |
| reason | - | Yes | The reason for change |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| reference | String | Reference of the order in question | - |
Remittance Change Sender Name
The string returned by the API looks like this:
{
"success": true,
"payload": {
"reference": "XYZ123"
}
}
Change the sender name of a previously created cash-out order.
HTTP Request
POST https://api.bitso.com/v3/remittance_change_sender/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| reference | - | Yes | The reference code for the cash-out order |
| new_name | - | Yes | The new name for the sender |
| reason | - | Yes | The reason for change |
JSON Response Payload
Returns a JSON object representing the order:
| Field Name | Type | Description | Units |
|---|---|---|---|
| reference | String | Reference of the order in question | - |
Remittance Payout Locations
The string returned by the API looks like this:
{
"success": true,
"payload": [{
"ID": 1234,
"city": "Ciudad de Rafael Lara Grajales",
"state": "Puebla",
"payer": "Payer Name",
"address": "Payer Address",
"zipCode": "Payer ZIP",
"reference": "",
"phoneNumber": "Payer Phone",
"currency": "PESOS",
"paymentLimit": 300,
"monday": "10:00 a 18:00",
"tuesday": "10:00 a 18:00",
"wednesday": "10:00 a 18:00",
"thursday": "10:00 a 18:00",
"friday": "10:00 a 18:00",
"saturday": "11:00 a 17:00",
"sunday": "11:00 a 17:00"
},
{
"ID": 1235,
"city": "Santa Maria La Alta",
"state": "Puebla",
"payer": "Payer Name",
"address": "Payer Address",
"zipCode": "Payer ZIP",
"reference": "",
"phoneNumber": "Payer Phone",
"currency": "PESOS",
"paymentLimit": 500,
"monday": "09:00 a 18:00",
"tuesday": "09:00 a 18:00",
"wednesday": "09:00 a 18:00",
"thursday": "09:00 a 18:00",
"friday": "09:00 a 18:00",
"saturday": "09:00 a 18:00",
"sunday": "CERRADO"
}
]
}
Get a list of all available cash payout locations.
HTTP Request
GET https://api.bitso.com/v3/remittance_locations/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| state | - | No | Limit results to a particular state. |
| city | - | No | Limit results to a particular city. |
| zipcode | - | No | Limit results to a particular ZIP code. |
JSON Response Payload
Returns a JSON array containing all of the available payout locations meeting the criteria:
| Field Name | Type | Description | Units |
|---|---|---|---|
| ID | String | The unique ID for the payout location for use in specifying a new cash-out order | - |
Webhooks
Registering URLs
Users can register a callback url that will get hit with payloads corresponding to certain events described below. (Callback urls that take more than 5 seconds to respond will timeout)
The JSON object returned by the API looks like this:
{
"success": true,
"payload": "Succesfully registered URL: <callback_url>"
}
HTTP Request
POST https://api.bitso.com/v3/webhooks/
Authorization Header Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| key | - | Yes | See Creating and Signing Requests |
| signature | - | Yes | See Creating and Signing Requests |
| nonce | - | Yes | See Creating and Signing Requests |
Body Parameters
Body parameters should be JSON encoded and should be exactly the same as the JSON payload used to construct the signature.
| Parameter | Default | Required | Description |
|---|---|---|---|
| callback_url | Yes | Specifies a url that will be hit on events |
Fundings
Users that register a webhook will get a POST payload to that URL with the following fields on deposits.
The JSON Object posted to the webhook URL looks like this
{
"event": "funding",
"payload":
{
"fid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "complete",
"created_at": "2016-04-08T17:52:31+00:00",
"currency": "mxn",
"method": "sp",
"method_name": "Transferencia SPEI",
"amount": "300.15",
"details": {
"sender_name": "HUGO HERNANDEZ MANZANO",
"sender_bank": "BBVA Bancomer",
"sender_clabe": "012610001967722183",
"receive_clabe": "646180115400467548",
"numeric_reference": "80416",
"concepto": "Para el 🐖",
"clave_rastreo": "BNET01001604080002076841",
"beneficiary_name": "HUGO HERNANDEZ MANZANO"
}
}
}
JSON Payload
Returns a JSON object with the following fields:
| Field Name | Type | Description | Units |
|---|---|---|---|
| fid | String | The unique funding ID | - |
| currency | String | Currency funded | - |
| method | String | Method for this funding (mxn, btc, eth). | - |
| method_name | String | Long name for the method | - |
| amount | String | The funding amount | currency |
| status | String | The status for this funding (pending, complete, cancelled) | - |
| created_at | String | Timestamp at which the funding was received | ISO 8601 timestamp |
| details | JSON object | Specific funding details, may vary depending on funding method | - |
Withdrawals
Users that register a webhook will get a POST payload to that URL with the following fields on withdrawals.
The JSON Object posted to the webhook URL looks like this
{
"event": "withdrawal",
"payload":
{
"wid": "p4u8d7f0768ee91d3b33bee6483132i8",
"status": "complete",
"created_at": "2017-07-09T19:22:38+00:00",
"currency": "xrp",
"method": "rp",
"method_name": "Ripple",
"amount": "57",
"details": {
"address": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_tag": "64136557",
"ripple_transaction_hash": "33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321"
}
}
}
JSON Payload
Returns a JSON object with the follwing fields:
| Field Name | Type | Description | Units |
|---|---|---|---|
| wid | String | The unique withdrawal ID | - |
| currency | String | Currency withdrawn | - |
| method | String | Method for this withdrawal (btc, eth). | - |
| method_name | String | Long name for the method | - |
| amount | String | The withdrawal amount | currency |
| status | String | The status for this withdrawal (pending, complete, cancelled) | - |
| created_at | String | Timestamp at which the withdrawal was received | ISO 8601 timestamp |
| details | JSON object | Specific withdrawal details, may vary depending on withdrawal method | - |
