Eosfinex adapter for Node and the browser.

const Sunbeam = require('sunbeam')

// Browser usage: import into browsers in case you can't transpile ES6
const Sunbeam = require('sunbeam/dist')

Example of the Websocket client usage: example-ws.js

Run with:

node example-ws.js

You can see all API calls in example-ws.js.

• opts <Object>
  • url <String> Address of the websocket eosfinex node
  • eos <Object> options passed to Eos client for signing transactions
    • expireInSeconds <Number> Expiration time for signed tx
    • Eos <Class> The official eosjs client Class from require('eosjs')
    • httpEndpoint <String|null> an Eos node HTTP endpoint, used to get the contract abi, if abi not passed via options. omit when you pass the abi via options
    • abis <Object> (optional) eosfinex contract abis, so no initial http request is required to get the contract abi and httpEndpoint can be omitted
      • exchange <Object> Exchange abi
      • token <Object> Token contract abi
    • keyProvider <String> your key, used to sign transactions
    • account <String> accountname to use for the key
    • permission <String> permission level to use for the account
  • transform <Object> Options passed to state components
    • orderbook <Object>
      • keyed <Boolean> Manage state as keyed Objects instead of an Array
    • wallet <Object>
    • orders <Object>
      • keyed <Boolean> Manage state as keyed Objects instead of an Array

const Eos = require('eosjs')
const opts = {
  url: 'wss://eosnode.example.com',
  eos: {
    expireInSeconds: 60 * 60, // 1 hour,
    Eos: Eos,
    httpEndpoint: 'https://eosnode.example.com:8888',
    abis: null, // fetched via http from eos node if null
    keyProvider: [''], // your key, used to sign transactions
    account: '', //
    permission: '@active'
  },
  transform: {
    orderbook: { keyed: true },
    wallet: {},
    orders: { keyed: true }
  }
}

const ws = new Sunbeam(opts)
ws.open()

For an example how to prefetch the contract abis to avoid the initial HTTP request to an eos node, see example-prefetched-abi-ws.js.

Emitted when the socket connection is established.

Example:

const ws = new Sunbeam(opts)

ws.on('open', () => {
  // ready to trade!
})

ws.open()

Emitted for every message that the websocket server server sends. Useful debugging and custom extensions.

Example:

ws.on('message', (m) => {
  console.log(m)
})

Emitted in case of an error.

Example:

ws.on('error', (m) => {
  console.error(m)
})

You can see all API calls in example-ws.js.

Opens a Websocket.

Example:

ws.open()

Closes the connection to eosfinex.

Example:

ws.close()

Takes the account name you have defined when creating a Sunbeam instance with opts.eos.account and sends it to the server. Your private key stays local.

Subscribes you to wallet, trade and order updates for the specified account.

• order <Object>
  • symbol <String> Token pair to trade for
  • amount <String> Amount to buy/sell
  • type <String> Order type, EXCHANGE_MARKET, EXCHANGE_IOC or EXCHANGE_LIMIT
  • price <String> Price for orders except market orders
  • clientId <Number> Every order must have a unique id assigned from the client, defaults to unix timestamp
  • postOnly <Boolean> Submit postonly order, sugar for flags 1
  • flags <Number>

Creates an order compatible with the contract abi, pre-signs it and sends it to the Websocket endpoint.

List of available flags

Some flags are abstracted by Sunbeam. Here is a full list of available flags:

type                         flag         abstraction available

post only                       1         postOnly: true
ioc                             2         EXCHANGE_IOC
market                          4         EXCHANGE_MARKET   
release on trade               64
sweep collateral              128

A post only order would have the flag 1, a post only + ioc order would have the flag 3

Example:

// available types: EXCHANGE_MARKET EXCHANGE_IOC EXCHANGE_LIMIT
const order = {
  symbol: 'BTC.USD',
  amount: '1',
  type: 'EXCHANGE_MARKET',
  clientId: '12345' // unique locally assigned id
}
ws.place(order)

// available types: EXCHANGE_MARKET EXCHANGE_IOC EXCHANGE_LIMIT
const order = {
  symbol: 'BTC.USD',
  amount: '1',
  price: '1',
  type: 'EXCHANGE_LIMIT',
  clientId: '12346'
}
ws.place(order)

The request will be signed locally using the eosjs module.

• data
  • symbol <String> The pair, i.e. BTC.USD
  • side <String> bid or ask
  • id <String> The id returned from the contract on placement
  • clientId <String> The unique id assigned by the client

Cancels an order.

Example:

ws.cancel({
  symbol: 'BTC.USD',
  side: 'bid',
  id: '18446744073709551612',
  clientId: '1536867193329'
})

The request will be signed locally using the eosjs module.

• data
  • currency <String> The currency to withdraw, e.g. BTC
  • amount <String> The amount to withdraw
  • to <String> (optional) The account to withdraw to.

Withdraws tokens to a specified account. The account must be the same as the account used with EOSfinex.

Defaults to account passed in constructor, opts.eos.account.

Example:

ws.withdraw({
  currency: 'EUR',
  amount: '0.678'
})

The request will be signed locally using the eosjs module.

• data
  • currency <String> The currency to withdraw, e.g. BTC
  • to <String> (optional) The account to withdraw to.

Sweeps tokens to a specified account. The account must be the same as the account used with EOSfinex.

Defaults to account passed in constructor, opts.eos.account.

Example:

ws.sweep({
  currency: 'EUR'
})

// on success we receive a wallet update:
// [ '0', 'wu', [ 'exchange', 'EUR', 0, 0, null ] ]

