Private API

Authentication

To use private API, you need to get your access/secret key first. After signed up and verified, please visit API Tokens page to get your keys.

All private API requires 3 authentication parameters and zero or more API specific parameters. The 3 authentication parameters are:

access_key Your access key.
tonce Tonce is a timestamp in integer, stands for milliseconds elapsed since Unix epoch. Tonce must be within 30 seconds of server's current time. Each tonce can only be used once.
signature Signature of the API request, generated by you, use your secret key.

 

Signature is a hash of the request (in canonical string form):

hash = HMAC-SHA256(payload, secret_key).to_hex

Payload is a combination of HTTP verb, uri, and query string:

# canonical_verb is HTTP verb like GET/POST in upcase.
# canonical_uri is request path like /api/v2/markets.
# canonical_query is the request query sorted in alphabetica order, including access_key and tonce, e.g. access_key=xxx&foo=bar&tonce=123456789
# The combined string looks like: GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789
def payload
  "#{canonical_verb}|#{canonical_uri}|#{canonical_query}"
end

Note: query parameters are sorted in payload, so it must be "access_key=xxx&foo=bar" not "foo=bar&&access_key=xxx".

Suppose my secret key is 'yyy', then the result of HMAC-SHA256 of above payload is:

hash = HMAC-SHA256('GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789', 'yyy').to_hex
       = 'e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

Now we hav a signed request which can be used like this:

curl -X GET 'https://bsgex.com/api/v2/markets?access_key=xxx&foo=bar&tonce=123456789&signature=e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

 

Request limit

For security reasons Bsgex limits incoming requests to 6,000 requests/keypair/5minutes. If the requests exceed this quantity, API usage will be limited.

 

Response Format

Corresponding HTTP status code will be used in API response. Bsgex will also return a JSON structure including error details on failed request, for example:

{"error":{"code":1001,"message":"market does not have a valid value"}}

All errors follow the message format above, only differentiates in code and message. Code is a Bsgex defined error code, indicates the error's category, message is human-readable details.

Bsgex returns HTTP 200 response on successful request, with requested data in JSON format.

Data Type

Example

Comments

Market

{"at":1398410899, "ticker":{"buy":"3000.0","sell":"3100.0","low":"3000.0",
"high":"3000.0","last":"3000.0","vol":"0.11"}}
at: A timestamp in seconds since Epoch
buy/sell: Current buy/sell
pricelow/high: Lowest/highest price in last 24 hours
last: Last price
vol: Trade volume in last 24 hours

Member

{"sn":"BSG5TFFOGQHEX","name":"foo","email":"This email address is being protected from spambots. You need JavaScript enabled to view it.","activated":
true,"accounts":[{"currency":"bsg","balance":"100243840.0","locked":
"0.0"},{"currency":"btc","balance":"99999708.26","locked":"210.8"}]}
sn: Unique identifier of user
name: User name
email: User email
activated: Whether user is activated
accounts: User's accounts info, see Account

Account

{"currency":"bsg","balance":"100243840.0","locked":"0.0"}
currency: Account type, like 'btc' or 'bsg'balance: Account balance, exclude locked funds
locked: locked funds

Order

