cryptox/docs/api_documentation.md at master · dutu/cryptox

cryptox API Documentation

=======

Constructor
Methods
NOTES
- Currency Symbols
- Currency Pairs

Constructor

Creates an instance of Cryptox object type.

Cryptox(exchangeSlug [, options])

Depending on the parameters used, two types of objects can be created

public (without authentication) - can be used for calling public API methods
private (with authentication) - can be used for calling public and private API methods

Examples

var account = new Cryptox("btce", {key: "yourKey", secret: "yourSecret"});

var exchange = new Cryptox("btce");

Arguments

exchangeSlug is required and should have one values in table below
options is used to pass parameters required for authentication, as indicated in table below

Exchange name	`exchangeSlug`	Authentication
Bitfinex	`"bitfinex"`	`key`, `secret`
Bitstamp	`"bitstamp"`	`key`, `secret`, `username`
BitX	`"bitx"`	`key`, `secret`
BTC-e	`"btce"`	`key`, `secret`
CEX.io	`"cexio"`	`key`, `secret`, `username`
Gdax	`"gdax"`	`key`, `secret`, `passphrase`
Poloniex	`"poloniex"`	`key`, `secret`
Open Exchange Rates	`"oxr"`	`key`

options should be used when calling methods that require authentication. Missing or incorrect key/secret causes an error to be returned when calling a method that requires authentication (see Authentication).

Methods

Examples

getTicker(options, callback);

getTicker({pair: "XBT_USD"}, function (err, result) {
    if (!err)
        console.log(result);
});

Arguments

options is a JSON object containing parameters specific for each API call
callback is executed inside the method once the API response is received from the exchange

Callbacks

The arguments passed to the callback function for each method are:

err is an error object or null if no error occurred.

result is JSON object containing the response.

Example result:

{
    "timestamp": "2015-02-03T00:01:48+00:00",
    "error": "",
    "data": [
        {
            "pair": "XBT_USD",
            "last": "272.064",
            "bid": "272.064",
            "ask": "273.395",
            "volume": "7087.93047"
        }
     ]
}

          |  Type  | Description

--- | --- | ---
timestamp | string | ISO 8601 date & time
error | string | error message or "" if no error
data | array | array of one or more JSON objects containig the API result

Results

The format of API result (see result in Callbacks) above for each method is described in this document and it complies with JSON schemas in jsonSchemas.js

Authentication

Following methods require authentication

Method	Requires authentication
getRate	^[1]
getTicker
getOrderBook
getTrades
getFee	√ ^[2]
getTransactions	√
getBalance	√
getMarginPositions	√
getOpenOrders	√
postSellOrder	√
placeBuyOrder	√
cancelOrder	√

¹ Open Exchange Rates (OXR) requires authentication
² BTC-e and BitX does not require authentication (since the fee is fixed amount)

When calling a method that requires authentication, the object should have been constructed with parameters key, secret and (optional) userId.

getRate

Returns the exchange rate.

getRate(options, callback);

Example

exchange.getRate({pair: "EUR_USD"}, function (err, rate) {
    if (!err)
        console.log(rate);
});

Example result:

{
  "timestamp": "2016-10-16T15:00:07Z",
  "error": "",
  "data": [
    {
      "pair": "EUR_USD",
      "rate": "1.09727328"
    }
  ]
}

Arguments

options

Parameter	Type	Required for	Description
`pair`	string	All	currency pair

callback see Callbacks

Response

Parameter	Type	Description
`pair`	String	currency pair
`rate`	String	rate

getTicker

Returns the latest ticker indicators.

getTicker(options, callback);

Example

exchange.getTicker({pair: "XBT_USD"}, function (err, ticker) {
    if (!err)
        console.log(ticker);
});

Example result:

{
    "timestamp": "2015-02-03T00:01:48+00:00",
    "error": "",
    "data": [
        {
            "pair": "XBT_USD",
            "last": "272.064",
            "bid": "272.064",
            "ask": "273.395",
            "volume": "7087.93047"
        }
     ]
}

