Ethfinex Trustless – Developer Guide

A developers guide to interacting with Ethfinex Trustless

In addition to the UI available at trustless.ethfinex.com, the Ethfinex Trustless developer tools make it possible for anyone to build applications and trade from an Ethereum wallet.

This guide, and the Trustless client library and documentation, makes integration into any Ethereum Wallet, DApp or external site simple.

Ethfinex Trustless removes the need for signups, KYC, deposits and withdrawals to eliminate the counter-party risk associated with interacting with centralised order books.

The developer guide below will provide the tools that allow you or your customers to interact with the Ethfinex (and Bitfinex) order books whilst maintaining complete custody of your portfolios. This is the first of several guides, so please contact us at [email protected] to request additional clarification or suggest future articles. Additionally, you can visit our Trustless Feedback Thread on /r/Ethfinex to share your thoughts.

Possible Applications

A number of ideas for interacting with Ethfinex Trustless:

• Creating alternative or super-simple UI interface to the APIs to allow direct token to token exchange between any ERC20 tokens.
• Run an automated trading strategy taking liquidity from Ethfinex Trustless and arbitraging with decentralised exchanges such as ForkDelta or 0x Relayers.
• Create a mobile DApp interface for the Trustless APIs, optimised to trade from an Ethereum mobile wallet.

API Trading and Wallet Integrations

• Ethfinex Trustless Documentation – Full details of the smart contracts, api endpoints, and setup.
• Ethfinex Trustless Javascript Client Library – A library abstracting the interaction with the Ethereum blockchain, signing protocols, and API calls to make connection simple, and facilitate quick integration.

Getting Started in JavaScript

Subscribing to Order Books

This uses a standard websocket connection, and mirrors exactly the Bitfinex websocket stream. A client library makes connection easy in javascript:
npm i bitfinex-api-node.

All public / non-authenticated endpoints can be retrieved using traditional REST or Websockets and these endpoints are exactly the same as those used by Bitfinex and specified in the documentation here. The only difference required is to replace api.bitfinex.com with api.ethfinex.com.

Websocket is recommended but REST endpoints are also available for order books, trade history, tickers, and candles. Documentation for these is available on Bitfinex.

Once connected, the new Ethfinex Trustless API is used to place and manage your orders.

Set-up and Authentication

Authentication to make all the following requests is done by signing using an Ethereum private key. Signing is handled by the Ethfinex Trustless client library if the account is available and unlocked. However if signing using a hardware wallet, or using a raw private key, the message and signature needs to be prepared separately.

The ethereumjs-util package is used in various places in this tutorial for ensuring consistency in signing and preparation signatures in various formats. It can be installed using npm.

The base url for all requests is http://api.ethfinex.com/trustless/v1/

Pre-requisites:

• A source of Ethereum web3 (i.e. running a local node, or using a provider such as infura)
• An Ethereum wallet, which is unlocked and has access to your web3 provider. This can be a raw private key, encrypted keystore file, hardware wallet such as ledger or trezor, or an in-browser wallet such as Metamask.

Initialising EFX to trade from node.js:

To obtain a list of tradable pairs, token contract addresses, decimals, minimum order sizes and other configuration information is retrieved using efx.getConfig().

Placing an Order

Before placing an order, you are required to lock tokens into the Ethfinex Wrapper contracts. This allows for guaranteed execution and ensures Trustless orders can be added directly onto the centralised order book, and matched against trades from centralised users.

Approving and locking tokens:

The first time locking an ERC20 Ethereum-based token from a specific account, you are required to approve it to interact with the time-lock smart contracts.

This step does not need to be repeated again, and subsequently you are required only to call the lock function. This transfers tokens into the wrapper token contract, ready to trade.

The time limit specified when locking is a maximum – tokens can always be unlocked after this time limit (in hours) expires. In order to unlock tokens before this expires, you must request a signed permission from Ethfinex. This is always returned if you have no orders open involving those tokens.

Details about unlocking are further down this guide.

Submitting an order:

Orders are generated and submitted, returning either an orderId or error. A full list of possible errors and their associated explanation is available here.

When submitting an order there are 3 parameters:

1. symbol is the pair which you wish to trade
2. amount is specified in the first currency in the symbol (i.e. ZRXETH). For a sell, amount is negative. Amount accepts either maximum 8 d.p, or as many decimals as are available on the relevant token’s smart contract if it is fewer than 8.
3. price is specified in the second currency in the symbol (i.e. ZRXETH). Prices should be specified to 5 s.f. maximum.

The client library also provides methods for submitBuyOrder and submitSellOrder.

Requesting Open Orders and Historical Orders

If you already have an unlocked wallet available to web3 to use for signing, you can simply get open orders and order history from the API as follows:

If an unlocked account is not available to sign with, for example when using a raw private key or hardware wallet, authentication nonce and signature must be pre-signed and passed into the calls. nonce is required to be a timestamp less than 3 hours in the future. signature is that nonce signed using the relevant private key for the address who’s orders you wish to view.

Cancelling Orders

Cancelling orders requires the orderId you wish to cancel to be signed by the address which created and placed the order.

Unlocking Tokens

If tokens are not used in active orders they can always be unlocked. If unlocking after the time specified when locking has expired, no permission is required. When unlocking before this, Ethfinex must sign a release permission, after verifying that you have no orders currently active which require that token.

When a particular token’s lock time has not yet expired, permission is required from Ethfinex to unlock early. This permission can be requested directly from Ethfinex using an API call.

The request must be authenticated using a nonce and signature, and the response contains a signed permission from Ethfinex. This permission will always be granted if Ethfinex is online and your address has no open orders involving those tokens.

Troubleshooting

A list of error codes returned by the API and reasons are available here. Some more detailed explanations can also be found in the API documentation.

If you have suggestions to improve this guide or any of the available documentation, please raise an issue on Github, or email [email protected].

Get started on trustless.ethfinex.com.