API Documentation


What API mean

BitGrail API allows to its customers to manage their accounts with third party softwares. There are available websocket API, GET/POST API for public and private calls (concern user's account).

Current stable and available version is v1.

Requests limit

You may perform no more than 60 calls per minute or we could ban temporarily you IP address.
For real time API is prefered to use websocket.

Examples

Here some scripts developed to interact with BitGrail API.

Public [Websocket] API

Push API

Example https://bitgrail.com/api/v1/websocket.html

Using websocket server wss://api.bitgrail.com is possible to signup to channels of differents market (ex. BTC-XRB) and get:

Array containing bids order book

  • price - Price offered for each single coin
  • amount - Sum of all requested coins

Array containing asks order book

  • price - Price asked for each single coin
  • amount - Sum of all offered coin

Array containing latest trades

  • date - Date of trade
  • price - Price for each single trade coin
  • amount - Sum of all traded coins

Public [GET] API

Ticker

GET https://bitgrail.com/api/v1/$FIAT-$COIN/ticker

Return JSON:

  • last - Latest trade price
  • high - Highest trade price in latest 24h
  • low - Lowest trade price in latest 24h
  • volume - Trade volume in latest 24h
  • coinVolume - Amount of traded coin in latest 24h
  • bid - Highest actual bid
  • ask - Lowest actual ask

Order book

GET https://bitgrail.com/api/v1/$FIAT-$COIN/orderbook

Return JSON composed by 2 array:

Array containing bids order book

  • price - Price offered for each single coin
  • amount - Sum of requested coins

Array containing asks order book

  • price - Price asked for each single coin
  • amount - Sum of all offered coins

Trade history

GET https://bitgrail.com/api/v1/$FIAT-$COIN/tradehistory

Return JSON of latest 500 transactions:

  • date - Trade date
  • price - Price for each trade coin
  • amount - Sum of all traded coins

Private [POST] API

Authentication

To use private API you have to create keys pair to authenticate user.

All private calls have to be composed by HTTP POST call, containing following 2 headers:

  • KEY - Public API key
  • SIGNATURE - encrypted POST parameters with HMAC-SHA512 alghoritm using your secret API key

Private calls, overmore, need the additional POST parameter, the nonce

  • nonce - Integer number, always greater then nonce of previous call.

Balances

POST https://bitgrail.com/api/v1/balances

To get balances of all coins present on BitGrail you don't need parameters, except the authentication ones.

Calls, if succesfully, return an array containing as index the coin code and these parameters:

  • balance - Balance available for user.
  • reserved - Balance not available for user (ex. locked due to open orders).

Buy order

POST https://bitgrail.com/api/v1/buyorder

To create a buy order these POST parameters are necessary.

  • market - (Es. BTC-XRB) Market to place the order.
  • amount - Decimal number with total amount of coin you wish to buy.
  • price - A decimal number representing the price you are available to pay for each single coin.

The call, if succesfully, returns array containing:

  • orderID - Unique ID of placed order.

Sell order

POST https://bitgrail.com/api/v1/sellorder

To create a sell order these POST parameters are necessary.

  • market - (Es. BTC-XRB) Market to place the order.
  • amount - Decimal number with total amount of coin you wish to sell.
  • price - A decimal number representing the price asked for each single coin.

The call, if succesfully, returns array containing:

  • orderID - Unique ID of placed order.

Open orders

POST https://bitgrail.com/api/v1/openorders

To get a list of open orders by a user, you don't need additional parameters.

If not, call returns array containing as index the unique ID of order and these parameters:

  • data - timestamp in unix format concerning order place date.
  • market - Market of the placed order.
  • price - Price for each single coin.
  • amount - Sum of order coins.
  • type - Kind of order.

Cancel order

POST https://bitgrail.com/api/v1/cancelorder

To delete a placed order, you need this POST parameter.

  • id - Unique ID of order you want to delete.

Call returns a success or error message


Get deposit address

POST https://bitgrail.com/api/v1/getdepositaddress

To get a deposit address, is necessary this POST parameter.

  • coin - Coin you wish to get deposit address.

If succesfully call returns an address containing an address or an error message.


Withdraw

POST https://bitgrail.com/api/v1/withdraw

If you wish to withdraw, you need these POST parameters.

  • coin - The coin you wish to withdraw.
  • amount - The amount to withdraw.
  • address - Address where you wish to receive your withdraw amount.

Call returns a success or error message


Last trades

POST https://bitgrail.com/api/v1/lasttrades

To get a list of latest trade of an user, you don't need additional parameters.

If call has success, it returns array containing as index the unique ID of trade and these parameters:

  • date - Unix timestamp of trade date.
  • market - Market where the order has been placed.
  • price - Price for each coin of the order.
  • amount - Sum of all order coins.
  • type - Kind of order.

Deposits history

POST https://bitgrail.com/api/v1/depositshistory

To get a list of deposits of an user, is necessary this POST parameter.

  • coin - The coin you wish to get deposits list.

Call returns an array containing as index the ID of deposit transaction and these parameters:

  • data - Unix timestamp of deposit date.
  • amount - Deposited amount.
  • status - Deposit status.

Withdraws history

POST https://bitgrail.com/api/v1/withdrawshistory

To get a list of withdrawals of an user, is necessary this POST parameter.

  • coin - The coin you wish to get withdrawals list.

Call returns an array containing as index the ID of withdraw transaction and these parameters:

  • data - Unix timestamp of withdraw date.
  • amount - Withdrawed amount.
  • status - Withdraw status.