HTTP API

HTTP Public API

HTTP Private API

Realtime API

API Documentation

bitFlyer Lightning offers two styles of API, the HTTP API and Realtime API.

Regions

API functionality may be limited by region. Specific products, such as market or future, may not be available in every region, specific order pairs may be limited to a specific region as well.

The U.S. may only trade BTC_USD at this time. European accounts may only trade BTC_EUR at this time.

HTTP API

Japan Endpoint URL: https://api.bitflyer.com/v1/ U.S. Endpoint URL: https://api.bitflyer.com/v1/ Europe Endpoint URL: https://api.bitflyer.com/v1/

You can try out our API at the API Playground.

API Limits

Please be aware of the HTTP API usage limits below.


Authentication

Authentication is required to callout the Private API. After login, on the developer's page, use the issued API key and API secret.

Include the following information in the HTTP request header.

ACCESS-SIGN is the resulting HMAC-SHA256 hash of the ACCESS-TIMESTAMP, HTTP method, request path, and request body concatenated together as a character string, created using your API secret.

// Node.js sample
var request = require('request');
var crypto = require('crypto');

var key = '{{ YOUR API KEY }}';
var secret = '{{ YOUR API SECRET }}';

var timestamp = Date.now().toString();
var method = 'POST';
var path = '/v1/me/sendchildorder';
var body = JSON.stringify({
    product_code: 'BTC_JPY',
    child_order_type: 'LIMIT',
    side: 'BUY',
    price: 30000,
    size: 0.1
});

var text = timestamp + method + path + body;
var sign = crypto.createHmac('sha256', secret).update(text).digest('hex');

var options = {
    url: 'https://api.bitflyer.com' + path,
    method: method,
    body: body,
    headers: {
        'ACCESS-KEY': key,
        'ACCESS-TIMESTAMP': timestamp,
        'ACCESS-SIGN': sign,
        'Content-Type': 'application/json'
    }
};
request(options, function (err, response, payload) {
    console.log(payload);
});

API key permissions

When you set up an API key, you can set the permissions for each key. In order to access a list of the permissions held by the API key, please use the Get API permissions API.

Pagination

The API that returns multiple results can read within the specified range.

HTTP Public API

Market List

Request

GET /v1/getmarkets
GET /v1/markets
GET /v1/getmarkets/usa
GET /v1/markets/usa
GET /v1/getmarkets/eu
GET /v1/markets/eu

Response

[
  { "product_code": "BTC_JPY" },
  { "product_code": "FX_BTC_JPY" },
  { "product_code": "ETH_BTC" },
  {
    "product_code": "BTCJPY28APR2017",
    "alias": "BTCJPY_MAT1WK"
  },
  {
    "product_code": "BTCJPY05MAY2017",
    "alias": "BTCJPY_MAT2WK"
  },
  {
    "product_code": "BTC_USD"
  }
]

Order Book

Request

GET /v1/getboard
GET /v1/board

Query parameters

Response

{
  "mid_price": 33320,
  "bids": [
    {
      "price": 30000,
      "size": 0.1
    },
    {
      "price": 25570,
      "size": 3
    }
  ],
  "asks": [
    {
      "price": 36640,
      "size": 5
    },
    {
      "price": 36700,
      "size": 1.2
    }
  ]
}

Ticker

Request

GET /v1/getticker
GET /v1/ticker

Query parameters

Response

{
  "product_code": "BTC_JPY",
  "timestamp": "2015-07-08T02:50:59.97",
  "tick_id": 3579,
  "best_bid": 30000,
  "best_ask": 36640,
  "best_bid_size": 0.1,
  "best_ask_size": 5,
  "total_bid_depth": 15.13,
  "total_ask_depth": 20,
  "ltp": 31690,
  "volume": 16819.26,
  "volume_by_product": 6819.26
}

Execution History

Request

GET /v1/getexecutions
GET /v1/executions

Query parameters

Response

[
  {
    "id": 39287,
    "side": "BUY",
    "price": 31690,
    "size": 27.04,
    "exec_date": "2015-07-08T02:43:34.823",
    "buy_child_order_acceptance_id": "JRF20150707-200203-452209",
    "sell_child_order_acceptance_id": "JRF20150708-024334-060234"
  },
  {
    "id": 39286,
    "side": "SELL",
    "price": 33170,
    "size": 0.36,
    "exec_date": "2015-07-08T02:43:34.72",
    "buy_child_order_acceptance_id": "JRF20150708-010230-400876",
    "sell_child_order_acceptance_id": "JRF20150708-024334-197755"
  }
]