Arguments

options

Parameter	Type	Required for	Description
`pair`	string	BTC-e, Bitfinex	trading pair

callback see Callbacks

Response

Parameter	Type	Description
`pair`	String	trading pair
`last`	String	the price at which the last order executed
`bid`	String	highest buy order
`ask`	String	lowest sell order
`volume`	String	trading volume of the last 24 hours

Optional response parameters

Parameter / Availability	Type	Description
`high` ^{[1] [2]}	String	Highest trade price of the last 24 hours
`low` ^{[1] [2]}	String	Lowest trade price of the last 24 hours
`vwap` ^[1]	String	last 24 hours volume weighted average price

^[1] Bitstamp
^[2] Bitfinex

getOrderBook

Returns a list of bids and asks in the order book. Ask orders are sorted by price ascending. Bid orders are sorted by price descending. Note that multiple orders at the same price are not necessarily conflated.

cryptox.getOrderBook(options, callback);

Example

exchange.getOrderBook({pair: "BTC_USD"}, function (err, orderBook) {
    if (!err)
        console.log(orderBook);
});

Example result:

{
    "timestamp": ""2015-02-03T00:01:48+00:00"",
    "error": "",
    "data": [
        {
            "pair": "BTC_USD",
            "asks": [{price: "212.962", volume: "0.014"}, {price: "213", volume: "1.46820994"}],
            "bids": [{price: "212.885", volume: "0.014"}, {price: "212.827", volume: "0.00414864"]}
         }
    ]
}

Arguments

options

Parameter Type Required Description

pair string All exchanges trading pair
callback see Callbacks

Parameter	Type	Required	Description
`pair`	string	All exchanges	trading pair

Response

Parameter	Type	Required	Description
`pair`	String	Yes	trading pair
`asks`	Array	Yes	list of asks in the order book
`bids`	Array	Yes	list of bids in the order book

getTrades

Returns a list of the most recent trades.

cryptox.getTrades(options, callback);

Example

exchange.getTrades({pair: "BTC_USD"}, function (err, trades) {
    if (!err)
        console.log(trades);
});

Example result:

{
  timestamp: "2016-10-09T08:06:30Z",
  error: "",
  data: [
    {
      pair: "BTC_USD",
      trades: [
        {
          timestamp: "2016-10-09T08:05:17Z",
          trade_id: "11298830",
          price: "618.34000000",
          amount: "0.01000000",
          type: "buy"
        },
        {
          timestamp: "2016-10-09T07:31:16Z",
          trade_id: "11298732",
          price: "618.26000000",
          amount: "0.87449356",
          type: "sell"
        }
      ]
    }
  ]
}

Arguments

options

Parameter Type Required Description

pair string All exchanges trading pair
callback see Callbacks

Parameter	Type	Required	Description
`pair`	string	All exchanges	trading pair

Response

Parameter	Type	Required	Description
`pair`	String	Yes	trading pair
`trades`	Array	Yes	list of asks in the order book

getFee

getFee(options, callback);

Returns the fee, which is a float that represents the amount the exchange takes out of the orders.

Example

account.getFee({pair: "XBT_USD"}, function (err, fee) {
    if (!err)
	    console.log(fee);
});

Example result:

{ 
	timestamp: "2015-02-01T20:59:53+00:00",
	data: [
	   {
		  pair: "XBT_USD",
		  maker_fee: "0",
		  taker_fee: "0.002"
	   }
	]
}

Arguments

options

Parameter Type Required Description

pair string All exchanges trading pair
callback see Callbacks

Parameter	Type	Required	Description
`pair`	string	All exchanges	trading pair

Response

Parameter	Type	Description
`pair`	String	the trading pair or `""` if the fee is applicable for all pairs
`maker_fee` ^{[1] [2]}	String	the amount (%) the exchange takes out of limit orders
`taker_fee` ^{[1] [2]}	String	the amount (%) the exchange takes out of orders that match immediately

