@leemcdonald-au/bitmexapi v2.1.4

BitmexAPI

An event-based node.js library for the REST and Socket BitMEX APIs.

class BitmexAPI

The socket API handler.

const { BitmexAPI } = require('@leemcdonald-au/bitmexapi')

// Note: The BitmexAPI object will cache requests prior to connection and send them all individually at the same time when a connection is established.

// Will connect to Bitmex MD socket upon creation.
// The BitmexAPI object is an extended Websocket and does not emit any custom events.
// If you know your way around Websockets, you'll be fine.
const bitmex = new BitmexAPI
// const testmex = new BitmexAPI(true)  // Passing true will connect to the testnet rather than the mainnet.

// You have connected to BitMEX.
bitmex.on('open', () => {})

// You have disconnected from BitMEX.
bitmex.on('close', () => {})

// This API comes with a single function, which returns a BitmexStream object.
const account = bitmex.register('API_KEY', 'API_SECRET')

// The BitmexAccount object also has all the REST API functions included. These are 
// account.get('directory')
// account.post('directory', { orderQty: 100, price: 1000 })
// account.put('directory', { object: data })
// account.delete('directory', { object: data })
// Define the objects as suggested by the BitMEX REST API and use the appropriate function and you're golden. 
// See BitmexAccount example below for more details.

// When registerd with bitmex.register(), the returned BitmexAccount object comes with a subscribe() function.
const stream = account.subscribe('trade:XBTUSD')

// The BitmexStream object isn't exported and shouldn't be created independently of the BitmexAPI object.
// This object controls the flow of data to and from Bitmex for this channel.
// An account can subscribe to multiple streams.
const secondStream = account.subscribe('position')

// You don't need an API Key and Secret pair to receive public data.
const public = bitmex.register()
const thirdStream = public.subscribe('trade')

// You can keep track of the state of a stream with these events:
stream.on('connected',      () => console.log("I've connected!"))
stream.on('authenticated',  () => console.log("I've authenticated!"))
stream.on('subscribed',     () => console.log("I've subscribed!"))
stream.on('partial',        data => console.log("I've received the partial!"))
stream.on('message',        data => console.log("I've received data from the stream!"))
stream.on('error',          err => console.error(err))
stream.on('unsubscribed',   () => console.log("I've been unsubscribed!"))
stream.on('disconnected',   () => console.log("I've been disconnected!"))

// The stream also has variables to confirm these events have passed.
stream.connected
stream.partial
stream.subscribed
stream.authenticated

// Each BitmexStream object comes with the following functions:
// void stream.connect(), void stream.disconnect(), void stream.subscribe() and void stream.unsubscribe()
// stream.connect() and stream.subscribe() are called automatically upon object creation so you don't need to do this manually.
// BitmexAPI caches commands when not connected, so these will be cached if created prior to connection being established.

// Got all the data I wanted.
stream.disconnect() // Will call stream.unsubscribe() if that hasn't been called.

// The final function is for sending data back to Bitmex via the stream.
// stream.out(data = {}, type = 0).

// It is recommended you don't use this function unless you know what you're doing. But if new features are released which the API doesn't support, this can be used to access them until
// support is built in. type represents the packet type to send (0 - message, 1 - subscribe, 2 - unsubscribe)

// For a quick example of this, this is the authentication object sent directly via this function to authenticate a stream:
const command = { op: "authKeyExpires", args: [this.account.key, expires, createHmac('sha256', this.account.secret).update('GET/realtime' + expires).digest('hex')] }
this.out(command)

BitmexAccount

The REST API handler.

const { BitmexAccount } = require('@leemcdonald-au/bitmexapi')

// As with the BitmexAPI class, public data doesn't requre an API key/secret pair to fetch.
const account = new BitmexAccount('API_KEY', 'API_SECRET')
const public = new BitmexAccount

// Because we've created the BitmexAccount object directly ourselves, it no longer has a socket API component, thus we cannot use account.subscribe()
// This function is deleted prior to returning in the case of a direct creation.

// The REST API provides four basic functions. get() post() put() delete().

// Fetch the users account data when provided valid API Key / Secret
account.get('user').then(data => console.log(data)).catch(e => console.error(e))

// Create a LIMIT order for 100 contracts of XBTUSD at 7,500.
account.post('orders', { orderQty: 100, symbol: "XBTUSD", price: "7500" }).then(data => console.log(data)).catch(e => console.error(e))

// Etc
//account.put('direction', { object: data })
//account.delete('directory', { object: data })

// To use the REST API, just follow the instructions on the REST API docs page and pass the recommended objects to the API.

The BitMEX Socket API does not allow sending data to it (with exception to heart-beats/deadmans switch, which aren't supported back-end as of yet), but you could rig it up with stream.out()

Changelog

Update 2.1.4 - Added testnet switch to BitmexAPI. new BitmexAPI(true) will connect to testnet instead of mainnet. - Improved the documentation somewhat. - Added changelog to readme. Hi! <3