Exchange status

This will allow you to determine the current status of the exchange.

Request

GET /v1/gethealth

Query parameters

Response

{
  "status": "NORMAL"
}

Chat

Request

GET /v1/getchats
GET /v1/getchats/usa
GET /v1/getchats/eu

Query parameters

Response

[
  {
    "nickname": "User1234567",
    "message": "Hello world!",
    "date": "2016-02-16T10:58:08.833"
  },
  {
    "nickname": "TestUser",
    "message": "TestHello",
    "date": "2016-02-15T10:18:06.67"
  }
]

Please note this request will only pull the chat logs from Japan if you use /v1/getchats. Use /v1/getchats/usa and /v1/getchats/eu to pull their respective regional chat logs.

HTTP Private API

Authentication is required to callout the Private API. See the Authentication section.

Get API Key Permissions

You can access a list of which HTTP Private APIs can be used with this API key.

Request

GET /v1/me/getpermissions

Response

[
  "/v1/me/getpermissions",
  "/v1/me/getbalance",
  "/v1/me/getcollateral",
  "/v1/me/getchildorders",
  "/v1/me/getparentorders",
  "/v1/me/getparentorder",
  "/v1/me/getexecutions",
  "/v1/me/getpositions"
]

Get Account Asset Balance

Request

GET /v1/me/getbalance

Response

[
  {
    "currency_code": "JPY",
    "amount": 1024078,
    "available": 508000
  },
  {
    "currency_code": "BTC",
    "amount": 10.24,
    "available": 4.12
  },
  {
    "currency_code": "ETH",
    "amount": 20.48,
    "available": 16.38
  }
]

Get Margin Status

Request

GET /v1/me/getcollateral

Response

{
  "collateral": 100000,
  "open_position_pnl": -715,
  "require_collateral": 19857,
  "keep_rate": 5.000
}

Request

GET /v1/me/getcollateralaccounts

Response

[
  {
    "currency_code": "JPY",
    "amount": 10000
  },
  {
    "currency_code": "BTC",
    "amount": 1.23
  }
]

Obtain details of your collateral balances (multiple currencies supported).

Get Bitcoin/Ethereum Deposit Addresses

Request

GET /v1/me/getaddresses

Response

[
  {
    "type": "NORMAL",
    "currency_code": "BTC",
    "address": "3AYrDq8zhF82NJ2ZaLwBMPmaNziaKPaxa7"
  },
  {
    "type": "NORMAL",
    "currency_code": "ETH",
    "address": "0x7fbB2CC24a3C0cd3789a44e9073381Ca6470853f"
  }
]

Get Bitcoin/Ether Deposit History

Request

GET /v1/me/getcoinins

Query parameters

Response

[
  {
    "id": 100,
    "order_id": "CDP20151227-024141-055555",
    "currency_code": "BTC",
    "amount": 0.00002,
    "address": "1WriteySQufKZ2pVuM1oMhPrTtTVFq35j",
    "tx_hash": "9f92ee65a176bb9545f7becb8706c50d07d4cee5ffca34d8be3ef11d411405ae",
    "status": "COMPLETED",
    "event_date": "2015-11-27T08:59:20.301"
  }
]

Get Bitcoin/Ether Transaction History

Request

GET /v1/me/getcoinouts

Query parameters

Response

[
  {
    "id": 500,
    "order_id": "CWD20151224-014040-077777",
    "currency_code": "BTC",
    "amount": 0.1234,
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "tx_hash": "724c07dfd4044abcb390b0412c3e707dd5c4f373f0a52b3bd295ce32b478c60a",
    "fee": 0.0005,
    "additional_fee": 0.0001,
    "status": "COMPLETED",
    "event_date": "2015-12-24T01:40:40.397"
  }
]

Get Summary of Bank Accounts

Returns a summary of bank accounts registered to your account.

Request

GET /v1/me/getbankaccounts

Response

[
  {
    "id": 3402,
    "is_verified": true,
    "bank_name": "Wells Fargo",
    "branch_name": "1231234123",
    "account_type": "Checking",
    "account_number": "1111111",
    "account_name": "Name on Account"
  }
]

Get Cash Deposits

Request

GET /v1/me/getdeposits

Query parameters

Response

[
  {
    "id": 300,
    "order_id": "MDP20151014-101010-033333",
    "currency_code": "JPY",
    "amount": 10000,
    "status": "COMPLETED",
    "event_date": "2015-10-14T10:10:10.001"
  }
]

