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

• Java
• NodeJS
• .NET
• Python
• Objective-C

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

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	-

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/ws_demo.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:

1. Request quote
2. Create transfer using quote
3. Send bitcoins to address given
4. 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.