JOYSO

JOYSO API client library for trading.

Notice

v0.3.0 has breaking changes. Please see CHANGELOG v0.3.0

Installation

You can use this command to install:

npm install joyso

Usage

Setup and connect to JOYSO

const Joyso = require('joyso');

async function start() {
  const joyso = new Joyso({
    // your private key
    key: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
  });

  await joyso.connect();
}

subscribeOrderBook(pair, callback)

Subscribe order book, notify if change.

const subscription = joyso.subscribeOrderBook('JOY_ETH', orderBook => {
  console.log(JSON.stringify(orderBook));
});

Result:

{
  "buy":[
    {
      "price":0.000123456,
      "amount":"8.5"
    },
    {
      "price":0.000123455,
      "amount":"98.5"
    }
  ],
  "sell":[
    {
      "price":0.00012346,
      "amount":"100"
    },
    {
      "price":0.00012347,
      "amount":"500"
    }
  ]
}

• amount is BigNumber object.

subscribeTrades(pair, callback)

Subscribe market trades, notify if change, return last 100 records.

const subscription = joyso.subscribeTrades('JOY_ETH', trades => {
  console.log(JSON.stringify(trades.slice(0, 2)));
});

Result

[
  {
    "id":317,
    "side":"sell",
    "price":0.000123456,
    "amount":"2",
    "pair":"JOY_ETH"
  },
  {
    "id":315,
    "side":"buy",
    "price":0.00012347,
    "amount":"1",
    "pair":"JOY_ETH"
  }
]

• amount is BigNumber object.

subscribeBalances(callback)

Subscribe balances, notify if change.

const subscription = joyso.subscribeBalances(balances => {
  console.log(JSON.stringify(balances));
});

Result

{
  "JOY":{
    "inOrder":"0",
    "available":"4.5"
  },
  "ETH":{
    "inOrder":"0.001447757819",
    "available":"0.097815997145"
  }
}

• inOrder and available are BigNumber objects.

subscribeOrders(callback)

Subscribe open orders, notify if change.

const subscription = joyso.subscribeOrders(orders => {
  console.log(JSON.stringify(orders));
});

Result

[
  {
    "id":353,
    "status":"active",
    "side":"buy",
    "price":0.000123481,
    "amount":"1",
    "fill":"0",
    "pair":"T00_ETH"
  },
  {
    "id":326,
    "status":"partial",
    "side":"buy",
    "price":0.000123456,
    "amount":"12",
    "fill":"3.5",
    "pair":"JOY_ETH"
  }
]

• amount and fill are BigNumber objects.
• status could be active or partial

subscribeMyTrades(callback)

Subscribe my trades, notify if change, return last 100 records.

const subscription = joyso.subscribeMyTrades(trades => {
  console.log(JSON.stringify(trades.slice(0, 2)));
});

Result

[
  {
    "id":317,
    "status":"done",
    "txHash":"0xcf0aeb815200951559a38650a84f8eefa46411224e5e4076d6313ab47c7f9bb5",
    "side":"sell",
    "price":0.000123456,
    "amount":"2",
    "pair":"JOY_ETH",
    "fee":"ETH",
    "gasFee":"0",
    "txFee":"2.46912e-7"
  },
  {
    "id":316,
    "status":"done",
    "txHash":"0x582cc7a84e8aa7e28e44b11e22f24169a34776915ebbc95a88fa0e77c44faf4c",
    "side":"sell",
    "price":0.00012347,
    "amount":"1",
    "pair":"JOY_ETH",
    "fee":"ETH",
    "gasFee":"0.000105",
    "txFee":"2.4694e-7"
  }
]

• amount, gasFee and txFee are BigNumber objects.

subscribeFunds(callback)

Subscribe funds, notify if change, return last 100 records.

const subscription = joyso.subscribeFunds(funds => {
  console.log(JSON.stringify(funds));
});

Result

[
  {
    "id":192,
    "status":"done",
    "txHash":"0x4dbc49ae4735b1c230244d41377cf6aeccd70c5181df048e3be8306af8a487e6",
    "type":"withdraw",
    "amount":"0.0099",
    "token":"ETH",
    "fee":"ETH",
    "withdrawFee":"0.0001",
    "timestamp":1537434044,
    "blockId":null
  },
  {
    "id":191,
    "status":"done",
    "txHash":"0x8435bf9f69dd908373d50353ebab343b625527cd8ea44532eb01c8b0a5642879",
    "type":"withdraw",
    "amount":"0.001",
    "token":"ETH",
    "fee":"JOY",
    "withdrawFee":"0.809841",
    "timestamp":1537433888,
    "blockId":null
  }
]

• amount and withdrawFee are BigNumber objects.
• status could be pending, processing, done or failed
• type could be deposit, withdraw or transfer

buy({ pair, price, amount, feeByJoy })

Place buying order

try {
  let order = await joyso.buy({
    pair: 'JOY_ETH',
    price: '0.000123481',
    amount: 1,
    feeByJoy: true
  });
  console.log(JSON.stringify(order));
} catch (e) {
  if (e.statusCode === 400) {
    console.log(e.error.error);
  } else {
    console.log(e.message);
  }
}

Options

|Name|Required|Description| |---|---|---| |pair|O|Pair to trade, format is ${base}_${quote}, eg: JOY_ETH| |price|O|Order price, minimum is 0.000000001| |amount|O|Quote amount| |feeByJoy||Specify how to pay fee. true will pay by JOY. false will pay by quote token(ETH if pair XXX_ETH). Default is false|

Result

{
  "id":361,
  "status":"complete",
  "side":"buy",
  "price":0.000123481,
  "amount":"1",
  "fill":"1",
  "pair":"JOY_ETH"
}

• amount and fill are BigNumber objects.
• status could be active, partial or complete

sell({ pair, price, amount, feeByJoy })

Place selling order

let order = await joyso.sell({
  pair: 'JOY_ETH',
  price: '0.000123481',
  amount: 100
});

Options and result are same with buy.

trade({ pair, price, amount, feeByJoy, side })

Place order

let order = await joyso.trade({
  side: 'buy',
  pair: 'JOY_ETH',
  price: '0.000123481',
  amount: 100
});

Options and result are same with buy. One extra options

|Name|Required|Description| |---|---|---| |side|O|buy or sell|

withdraw({ token, amount, fee })

Withdraw

await joyso.withdraw({
  token: 'ETH',
  amount: 0.01,
  fee: 'eth'
});

Options

|Name|Required|Description| |---|---|---| |token|O|Token to withdraw| |amount|O|Amount to withdraw| |fee|O|Specify how to pay fee. eth, joy or token. token can only be used when token is quote token.|

getMyTrades({ from, to, quote, base, side, before, limit })

Get my trades

await joyso.getMyTrades({
  quote: 'ETH',
  base: 'JOY',
  side: 'sell',
  from: 1539129600,
  to: 1539216000,
  before: 123,
  limit: 10
});

Options

|Name|Required|Description| |---|---|---| |quote||Quote token| |base||Base token| |side||Specify side. buy, sell or blank. Blank means both.| |from||From time (included). Unix timestamp| |to||To time (excluded). Unix timestamp| |before||Only return Trade ID before this. (excluded)| |limit||Specify size of records to return. Default 100, max 1000|

Results are same with subscribeMyTrades.

disconnect()

Disconnect from JOYSO.

subscription.unsubscribe()

Unsubscribe

subscription.unsubscribe();

License

The project is released under the MIT license.

Contact

The project's website is located at https://github.com/Joyso-io/joyso-api