// and the amount is transferred back to the deposit contract:
$ ./cleos get currency balance efinextether testuser1431
100.00000000 EUR

• data
  • currency <String> The currency to deposit, e.g. BTC
  • amount <String> The amount to deposit

Takes your user account, defined in opts.eos.account, and deposits the desired amount to the exchange using the tether token contract.

Example:

ws.deposit({
  currency: 'EUR',
  amount: '2'
})

// success:
// [ '0', 'wu', [ 'exchange', 'EUR', 2, 0, null ] ]

The request will be signed locally using the eosjs module.

• pair <String> The pair, i.e. BTC.USD

Subscribe to orderbook updates for a pair.

Example:

ws.onOrderBook({ symbol: 'BTC.USD' }, (ob) => {
  console.log('ws.onOrderBook({ symbol: "BTC.USD" }')
  console.log(ob)
})

ws.onManagedOrderbookUpdate({ symbol: 'BTC.USD' }, (ob) => {
  console.log('ws.onManagedOrderbookUpdate({ symbol: "BTC.USD" }')
  console.log(ob)
})

ws.subscribeOrderBook('BTC.USD')

• pair <String> The pair, i.e. BTC.USD

Unsubscribe from orderbook updates for a pair.

Example:

ws.subscribeTrades('BTC.USD')

• pair <String> The pair, i.e. BTC.USD

Unsubscribe from orderbook updates for a pair.

Example:

ws.unSubscribeOrderBook('BTC.USD')

• channel <String> The channel to subscribe to
• opts <Object> Additional data to send

Subscribes to a websocket channel.

Example:

this.subscribe('wallets', { account: 'testuser1431' })

• channel <String> The channel to subscribe to
• opts <Object> Additional data to send

Unsubscribes from a channel.

Example:

this.unsubscribe('wallets', { account: 'testuser1431' })

Usually the Bitfinex trading protocol will send a snapshot, and later just updates, for performance reasons.

When you register a managed orderbook handler, the managed state component will take care of parsing the snapshots update the state when partial updates arrive.

For every update, the full updated data is emitted.

• opts <Object>
  • symbol <String> The symbol to emit the orderbook update for, i.e. BTC.USD
• handler <Function> Called every time the state is updated

If you want to manage state on your own, our just need a stream of updates, use the onOrderBook handler.

Example:

ws.onManagedOrderbookUpdate({ symbol: 'BTC.USD' }, (ob) => {
  console.log(ob)
})
ws.subscribeOrderBook('BTC.USD')

Registered for messages from the corresponding book channel (received on subscribe).

• opts <Object>
• handler <Function> Called every time the state is updated

Example:

ws.onManagedWalletUpdate({}, (mw) => {
  console.log(mw)
})
ws.auth()

Registered for ws, wu messages via channel 0.

• opts <Object>
• handler <Function> Called every time the state is updated

Example:

ws.onManagedOrdersUpdate({}, (orders) => {
  console.log(orders)
})
ws.auth()

Registered for os, on, ou, oc messages via channel 0.

If you want to manage state on your own, or have a special use case, you can use unmanaged handlers.

• opts <Object>
• handler <Function> Called every time the state is updated

Example:

ws.onWallet({}, (wu) => {
  console.log(wu)
})
ws.auth()

Registered for ws, wu messages via channel 0.

• opts <Object>
• handler <Function> The callback called for every update

Example:

ws.onOrderUpdate({}, (data) => {
  console.log(data)
})
ws.auth()

Registered for os, on, ou, oc messages via channel 0.

• opts <Object>
• handler <Function> The callback called for every update

Example:

ws.onTradeUpdate({}, (update) => {
  console.log(update)
})
ws.auth()

Registered for tu, te messages via channel 0.

• opts <Object>
  • symbol <String> The symbol to emit the public trade updates for, i.e. BTC.USD
• handler <Function> The callback called for every update

Example:

ws.onTrades({ symbol: 'ETH.USD' }, (data) => {
  console.log('ws.onTrades({ symbol: "ETH.USD" }')
  console.log(data) // emits [ 'ETH.USD', 'te', [ '3', 1537196302500, -0.9, 1 ] ]
})

ws.subscribeTrades('ETH.USD')

Registered for tu, te messages via the corresponding channel for the symbol.

• opts <Object>
  • symbol <String> The symbol to emit the orderbook update for, i.e. BTC.USD
• handler <Function> The callback called for every update

Just emits order updates and order snapshots without keeping or managing state.

Example:

ws.onOrderBook({ symbol: 'BTC.USD' }, (ob) => {
  console.log(ob)
})
ws.subscribeOrderBook('BTC.USD')

Registered for messages from the corresponding book channel (received on subscribe).

Sunbeam can take care of managing state snapshots for you, and keeps them up to date when the API sends updates. The state helpers can also be used as standalone components. They are also integrated into the main Websocket client, and are accessed by the onManaged[]StateUpdate handlers you can register.

Run with:

node example-wallet.js
node example-orderbook.js
node example-orders.js

Sometimes you may want to interact with Sunbeam's managed state. They are exposed through a method:

sb.getManagedStateComponent('wallet')
sb.getManagedStateComponent('orders')
sb.getManagedStateComponent('books', 'BTC.USD')

Start nodeos:

nodeos --access-control-allow-origin "*" --verbose-http-error --http-validate-host=false --enable-stale-production --producer-name eosio --plugin eosio::chain_api_plugin --plugin eosio::net_api_plugin

--contracts-console will output the logging from custom contracts

Enable CORS for your EOS node, by enabling it via config:

cd ~/eosdata/

echo "access-control-allow-origin = *" >> config.ini