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", |
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": |
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": |
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" |
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 |