Withdrawing Funds

Request

POST /v1/me/withdraw

Body parameters

{
  "currency_code": "JPY",
  "bank_account_id": 1234,
  "amount": 12000
}

Additional fees apply for withdrawals. Please see the Fees and Taxes page for reference.

Response

{
  "message_id": "69476620-5056-4003-bcbe-42658a2b041b"
}


Error Response:

{
  "status": -700,
  "error_message": "This account has not yet been authenticated",
  "data": null
}

If an error with a negative status value is returned, the cancellation has not been committed.

Get Deposit Cancellation History

Request

GET /v1/me/getwithdrawals

Query parameters

Response

[
  {
    "id": 700,
    "order_id": "MWD20151020-090909-011111",
    "currency_code": "JPY",
    "amount": 12000,
    "status": "COMPLETED",
    "event_date": "2015-10-20T09:09:09.416"
  }
]

Send a New Order

Request

POST /v1/me/sendchildorder

Body parameters

{
  "product_code": "BTC_JPY",
  "child_order_type": "LIMIT",
  "side": "BUY",
  "price": 30000,
  "size": 0.1,
  "minute_to_expire": 10000,
  "time_in_force": "GTC"
}

Response

If the parameters are correct, the status code will show 200 OK.

{
    "child_order_acceptance_id": "JRF20150707-050237-639234"
}

Cancel Order

Request

POST /v1/me/cancelchildorder

Body parameters

{
  "product_code": "BTC_JPY",
  "child_order_id": "JOR20150707-055555-022222"
}

{
  "product_code": "BTC_JPY",
  "child_order_acceptance_id": "JRF20150707-033333-099999"
}

Please specify only one between child_order_id and child_order_acceptance_id

Response

If the parameters are correct, the status code will show 200 OK.

Submit New Parent Order (Special order)

It is possible to place orders including logic other than simple limit orders (LIMIT) and market orders (MARKET). Such orders are handled as parent orders. By using a special order, it is possible to place orders in response to market conditions or place multiple associated orders.

Please read about the types of special orders and their methods in the bitFlyer Lightning documentation on special orders.

Request

POST /v1/me/sendparentorder

Body parameters

{
  "order_method": "IFDOCO",
  "minute_to_expire": 10000,
  "time_in_force": "GTC",
  "parameters": [{
    "product_code": "BTC_JPY",
    "condition_type": "LIMIT",
    "side": "BUY",
    "price": 30000,
    "size": 0.1
  },
  {
    "product_code": "BTC_JPY",
    "condition_type": "LIMIT",
    "side": "SELL",
    "price": 32000,
    "size": 0.1
  },
  {
    "product_code": "BTC_JPY",
    "condition_type": "STOP_LIMIT",
    "side": "SELL",
    "price": 28800,
    "trigger_price": 29000,
    "size": 0.1
  }]
}

In the parameters, specify an array of objects with the following keys and values.

Response

If the parameters are correct, the status code will show 200 OK.

{
  "parent_order_acceptance_id": "JRF20150707-050237-639234"
}

Cancel parent order

Parent orders can be canceled in the same manner as regular orders. If a parent order is canceled, the placed orders associated with that order will all be canceled.

Request

POST /v1/me/cancelparentorder

Body parameters

{
  "product_code": "BTC_JPY",
  "parent_order_id": "JCO20150925-055555-022222"
}

{
  "product_code": "BTC_JPY",
  "parent_order_acceptance_id": "JRF20150925-033333-099999"
}

Please specify only one between parent_order_id and parent_order_acceptance_id

Response

If the parameters are correct, the status code will show 200 OK.

Cancel All Orders

Request

POST /v1/me/cancelallchildorders

Body parameters

{
  "product_code": "BTC_JPY"
}

Response

If the parameters are correct, the status code will show 200 OK.

List Orders

Request

GET /v1/me/getchildorders

Query parameters

Response

