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:

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.

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

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

deposits

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

        Parameters

deposit

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

        Parameters

 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

orders

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

        Parameters

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

        Parameters

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

        Parameters

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

        Parameters

order

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

        Parameters

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

        Parameters

trades

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

        Parameters