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.
- PHP [mikerow] - https://github.com/mikerow/bitgrailphp
Public [Websocket] API
Push API
Example https://api.bitgrail.com/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
Markets
GET https://api.bitgrail.com/v1/markets
Return JSON with all tickers of all markets on BitGrail:
- Market
- 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
Ticker
GET https://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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://api.bitgrail.com/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.