[
  {
    "id": 138398,
    "child_order_id": "JOR20150707-084555-022523",
    "product_code": "BTC_JPY",
    "side": "BUY",
    "child_order_type": "LIMIT",
    "price": 30000,
    "average_price": 30000,
    "size": 0.1,
    "child_order_state": "COMPLETED",
    "expire_date": "2015-07-14T07:25:52",
    "child_order_date": "2015-07-07T08:45:53",
    "child_order_acceptance_id": "JRF20150707-084552-031927",
    "outstanding_size": 0,
    "cancel_size": 0,
    "executed_size": 0.1,
    "total_commission": 0
  },
  {
    "id": 138397,
    "child_order_id": "JOR20150707-084549-022519",
    "product_code": "BTC_JPY",
    "side": "SELL",
    "child_order_type": "LIMIT",
    "price": 30000,
    "average_price": 0,
    "size": 0.1,
    "child_order_state": "CANCELED",
    "expire_date": "2015-07-14T07:25:47",
    "child_order_date": "2015-07-07T08:45:47",
    "child_order_acceptance_id": "JRF20150707-084547-396699",
    "outstanding_size": 0,
    "cancel_size": 0.1,
    "executed_size": 0,
    "total_commission": 0
  }
]

List Parent Orders

Request

GET /v1/me/getparentorders

Query parameters

Response

[
  {
    "id": 138398,
    "parent_order_id": "JCO20150707-084555-022523",
    "product_code": "BTC_JPY",
    "side": "BUY",
    "parent_order_type": "STOP",
    "price": 30000,
    "average_price": 30000,
    "size": 0.1,
    "parent_order_state": "COMPLETED",
    "expire_date": "2015-07-14T07:25:52",
    "parent_order_date": "2015-07-07T08:45:53",
    "parent_order_acceptance_id": "JRF20150707-084552-031927",
    "outstanding_size": 0,
    "cancel_size": 0,
    "executed_size": 0.1,
    "total_commission": 0
  },
  {
    "id": 138397,
    "parent_order_id": "JCO20150707-084549-022519",
    "product_code": "BTC_JPY",
    "side": "SELL",
    "parent_order_type": "IFD",
    "price": 30000,
    "average_price": 0,
    "size": 0.1,
    "parent_order_state": "CANCELED",
    "expire_date": "2015-07-14T07:25:47",
    "parent_order_date": "2015-07-07T08:45:47",
    "parent_order_acceptance_id": "JRF20150707-084547-396699",
    "outstanding_size": 0,
    "cancel_size": 0.1,
    "executed_size": 0,
    "total_commission": 0
  }
]

price and size values for parent orders with multiple associated orders are both reference values only.

To obtain the detailed parameters for individual orders, use the API to obtain the details of the parent order. To obtain a list of associated orders, use the API to obtain the order list.

Get Parent Order Details

Request

GET /v1/me/getparentorder

Query parameters

Please specify only parent_order_id or parent_order_acceptance_id.

Response

{
  "id": 4242,
  "parent_order_id": "JCO20150925-046876-036161",
  "order_method": "IFDOCO",
  "minute_to_expire": 10000,
  "parameters": [{
    "product_code": "BTC_JPY",
    "condition_type": "LIMIT",
    "side": "BUY",
    "price": 30000,
    "size": 0.1,
    "trigger_price": 0,
    "offset": 0
  }, {
    "product_code": "BTC_JPY",
    "condition_type": "LIMIT",
    "side": "SELL",
    "price": 32000,
    "size": 0.1,
    "trigger_price": 0,
    "offset": 0
  }, {
    "product_code": "BTC_JPY",
    "condition_type": "STOP_LIMIT",
    "side": "SELL",
    "price": 28800,
    "size": 0.1,
    "trigger_price": 29000,
    "offset": 0
  }],
  "parent_order_acceptance_id": "JRF20150925-060559-396699"
}

List Executions

Request

GET /v1/me/getexecutions

Query parameters

Response

[
  {
    "id": 37233,
    "child_order_id": "JOR20150707-060559-021935",
    "side": "BUY",
    "price": 33470,
    "size": 0.01,
    "commission": 0,
    "exec_date": "2015-07-07T09:57:40.397",
    "child_order_acceptance_id": "JRF20150707-060559-396699"
  },
  {
    "id": 37232,
    "child_order_id": "JOR20150707-060426-021925",
    "side": "BUY",
    "price": 33470,
    "size": 0.01,
    "commission": 0,
    "exec_date": "2015-07-07T09:57:40.397",
    "child_order_acceptance_id": "JRF20150707-060559-396699"
  }
]

List Balance History

Request

GET /v1/me/getbalancehistory

Query parameters

Response