{"id":7,"side":"sell","price":"3100.0","avg_price":"3101.2","state":
"wait","market":"bsgbtc","created_at":"2014-04-18T02:02:33Z","volume"
:"100.0","remaining_volume":"89.8","executed_volume":"10.2","trades":
[{"id":2,"price":"3100.0","volume":"10.2","market":"bsgbtc","created_at
":"2014-04-18T02:04:49Z","side":"sell"}]}
id: Unique order ID
side: Buy/Sell
price: Order priceavg_price: Average execution price
state: wait, done or cancel. 'wait' represents the order is active, it may be a new order or partial complete order; 'done' means the order has been fulfilled completely; 'cancel' means the order has been cancelled.
market: Which market the order belongs to
created_at: Order created time
volume: volume to buy/sell
remaining_volume: remaining_volume is always less or equal than volume
executed_volume: volume = remaining_volume + executed_volume
trades: the order's trade history, see Trade.
Note: not all order include trades, only detailed order data returned by certain API will.

Trade

{"id":2,"price":"3100.0","volume":"10.2","market":"bsgbtc","created_at"
:"2014-04-18T02:04:49Z","side":"sell"}
id: Unique ID
price: trade price
volume: trade volume
market: the market trade belongs to, like 'bsgbtc'
created_at: trade time

OrderBook

{"asks": [...],"bids": [...]}
OrderBook shows orders on market.

 

Some Examples

Buy 1BTC at price 4000BSG:

curl -X POST 'https://bsgex.com/api/v2/orders' -d 'access_key=your_access_key&tonce=1234567&signature=computed_signature&market=bsgbtc&price=4000&side=buy&volume=1'

Create multiple orders with a single request:

curl -X POST 'https://bsgex.com/api/v2/orders/multi' -d 'access_key=your_access_key&tonce=123456789&signature=computed_signature&market=bsgbtc&orders[][price]=4000&orders[][side]=sell&orders[][volume]=0.5&orders[][price]=3999&orders[][side]=sell&orders[][volume]=0.99'

 

Tips/Caveats
API Detail
POST /api/v2/order/delete Cancel order is an asynchronous operation. A success response only means your cancel request has been accepted, it doesn't mean the order has been cancelled. You should always use /api/v2/order or websocket api to get order's latest state.
POST /api/v2/orders/clear Cancel all your orders is an asynchronous operation. A success response only means your request has been accepted. The orders in response may or may not have been cancelled yet.

 

Private API List

All Private API are listed below with details. Those require access_key/tonce/signature.

 

members

GET /v2/members/me.json            Get your profile and accounts info.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String

 

deposits

GET /v2/deposits.json            Get your deposits history.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String
currency   Currency value contains btc,bsg query String
limit   Set result limit. query Integer
state     query String

 

deposit

GET /v2/deposit.json            Get details of specific deposit.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String
txid (required)   query String

 

 deposit_address

 GET /v2/deposit_address.json            Where to deposit. The address field could be empty when a new address is generating (e.g. for bitcoin), you should try again later in that case.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String
currency (required) The account to which you want to deposit. Available values: btc, bsg query String

 

orders

GET /v2/orders.json            Get your orders, results is paginated.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String
market (required) Unique market id. It's always in the form of xxxyyy, where xxx is the base currency code, yyy is the quote currency code, e.g. 'bsgbtc'. All available markets can be found at /api/v2/markets. query String
state   Filter order by state, default to 'wait' (active orders). query String
limit   Limit the number of returned orders, default to 100. query Integer
page   Specify the page of paginated results. query Integer
order_by   If set, returned orders will be sorted in specific order, default to 'asc'. query String

 

POST /v2/orders.json            Create a Sell/Buy order.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. form String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. form Integer
signature (required) The signature of your request payload, generated using your secret key. form String
market (required) Unique market id. It's always in the form of xxxyyy, where xxx is the base currency code, yyy is the quote currency code, e.g. 'bsgbtc'. All available markets can be found at /api/v2/markets. form String
side (required) Either 'sell' or 'buy'. form String
volume (required) The amount user want to sell/buy. An order could be partially executed, e.g. an order sell 5 btc can be matched with a buy 3 btc order, left 2 btc to be sold; in this case the order's volume would be '5.0', its remaining_volume would be '2.0', its executed volume is '3.0'. form String
price   Price for each unit. e.g. If you want to sell/buy 1 BTC at 3000 BSG, the price is '3000.0' form String
ord_type     form String

 

POST /v2/orders/multi.json            Create multiple sell/buy orders.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. form String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. form Integer
signature (required) The signature of your request payload, generated using your secret key. form String
market (required) Unique market id. It's always in the form of xxxyyy, where xxx is the base currency code, yyy is the quote currency code, e.g. 'bsgbtc'. All available markets can be found at /api/v2/markets. form String
orders (required)   form Array
orders[side] (required) Either 'sell' or 'buy'. form String
orders[volume] (required) The amount user want to sell/buy. An order could be partially executed, e.g. an order sell 5 btc can be matched with a buy 3 btc order, left 2 btc to be sold; in this case the order's volume would be '5.0', its remaining_volume would be '2.0', its executed volume is '3.0'. form String
orders[price]   Price for each unit. e.g. If you want to sell/buy 1 BTC at 3000 BSG, the price is '3000.0' form String
orders[ord_type]     form String

 

POST /v2/orders/clear.json            Cancel all my orders.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. form String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. form Integer
signature (required) The signature of your request payload, generated using your secret key. form String
side   If present, only sell orders (asks) or buy orders (bids) will be canncelled. form String

 

order

GET /v2/order.json            Get information of specified order.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String
id (required) Unique order id. query Integer

 

POST /v2/order/delete.json            Cancel an order.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. form String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. form Integer
signature (required) The signature of your request payload, generated using your secret key. form String
id (required) Unique order id. form Integer

 

trades

GET /v2/trades/my.json            Get your executed trades. Trades are sorted in reverse creation order.

        Parameters

Parameter Value Description Parameter Type Data Type
access_key (required) Access key. query String
tonce (required) Tonce is an integer represents the milliseconds elapsed since Unix epoch. query Integer
signature (required) The signature of your request payload, generated using your secret key. query String
market (required) Unique market id. It's always in the form of xxxyyy, where xxx is the base currency code, yyy is the quote currency code, e.g. 'bsgbtc'. All available markets can be found at /api/v2/markets. query String
limit   Limit the number of returned trades. Default to 50. query Integer
timestamp   An integer represents the seconds elapsed since Unix epoch. If set, only trades executed before the time will be returned. query Integer
from   Trade id. If set, only trades created after the trade will be returned. query Integer
to   Trade id. If set, only trades created before the trade will be returned. query Integer
order_by   If set, returned trades will be sorted in specific order, default to 'desc'. query String