^[1] "maker" fees are paid when you add liquidity to the orderbook, by placing a limit order under the ticker price for buy and above the ticker price for sell. "taker" fees are paid when you remove liquidity from the orderbook, by placing any order that is executed against an order of the orderbook. if type is "", the fee is applicable both for maker and taker
^[2] If an exchange has a fee of 0.2% the fee would be 0.002

getTransactions

getTransactions(options, callback);

Returns user transaction history. Transactions are returned in descending order (newer transactions first).

Note: Depending on the exchange used and parameter combination this method can require up to 10 API calls

Example

account.getTransactions({limit: 2, sort: "desc"}, function (err, transactions) {
    if (!err)
	    console.log(transactions);
});

Example result:

{
    {
    "timestamp": "2015-02-25T22:37:19+00:00",
    "error": "",
    "data": [
        {
            "tx_id": "7624780",
            "datetime": "2015-02-24T12:02:27+00:00",
            "type": "sell",
            "symbol": "XBT_USD",
            "amount_base": "-0.30183411",
            "amount_counter": "72.62",
            "rate": "240.6",
            "fee_base": "0",
            "fee_counter": "0.15",
            "order_id": "58025817",
            "add_info": ""
        },
        {
            "tx_id": "7624695",
            "datetime": "2015-02-24T11:45:26+00:00",
            "type": "deposit",
            "symbol": "XBT",
            "amount_base": "49.04253049",
            "amount_counter": "0",
            "rate": "0",
            "fee_base": "0",
            "fee_counter": "0",
            "order_id": "",
            "add_info": ""
        }
    ]
}

Arguments

options

Parameter	Type	Required	Description
`limit`	Number	no	limit result to that many transactions. Default: `50`
`skip`	Number	no	skip that many transactions before beginning to return results
`after`	String	no	return only transactions after or at the time specified here (ISO 8601 string)
`before`	String	no	return only transactions before or at the time specified here (ISO 8601 string)
`type`	String	no	return only transactions of this type ^[1]. Default return all transactions
`symbol`	String	no	return only transactions related to this curency symbol or curency pair

^[1] valid values are "trades" (for buys or sells) or "movements" (for deposits and withdrawals)
^[2] valid values are currecny symbols (3 characters) or trading pair symbols (6 characters).

callback see Callbacks

Response

Parameter	Type	Description
`tx_id`	String	transaction ID
`datetime`	String	ISO 8601 date & time of the transaction
`type`	String	transaction type: `"buy"`, `"sell"`, `"deposit"`, `"withdrawal"`
`symbol`	String	currency symbol ^[1] or currency pair ^[2]
`amount_base`	String	currency amount ^[1] or base currency amount ^{[3] [4]}
`amount_counter`	String	counter currency amount ^{[3] [4]}
`rate`	String	zero (`0`) ^[1] or the exchange rate ^{[2] [3]}
`fee_base`	String	amount of the fees debited
`fee_counter`	String	amount of the fees debited
`order_id`	String	the id of the parent order of the trade. Can be `""`
`add_info`	String	additional info. Can be `""`

^[1] for single currency transaction ("deposit" or "withdrawal")
^[2] for trades / pair transaction ("buy" or "sell")
^[3] See Currency Pairs
^[3] The amount_base and amount_counter are the amounts that were traded after the fees were deducted. These are the amounts that were credited/debited from your account

getBalance

getBalance(options, callback);

Returns the account balance.

Example

account.getBalance({}, function (err, balance) {
    if (!err)
	    console.log(balance);
});

Example result:

{
    timestamp: "2015-02-06T17:53:02+00:00",
    error: "",
    data: [
        {
            account_id: "8274332321",
            total: [
                {currency: "XBT", amount: "4.86509177"},
                {currency: "USD", amount: "100.44"}
            ],
            available: [
                {currency: "XBT", amount: "2.86709177"},
            ]
        }
    ]
}

Arguments

options argument is not used and it is ignored, except for poloniex. For poloniex { account: 'all' } can be used for summing up the balances of all accounts (exchange, margin and lending)
callback see Callbacks

Response

Parameter	Type	Description
`account_id`	String	account ID / name
`total`	Array	account balance
`available`	Array	funds available for trading (balance minus funds reserved in open orders. For margin accounts the leverage is taken into consideration, hence `available` can be higher than `total`)

getMarginPositions

getMarginPositions(options, callback);

Returns the account balance.

Example

account.getMarginPositions({pair: BTC_USD}, function (err, marginPositions) {
    if (!err)
	    console.log(balance);
});

Example result:

{
    timestamp: "2015-02-06T17:53:02+00:00",
    error: "",
    data: [
        {
        }
    ]
}

Arguments

options

Parameter Type Description

pair String trading pair (optional)
callback see Callbacks

Parameter	Type	Description
`pair`	String	trading pair (optional)

Response

Parameter	Type	Description
`pair`	String	account ID / name
`total`	Array	account balance
`available`	Array	funds available for trading (balance minus funds reserved in open orders. For margin accounts the leverage is taken into consideration, hence `available` can be higher than `total`)

getOpenOrders

getOpenOrders(options, callback);

Returns the open orders.

Example

account.getOpenOrders({pair: "LTC_USD"}, function (err, openOrders) {
    if (!err)
	    console.log(openOrders);
});

Example result:

{
    "timestamp": "2015-02-03T00:03:27+00:00",
    "error": "",
    "data": [
        {
            "order_id": "563489985",
            "pair": "LTC_USD",
            "type": "buy",
            "amount": "1",
            "rate": "0.1",
			"margin": true,
            "created_at": "2015-02-01T19:23:15+00:00",
            "status": "0"

        },
        {
            "order_id": "563612426",
            "pair": "LTC_USD",
            "type": "buy",
            "amount": "2",
            "rate": "0.5",
			"margin": false,
            "created_at": "2015-02-01T20:59:53+00:00",
            "status": "0"

        }        
    ]
}

Arguments

options
callback see Callbacks

Response

Parameter	Type	Description
`order_id`	String	order ID
`pair`	String	trading pair
`type`	String	order type (`buy`, `sell`)
`amount`	String	trading amount
`rate`	String	rate
`margin`	Boolean	margin trading order
`created_at`	String	date&time when order was created, ISO 8601 string

Optional response parameters

Parameter / Availability	Type	Description
`status`	Number	order status ^[1]

^[1] BTC-e API description doesn't clarify what status value means

postSellOrder

postSellOrder(options, callback);

Posts a sell order.

Example

account.postSellOrder({pair: "ETH_BTC"}, function (err, order) {
    if (!err)
	    console.log(openOrders);
});

Example result:

{
    "timestamp": "2015-02-03T00:03:27+00:00",
    "error": "",
    "data": [
        {
            "order_id": "563489985",
            "created_at": "2015-02-01T19:23:15+00:00",

        }
    ]
}

Arguments

options

Parameter Type Description

pair String trading pair

amount String trading amount

rate String rate

margin Boolean margin trading order
callback see Callbacks

Response

Parameter	Type	Description
`order_id`	String	order ID
`created_at`	String	date&time when order was created, ISO 8601 string

postBuyOrder

Same as for postSellOrder() method

cancelOrder

cancelOrder(options, callback);

Posts a sell order.

Example

account.cancelOrder({order_id: "123456789"}, function (err, order) {
    if (!err)
	    console.log(openOrders);
});

Example result:

{
    "timestamp": "2015-02-03T00:03:27+00:00",
    "error": "",
    "data": []
}

Arguments

options

Parameter Type Required Description

order_id string All exchanges currecny
callback see Callbacks

Parameter	Type	Required	Description
`order_id`	string	All exchanges	currecny

Response

Parameter	Type	Description

getLendBook

Returns the lend book. Note that multiple asks/bids at the same rate are not necessarily conflated.

cryptox.getOrderBook(options, callback);

Example

exchange.getLendBook({currency: "USD"}, function (err, orderBook) {
    if (!err)
        console.log(lendBook);
});

Example result:

{
	"timestamp": "2015-03-14T16:49:12+00:00",
	"error": "",
	"data": [
		{
			"currency": "USD",
			"asks": [
				{
					"rate": "36.5",
					"amount": "1441.80137112",
					"period": 2,
					"frr": "yes"
					"created_at": "2015-03-14T16:32:17+00:00",
				}
			],
			"bids": [
				{
					"rate": "32.8573",
					"amount": "6163.37130384",
					"period": 30,
					"frr": "no"
					"created_at": "2015-03-14T15:27:38+00:00",
				}
	
			]
		}
	]
}

Arguments

options

Parameter Type Required Description

currency string All exchanges currecny
callback see Callbacks

Parameter	Type	Required	Description
`currency`	string	All exchanges	currecny

Response

Parameter	Type	Required	Description
`asks`	Array	Yes	loan offers
`bids`	Array	Yes	loan demands
`rate`	String	Yes	rate in % per 365 days
`amount`	String	Yes	amount
`period`	Number	Yes	maximum no of days for the loan offers or minimum no of days for the demand offers
`frr`	String	Yes	`"yes"` if the offer is at Flash Return Rate, `"no"` if the offer is at fixed rate
`created_at`	String	Yes	date&time when offer was created, ISO 8601 string

getActiveOffers

postOffer

cancelOffer

Native API calls

cryptox supports native API methods. The parameter and callback results are as described in the follwoing packages:

Bitfinex: https://github.com/bitfinexcom/bitfinex-api-node
Bitstamp: https://github.com/askmike/bitstamp
BitX: https://github.com/bausmeier/node-bitx
BTC-e: https://github.com/pskupinski/node-btc-e
Gdax: https://github.com/coinbase/gdax-node
Poloniex: https://github.com/dutu/poloniex-api-node

Example

var btce = new Cryptox("btce");
btce.native.ticker("ltc_btc", function(err, data) {
  console.log(err, data);
});

Notes

Currency Symbols

cryptox uses ISO 4217 currency codes for fiat currencies and 3 letter symbols for cryptocurrencies

Currency	Symbol
Auroracoin	AUR
Bitcoin	XBT ^[1]
BlackCoin	BLK
Darkcoin	DRK
Dogecoin	DGE
Gridcoin	GRC
Litecoin	LTC
Mastercoin	MSC
MazaCoin	MZC
Monero	XMR
Namecoin	NMC
Nxt	NXT
Peercoin	PPC
PotCoin	POT
Primecoin	XPM
Ripple	XRP
Titcoin	TIT

^[1] See FAQ

Currency Pairs

The first currency of a currency pair is called the "base currency", and the second currency is called the "counter currency". The currency pair shows how much of the counter currency is needed to purchase one unit of the base currency.

In example below the last price of the XBT_USD currency pair is 272.064.

    "timestamp": "2015-02-03T00:01:48+00:00",
    "error": "",
    "data": [
        {
            "pair": "XBT_USD",
            "last": 272.064,
            "bid": 272.064,
            "ask": 273.395,
            "volume": 7087.93047
        }
     ]
}

This means that 1 Bitcoin was exchanged for 272.006 US dollars.

FilesExpand file tree

api_documentation.md

Latest commit

History

api_documentation.md

File metadata and controls

Contents

Constructor

Examples

Arguments

Methods

Examples

Arguments

Callbacks

Results

Authentication

getRate

Example

Arguments

Response

getTicker

Example

Arguments

Response

getOrderBook

Example

Arguments

Response

getTrades

Example

Arguments

Response

getFee

Example

Arguments

Response

getTransactions

Example

Arguments

Response

getBalance

Example

Arguments

Response

getMarginPositions

Example

Arguments

Response

getOpenOrders

Example

Arguments

Response

postSellOrder

Example

Arguments

Response

postBuyOrder

cancelOrder

Example

Arguments

Response

getLendBook

Example

Arguments

Response

getActiveOffers

postOffer

cancelOffer

Native API calls

Example

Notes

Currency Symbols

Currency Pairs