Introduction - WARNING - THIS API VERSION HAS BEEN SUPERSEDED
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.
General
General Information about Bitso’s APIs
HTTP and WebSocket APIs
Bitso offers a HTTP API, and a WebSocket API. The HTTP API exposes both public and private functions. The WebSocket API offers realtime streaming of market-data, such as the Bitso orderbook state.
Transfer API
Bitso’s powerful Transfer API allows for simple integration for routing Bitcoin payments directly through to a choice of Mexican Peso end-points. Please contact us if you’re interested in using this API, access is available on request.
Notations
Major denotes the cryptocurrency, in our case Bitcoin (BTC).
Minor denotes fiat currencies such as Mexican Peso (MXN), etc
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 are based on one minute windows. If you do more than 30 requests in a minute, you get locked out for one minute.
Client Libraries
The following client libraries will allow you to integrate quickly with our APIs
Public Endpoints
Ticker
curl "https://bitso.com/api/v2/ticker?book=btc_mxn"
The JSON dictionary returned by the API looks like this:
{
"volume": "22.31349615",
"high": "5750.00",
"last": "5633.98",
"low": "5450.00",
"vwap": "5393.45",
"ask": "5632.24",
"bid": "5520.01",
"timestamp": "1447348096"
}
This endpoint returns trading information from the specified book.
HTTP Request
GET https://api.bitso.com/v2/ticker
Query Parameters
Parameter | Default | Required | Description |
---|---|---|---|
book | btc_mxn | No | Specifies which book to use |
JSON Response
Field Name | Type | Description | Units |
---|---|---|---|
last | String | Last traded price | Minor/Major |
high | String | Last 24 hours price high | Minor/Major |
low | String | Last 24 hours price low | Minor/Major |
vwap | String | Last 24 hours volume weighted average price: vwap | Minor/Major |
volume | String | Last 24 hours volume | Major |
bid | String | Highest buy order | Minor/Major |
ask | String | Lowest sell order | Minor/Major |
Order Book
curl "https://api.bitso.com/v2/order_book?book=btc_mxn&group=1"
The JSON dictionary returned by the API looks like this:
{
"asks": [
["5632.24", "1.34491802"],
["5632.25", "1.00000000"],
["5633.99", "0.61980799"]
],
"bids": [
["5520.01", "0.34493053"],
["5520.00", "0.08000000"],
["5486.01", "0.00250000"]
],
"timestamp": "1447348416"
}
This endpoint returns a list of all open orders in the specified book.
HTTP Request
GET https://api.bitso.com/v2/order_book
Query Parameters
Parameter | Default | Required | Description |
---|---|---|---|
book | btc_mxn | No | Specifies which book to use |
group | 1 | No | Group orders with the same price (0 - false; 1 - true) |
JSON Response
Returns JSON dictionary with “bids” and “asks”. Each is a JSON Array of open orders and each open order is represented as a JSON Array of price (minor) and amount (major).
Field Name | Type | Description |
---|---|---|
asks | JSON Array | List of open asks |
bids | JSON Array | List of open bids |
asks and bids JSON Array format:
Array Position | Type | Description | Units |
---|---|---|---|
0 | String | Order Price | Minor |
1 | String | Order Amount | Major |
Transactions [DISCONTINUED]
curl "https://api.bitso.com/v2/transactions?book=btc_mxn&time=minute"
The JSON Array returned by the API looks like this:
[
{
"date": "1447350465",
"amount": "0.02000000",
"side": "buy",
"price": "5545.01",
"tid": 55845
},
{
"date": "1447347533",
"amount": "0.33723939",
"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/v2/transactions
Query Parameters
Parameter | Default | Required | Description |
---|---|---|---|
book | btc_mxn | No | Specifies which book to use |
time | hour | No | Time frame for transaction export (“minute” - 1 minute, “hour” - 1 hour) |
JSON Response
Returns descending JSON Array of transactions. Every element in the array is a JSON dictionary:
Field Name | Type | Description | Units |
---|---|---|---|
date | String | Unix timestamp | Seconds |
tid | Long | transaction id | - |
price | String | Price per unit of major | Minor |
amount | String | Major amount transacted | Major |
side | String | Indicates the maker order side (maker order is the order that was open on the order book) | - |
Private Endpoints
Private endpoints are used to manage your account and your orders. These requests must be signed (more about 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 three key elements you will need to sign requests are:
- Bitso API Key
- Bitso API Secret
- Bitso Client ID
Creating and Signing Requests
var secret = "BITSO API SECRET";
var key = "BITSO API KEY";
var client_id = "BITSO CLIENT ID";
var nonce = new Date().getTime();
// Create the signature
var Data = nonce + client_id + key;
var crypto = require('crypto');
var signature = crypto.createHmac('sha256', secret).update(Data).digest('hex');
// Build the request parameters
var querystring = require('querystring');
var data = querystring.stringify({
key: key,
nonce: nonce,
signature: signature
});
var options = {
host: 'api.bitso.com',
port: 443,
path: '/v2/balance',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
}
};
// Send request
var http = require('https');
var req = http.request(options, function(res) {
res.on('data', function (chunk) {
console.log("body: " + chunk);
});
});
req.write(data);
req.end();
#!/usr/bin/ruby
require 'date'
require 'json'
require 'openssl'
require 'typhoeus'
bitso_key = "BITSO_KEY";
bitso_secret = "BITSO_SECRET";
bitso_client_id = "BITSO_CLIENT_ID";
nonce = DateTime.now.strftime('%Q')
# Create signature
message = nonce + bitso_key + bitso_client_id
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), bitso_secret, message)
# Build the request parameters
o = {
:key => bitso_key,
:nonce => nonce.to_i,
:signature => signature
}
body = JSON.generate(o)
# Send request
response = Typhoeus::Request.new(
"https://api.bitso.com/v2/balance",
method: "post",
body: body,
headers: { "Content-Type" => "application/json" }
).run
puts response.body
package com.bitso.awesome;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.math.BigInteger;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.json.JSONObject;
public class BitsoJavaExample {
public static void main(String[] args) throws Exception {
String bitsoKey = "BITSO API KEY";
String bitsoSecret = "BITSO API SECRET";
String bitsoClientId = "BITSO CLIENT ID";
long nonce = System.currentTimeMillis();
// Create the signature
String message = nonce + bitsoKey + bitsoClientId;
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 });
// Build the request parameters
JSONObject o = new JSONObject();
o.put("key", bitsoKey);
o.put("nonce", nonce);
o.put("signature", signature);
String body = o.toString();
String url = "https://api.bitso.com/v2/balance";
// Send request
HttpPost postRequest = new HttpPost(url);
postRequest.addHeader("Content-Type", "application/json");
postRequest.setEntity(new StringEntity(body));
CloseableHttpResponse response = HttpClients.createDefault().execute(postRequest);
BufferedReader in = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
String inputLine;
StringBuffer responseBody = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
responseBody.append(inputLine);
}
in.close();
System.out.println(responseBody.toString());
}
}
<?php
$bitsoKey = 'BITSO_API_KEY';
$bitsoSecret = 'BITSO_API_SECRET';
$bitsoClientId = 'BITSO_CLIENT_ID';
$nonce = round(microtime(true) * 1000);
// Create signature
$message = $nonce . $bitsoClientId . $bitsoKey;
$signature = hash_hmac('sha256', $message, $bitsoSecret);
// Build the request parameters
$o = array(
'key' => $bitsoKey,
'nonce' => $nonce,
'signature' => $signature
);
$body = json_encode($o);
// Send request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.bitso.com/v2/balance');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json; charset=utf-8',
'Content-Length: ' . strlen($body))
);
$result = curl_exec($ch);
echo $result;
?>
All REST requests should be valid JSON. You need to POST 3 fields as a JSON payload to the API 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 + Bitso Client ID + Bitso API Key (no ’+’ signs in the concatenated string) and hex-encode the output. The nonce value should be the same as the nonce field in the json dictionary.
Account balance
The JSON dictionary returned by the API looks like this:
{
"btc_available": "46.67902107",
"fee": "1.0000",
"mxn_available": "26864.57",
"btc_balance": "46.67902107",
"mxn_reserved": "0.00",
"mxn_balance": "26864.57",
"btc_reserved": "0.00000000"
}
This endpoint returns information of all balances.
HTTP Request
POST https://api.bitso.com/v2/balance
Body 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
Field Name | Type | Description | Units |
---|---|---|---|
mxn_balance | String | MXN balance | MXN |
btc_balance | String | BTC balance | BTC |
mxn_reserved | String | MXN locked in open orders | MXN |
btc_reserved | String | BTC locked in open orders | BTC |
mxn_available | String | MXN available for trading (balance - reserved) | MXN |
btc_available | String | BTC available for trading (balance - reserved) | BTC |
fee | String | Customer trading fee as a percentage for the btc_mxn book. | - |
User Transactions
The JSON dictionary returned by the API looks like this:
[
{
"datetime": "2015-10-10 16:19:33",
"method": "Bitcoin",
"btc": "0.48650929",
"type": 0
},
{
"datetime": "2015-10-09 13:49:00",
"method": "SPEI Transfer",
"mxn": "-1800.15",
"type": 1
},
{
"btc": "-0.25232073",
"datetime": "2015-10-09 13:45:46",
"mxn": "1023.77",
"rate": "4057.45",
"id": 51756,
"type": 2,
"order_id": "19vaqiv72drbphig81d3y1ywri0yg8miihs80ng217drpw7xyl0wmytdhtby2ygk"
}
]
Returns a list of the user’s transactions.
HTTP Request
POST https://api.bitso.com/v2/user_transactions
Body 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 |
offset | 0 | No | Skip that many transactions before beginning to return results |
limit | 100 | No | Limit result to that many transactions |
sort | desc | Sorting by date and time (asc - ascending; desc - descending) | |
book | btc_mxn | No | Specifies which book to use |
JSON Response
Returns a descending JSON Array of transactions. Every element in the array is a JSON dictionary:
Field Name | Type | Description | Units |
---|---|---|---|
datetime | String | Date and time | - |
id | long | Unique identifier (only for trades) | - |
type | int | Transaction type (0 - deposit; 1 - withdrawal; 2 - trade) | - |
method | String | Deposit or withdrawal method | - |
(minor currency code) | String | The minor currency amount | Minor |
(major currency code) | String | The major currency amount | Major |
order_id | String | A 64 character long hexadecimal string representing the order that was fully or partially filled (only for trades) | - |
rate | String | Price per minor (only for trades) | Minor |
Open Orders
The JSON dictionary returned by the API looks like this:
[
{
"amount": "0.01000000",
"datetime": "2015-11-12 12:37:01",
"price": "5600.00",
"id": "543cr2v32a1h684430tvcqx1b0vkr93wd694957cg8umhyrlzkgbaedmf976ia3v",
"type": "1",
"status": "1"
},
{
"amount": "0.12680000",
"datetime": "2015-11-12 12:33:47",
"price": "4000.00",
"id": "qlbga6b600n3xta7actori10z19acfb20njbtuhtu5xry7z8jswbaycazlkc0wf1",
"type": "0",
"status": "0"
},
{
"amount": "1.12560000",
"datetime": "2015-11-12 12:33:23",
"price": "6123.55",
"id": "d71e3xy2lowndkfmde6bwkdsvw62my6058e95cbr08eesu0687i5swyot4rf2yf8",
"type": "1",
"status": "0"
}
]
Returns a list of the user’s open orders.
HTTP Request
POST https://api.bitso.com/v2/open_orders
Body 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 |
book | btc_mxn | No | Specifies which book to use |
JSON Response
Returns a JSON Array of open orders. Every element in the array is a JSON dictionary:
Field Name | Type | Description | Units |
---|---|---|---|
datetime | String | Date and time | - |
id | String | The order ID | - |
type | String | The order type (0 - buy; 1 - sell) | - |
price | String | The order’s price | Minor |
amount | String | The order’s major currency amount | Major |
status | String | The order’s status (0 - active; 1 - partially filled) | - |
Lookup Order
The JSON dictionary returned by the API looks like this:
[{
"amount": "0.01000000",
"created": "2015-11-12 12:37:01",
"price": "5600.00",
"book": "btc_mxn",
"id": "543cr2v32a1h684430tvcqx1b0vkr93wd694957cg8umhyrlzkgbaedmf976ia3v",
"type": "1",
"updated": "2015-11-12 12:37:40",
"status": "-1"
}]
Returns a list of details for 1 or more orders
HTTP Request
POST https://api.bitso.com/v2/lookup_order
Body 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 |
id | - | Yes | A single or array of 64 characters long hexadecimal strings taken from the list of orders |
JSON Response
Returns a JSON Array with details about 1 or more orders. Each order is represented by a JSON dictionary:
Field Name | Type | Description | Units |
---|---|---|---|
id | String | The order ID passed to the API | - |
book | String | Which orderbook the order belongs to (not shown when status = 0) | - |
price | String | The order’s price | Minor |
amount | String | The order’s major currency amount | Major |
type | String | The order type (0 - buy; 1 - sell) | - |
status | String | The order’s status (-1 - cancelled; 0 - active; 1 - partially filled; 2 - complete) | - |
created | String | The date the order was created | - |
updated | String | The date the order was last updated (not shown when status = 0) |
Cancel Order
The string returned by the API looks like this:
"true"
Cancels an open order
HTTP Request
POST https://api.bitso.com/v2/cancel_order
Body 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 |
id | - | Yes | A 64 characters long hexadecimal string taken from the list of orders |
HTTP Response
Returns “true” (quotation marks included) if the order has been found and canceled. Otherwise it returns a JSON dictionary indicating the error
Place a Buy Order
The JSON dictionary returned by the API looks like this:
{
"amount": "0.10000000",
"datetime": "2015-11-12 12:53:28",
"price": "100.00",
"book": "btc_mxn",
"id": "kidxgibf009w85qykad1sdoktdmdlbo6t23akepkfzgn56mphzracfv6thjfs8lm",
"type": "0",
"status": "0"
}
Places a buy order (both limit and market orders are available)
HTTP Request
POST https://api.bitso.com/v2/buy
Body 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 |
book | btc_mxn | No | Specifies which book to use |
amount | - | Yes | The amount of major currency to buy. |
price | - | No | If supplied, this will place a limit order to buy at the specified price. If not supplied, this will place a market order to buy the amount of major currency specified in amount at the market rate |
JSON Response
Returns a JSON dictionary representing the order:
Field Name | Type | Description | Units |
---|---|---|---|
id | String | The order ID | - |
book | String | Which orderbook the order belongs to (not shown when status = 0) | - |
datetime | String | The date and time | |
type | String | The order type (0 - buy; 1 - sell) | - |
status | String | (Only for limit orders) The order’s status (-1 - cancelled; 0 - active; 1 - partially filled; 2 - complete) | - |
price | String | (Only for limit orders) The order’s price | Minor |
amount | String | (Only for limit orders) The order’s major amount | Major |
Place a Sell Order
The JSON dictionary returned by the API looks like this:
{
"amount": "0.01000000",
"datetime": "2015-11-12 13:29:33",
"price": "10000.00",
"book": "btc_mxn",
"id": "5umhs73uxry9ykblk923xxi48j4jhcwm7i40q7vnztxxd8jyil1gjkkr4obl1789",
"type": "1",
"status": "0"
}
Places a sell order (both limit and market orders are available)
HTTP Request
POST https://api.bitso.com/v2/sell
Body 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 |
book | btc_mxn | No | Specifies which book to use |
amount | - | Yes | Amount of major currency to sell |
price | - | No | If supplied, this will place a limit order to sell at the specified price. If not supplied, this will place a market order to sell the amount of major currency specified in amount at the market rate |
JSON Response
Returns a JSON dictionary representing the order:
Field Name | Type | Description | Units |
---|---|---|---|
id | String | The order ID | - |
book | String | Which orderbook the order belongs to (not shown when status = 0) | - |
datetime | String | The date and time | |
type | String | The order type (0 - buy; 1 - sell) | - |
status | String | (Only for limit orders) The order’s status (-1 - cancelled; 0 - active; 1 - partially filled; 2 - complete) | - |
price | String | (Only for limit orders) The order’s price | Minor |
amount | String | (Only for limit orders) The order’s major amount | Major |
Bitcoin Deposit
The string returned by the API looks like this:
"3CaPt93nYFzapDHMk6zZsXqiD8dJqKjWvb"
Gets a Bitcoin deposit address to fund your account
HTTP Request
POST https://api.bitso.com/v2/bitcoin_deposit_address
Body 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 |
HTTP Response
Returns a bitcoin deposit address (quotation marks included) that can be used to fund your account
Bitcoin Withdrawal
The string returned by the API looks like this:
"ok"
Triggers a bitcoin withdrawal from your account
HTTP Request
POST https://api.bitso.com/v2/bitcoin_withdrawal
Body 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 |
amount | - | Yes | The amount of BTC to withdraw from your account |
address | - | Yes | The Bitcoin address we will send the amount to |
HTTP Response
Returns “ok” (quotation marks included) if the withdrawal was successfully triggered. Otherwise it returns a JSON dictionary indicating the error
Ripple Withdrawal
The string returned by the API looks like this:
"ok"
Triggers a Ripple withdrawal from your account
HTTP Request
POST https://api.bitso.com/v2/ripple_withdrawal
Body 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 |
currency | - | Yes | The currency to withdraw |
amount | - | Yes | The amount of currency to withdraw from your account |
address | - | Yes | The ripple address we will send the amount to |
HTTP Response
Returns “ok” (quotation marks included) if the withdrawal was successfully triggered. Otherwise it returns a JSON dictionary indicating the error
Bank Withdrawal (SPEI)
The string returned by the API looks like this:
"ok"
Triggers a SPEI withdrawal from your account. These withdrawals are immediate during banking hours (M-F 9:00AM - 5:00PM Mexico City Time).
HTTP Request
POST https://api.bitso.com/v2/spei_withdrawal
Body 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 |
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 | - | Yes | The alpha-numeric reference number for this SPEI |
numeric_ref | - | Yes | The numeric reference for this SPEI |
HTTP Response
Returns “ok” (quotation marks included) if the withdrawal was successfully triggered. Otherwise it returns a JSON dictionary indicating the error
WebSocket API
General
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.
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 am 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. 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.
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 succesfuly 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) {
}
};
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 | Number | Amount | Major |
r | String | Rate | Minor |
v | String | Value | Minor |
Diff-Orders
Messages on this channel look like this:
{
"type": "diff-orders",
"book": "btc_mxn",
"payload": [
{
"d": 1455315979682,
"r": 7251.1,
"t": 1,
"a": 0.29437179,
"v": 2134.51
}
]
}
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 | Number | Amount | Major |
v | String | Value | Minor |
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 | Number | 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 dictionary returned by the API looks like this:
{
"quote":{
"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"
},
"rp":{
"id":"rp",
"name":"Ripple",
"required_fields":[
"ripple_address"
],
"minimum_transaction":"0.00",
"maximum_transaction":"10000000.00",
"fee":"5.00",
"daily_limit":"0.00",
"net":"495.00",
"available":"1",
"verification_level_requirement":"0"
},
"pm":{
"id":"pm",
"name":"Pademobile",
"required_fields":[
"phone_number"
],
"minimum_transaction":"1.00",
"maximum_transaction":"1000000.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"
}
},
"timestamp":"1425101044",
"expires_epoch":"1425101104"
},
"success":true
}
HTTP Request
POST https://api.bitso.com/v2/transfer_quote
Body Parameters
Parameter | Required | Description |
---|---|---|
btc_amount | No | Mutually exclusive with amount. Either this, or amount should be present in the request. The total amount in Bitcoins, as provided by the user. NOTE: The amount is in BTC format (900mbtc = .9 BTC). |
amount | No | Mutually exclusive with btc_amount. Either this, or btc_amount should be present in the request. The total amount in Fiat currency. Use this if you prefer specifying amounts in fiat instead of BTC. |
currency | Yes | An ISO 4217 fiat currency symbol (ie, “MXN”). If btc_amount is provided instead of amount, this is the currency to which the BTC price will be converted into. Otherwise, if amount is specified instead of btc_amount, this is the currency of the specified amount. |
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. |
key | Yes | API key (see Authentication) |
signature | Yes | Signature (see Authentication) |
nonce | Yes | nonce (see Authentication) |
Creating a Transfer
The JSON dictionary returned by the API looks like this:
{
"order":{
"btc_amount":"0.14965623",
"btc_pending":"0",
"btc_received":"0",
"confirmation_code":"9b2a4",
"created_at":"1425101044",
"currency":"MXN",
"currency_amount":"0",
"currency_fees":"0",
"currency_settled":"0",
"expires_epoch":1425101104,
"fields":{
"phone_number":"5554181042"
},
"id":"9b2a431b98597312e99cbff1ba432cbf",
"payment_outlet_id":"pm",
"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\/v2\/transfer\/9b2a431b98597312e99cbff1ba432cbf",
"wallet_address":"mgKZfNdFJgztvfvhEaGgMTQRQ2iHCadHGa"
},
"success":true
}
HTTP Request
POST https://api.bitso.com/v2/transfer_create
Body Parameters
Parameter | Required | Description |
---|---|---|
btc_amount | No | Mutually exclusive with amount. Either this, or amount should be present in the request. The total amount in Bitcoins, as provided by the user. NOTE: The amount is in BTC format (900mbtc = .9 BTC). |
amount | No | Mutually exclusive with btc_amount. Either this, or btc_amount should be present in the request. The total amount in Fiat currency. Use this if you prefer specifying amounts in fiat instead of BTC. |
currency | Yes | An ISO 4217 fiat currency symbol (ie, “MXN”). If btc_amount is provided instead of amount, this is the currency to which the BTC price will be converted into. Otherwise, if amount is specified instead of btc_amount, this is the currency of the specified amount. |
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 | |
key | Yes | API key (see Authentication) |
signature | Yes | Signature (see Authentication) |
nonce | Yes | nonce (see Authentication) |
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/v2/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).
Pademobile
Pademobile is a popular mobile wallet and payments system in Latin America and beyond. Users running the Pademobile wallet on their cellphone can carry a balance in local currency, and spend it at a variety of locations, including cash-out at stores such as 7-Eleven (this is limited to 300 MXN per day, per location).
Pademobile accounts are identified simply by the user’s phone number. Recipients who do not have smart phones, or who have not installed the wallet app, will receive a text message containing instructions on how to access the received funds.
For more information, please see: https://www.pademobile.com/en/mx/
Ripple
As a Ripple Gateway, Bitso is able to issue currencies such as the Mexican Peso directly into the Ripple Network. For more information on Ripple, please see: https://ripple.com/
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.