Javascript Client for the Hydro API

A client written in Typescript for interacting with the Hydro API

New in version 2.x

• Updated functions to match new Hydro API specs
• Added support for market orders
• Added convenience functions for wrapping eth and approving tokens

What is the Hydro Protocol?

Hydro Protocol is an open-source framework for building decentralized exchanges on Ethereum. Hydro is designed for developers looking to build decentralized exchanges without having to deal with the complexity and expense of designing, deploying, and securing their own smart contracts.

For more information, please visit https://www.hydroprotocol.io/

What is this Client for?

The Client is built to provide easy access to the Hydro API. The API is intended to give you full access to the state of the market, and to help you easily create new orders based on that information. Using this API, you can write helpers to visualize the market data however you like, clients to help you create orders more easily, or full on bots that will analyze the incoming data and place orders automatically.

By default, this Client connects to the DDEX exchange, but is compatible with any exchange running the Hydro API.

For full API specs, please see the documentation: https://docs.ddex.io/

Getting Started

To get started, simply install the package through npm:

npm i @hydro-protocol/hydro-client-js

Once you've done that there are two main interfaces into the API.

HydroClient

HydroClient is used to query the API for data. Initialize it with your private key to start making API calls.

import { HydroClient } from "@hydro-protocol/hydro-client-js";

let client = HydroClient.withPrivateKey("0x..."); // Your private key here

// Get a list of all markets and their details
let markets = await client.listMarkets();

// Create, sign, and submit a market order for HOT
let order = await client.createOrder("HOT-WETH", "buy", "market", "0.01", "100");

Instantiating a client

Each instantiation method takes an options object with the following parameters:

HydroClientOptions

| Parameter | Type | Notes | | --------- | ---- | ----- | | apiUrl | string | The url to the Hydro API you wish to query. This defaults to the DDEX exchange running on mainnet: https://api.ddex.io/v3/ | | web3Url | string | The url to use to query the blockchain. This is required if you wish to use the blockchain helper methods. Recommended to register an account on Infura and use the mainnet url provided to your account. |

Using the HydroClient to query the API

HydroClient was built to largely mirror the actual Hydro API, so if you see a method in the API docs you should be able to find a way to call it from HydroClient. Here is a brief rundown of available API calls.

Public

These methods do not need a valid signature in order to return data, and can be called without an authenticated HydroClient instance. Public Rest API.

Private

These methods return data tied to a specific account, and therefore require an authenticated HydroClient instance. Private Rest API.

Blockchain

These methods do not query the Hydro API directly, but instead perform actions directly against the blockchain. As these actions will be tied to your account, you must use an authenticated HydroClient instance.

HydroWatcher

Our other API interface is HydroWatcher, which is used to get live updates about the state of the market. It will connect to our websocket endpoint and notify you about any changes to the exchange that you are subscribed to. All of this data is public, so no authentication is required. Websocket API.

import { HydroWatcher } from "@hydro-protocol/hydro-client-js"

let watcher = new HydroWatcher({
  // Listen for changes to the HOT-WETH ticker and post them to the console.
  tickerUpdate: (ticker) => console.log(ticker),
})
watcher.subscribe("ticker", ["HOT-WETH"])

Instantiating a watcher

Listeners for events must be provided in the HydroWatcher constructor via the listener parameter. This is a HydroListener object, which lets you provide callback functions for various events. The object has the following parameters:

HydroListener

The HydroWatcher constructor takes an options object with the following parameters:

HydroClientOptions

| Parameter | Type | Notes | | --------- | ---- | ----- | | websocketUrl | string | The websocket url to the Hydro API you wish to query. This defaults to the DDEX exchange running on mainnet: wss://ws.ddex.io/v3 |

Subscribing

Once you have a HydroWatcher instance defined with callbacks for the events you wish to handle, you must Subscribe to a channel in order to receive any data. You subscribe by specifying a channel, which defines the type of data you want to receive, and a list of market ids, which filters the events to only include data from those markets. Subscription is handled by the following call:

Unsubscribing

If you no longer wish to receive data from a channel, you must Unsubscribe. Unsubscription is handled by the following call:

Channel types

There are a few different channels you can subscribe to, as defined in the API.

| Channel | API Docs Link | | ------ | ----- | | ticker | Ticker - Price updates on a market. | | orderbook | Orderbook - Aggregated orderbook data for a market. | | full | Full - Details on all orders and trades for a market. |