[
  { 
    "id": 1000108,
    "trade_date": "2016-10-19T14:44:55.28", 
    "product_code": "BTC_USD",
    "currency_code": "USD",
    "trade_type": "SELL",
    "price": 9999.99,
    "amount": 99.99,
    "quantity": 99.99,
    "commission": 0,
    "balance": 9999999.99,
    "order_id": "JORYYYYMMDD‌-0000000-000000X" 
  },
  { 
    "id": 1000107,
    "trade_date": "2016-10-19T14:41:35.23",
    "product_code": "BTC_USD",
    "currency_code": "USD",
    "trade_type": "SELL",
    "price": 9999.99,
    "amount": 999.99,
    "quantity": 99.99,
    "commission": 0,
    "balance": 9999999.99,
    "order_id": "JORYYYMMDD‌-000000-000000X" 
  }
]

trade_type:

Get Open Interest Summary

Request

GET /v1/me/getpositions

Query parameters

Response

[
  {
    "product_code": "FX_BTC_JPY",
    "side": "BUY",
    "price": 36000,
    "size": 10,
    "commission": 0,
    "swap_point_accumulate": -35,
    "require_collateral": 120000,
    "open_date": "2015-11-03T10:04:45.011",
    "leverage": 3,
    "pnl": 965,
    "sfd": -0.5
  }
]

Get Margin Change History

Request

GET /v1/me/getcollateralhistory

Query parameters

Response

[
  {
    "id": 4995,
    "currency_code": "JPY",
    "change": -6,
    "amount": -6,
    "reason_code": "CLEARING_COLL",
    "date": "2017-05-18T02:37:41.327"
  },
  {
    "id": 4994,
    "currency_code": "JPY",
    "change": 2083698,
    "amount": 0,
    "reason_code": "EXCHANGE_COLL",
    "date": "2017-04-28T03:05:07.493"
  },
  {
    "id": 4993,
    "currency_code": "BTC",
    "change": -14.69001618,
    "amount": 34.97163164,
    "reason_code": "EXCHANGE_COLL",
    "date": "2017-04-28T03:05:07.493"
  }
]

Get Trading Commission

Request

GET /v1/me/gettradingcommission

Query parameters

Response

{
  "commission_rate": 0.001
}

Realtime API

bitFlyer supports 3 protocols for real-time updates.

Socket.IO 2.0 (WebSocket)

Endpoint URL: https://io.lightstream.bitflyer.com

Events:

Methods:

Sample:

// Node.js / JavaScript sample
const io = require('socket.io-client');
const socket = io("https://io.lightstream.bitflyer.com", { transports: ["websocket"] });

const channelName = "lightning_ticker_BTC_JPY";
socket.on("connect", () => {
socket.emit("subscribe", channelName);
});
socket.on(channelName, message => {
    console.log(channelName, message);
});

See more samples: Realtime API Playground

JSON-RPC 2.0 over WebSocket

Endpoint URL: wss://ws.lightstream.bitflyer.com/json-rpc

Events:

Methods:

Sample:

// Node.js / JavaScript sample
const WebSocket = require("rpc-websockets").Client;
const ws = new WebSocket("wss://ws.lightstream.bitflyer.com/json-rpc");

const channelName = "lightning_ticker_BTC_JPY";
ws.on("open", () => {
    ws.call("subscribe", {
        channel: channelName
    });
});
ws.on("channelMessage", notify => {
    console.log(notify.channel, notify.message);
});

See more samples: Realtime API Playground

Order Book

Channel Name

The channel name should be the product_code of a market from the Market List appended to lightning_board_snapshot_. (alias cannot be used.)

Response

Snapshot of the Order Book. If the data size becomes too large, data distribution on each update cannot be guaranteed. To return the data upon each update, please use Order Book Updates.

Please refer to the Order Book section for a sample response.

Order Book Updates

Channel Name

The channel name should be the product_code of a market from the Market List appended to lightning_board_. (alias cannot be used.)

Response

If there is an order update on the board, the updated information is sent out. The following response shows the order's updated ¥33350 bid and the total quantity of 1 BTC.

{
  mid_price: 35625,
  bids: [
    {
      price: 33350,
      size: 1
    }
  ],
  asks: []
}

Ticker

Channel Name

Response

Sent out each time there is an update. See the Ticker section.

Execution

Channel Name

Response

Sent out each time an execution is created.

[
  {
    "id": 39361,
    "side": "SELL",
    "price": 35100,
    "size": 0.01,
    "exec_date": "2015-07-07T10:44:33.547",
    "buy_child_order_acceptance_id": "JRF20150707-014356-184990",
    "sell_child_order_acceptance_id": "JRF20150707-104433-186048"
  }
]