# @hashflow/taker-js

> Javascript library to facilitate interactions with Hashflow backend and smart contracts for takers

Latest version **0.4.1** (published 2025-03-13) · ISC license · 0 weekly downloads

## Install

```sh
npm install @hashflow/taker-js
pnpm add @hashflow/taker-js
yarn add @hashflow/taker-js
bun add @hashflow/taker-js
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.1 |
| Published | 2025-03-13 |
| First published | 2022-09-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.18.1 |
| Dependencies | 4 |
| Unpacked size | 38.1 KB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| Author | Michael Blind |
| Maintainers | gxmxni, michael-hashflow |

## Links

- npm: https://www.npmjs.com/package/@hashflow/taker-js
- npm.io page: https://npm.io/package/@hashflow/taker-js

## Dependencies (4)

- [axios](https://npm.io/package/axios.md) ^0.27.2
- [ethers](https://npm.io/package/ethers.md) ^6.7.0
- [@hashflow/sdk](https://npm.io/package/@hashflow/sdk.md) ^2.3.4
- [@solana/web3.js](https://npm.io/package/@solana/web3.js.md) ^1.87.5

## Recent versions

- 0.4.1 (latest) — 2025-03-13
- 0.4.0 — 2025-03-13
- 0.3.7 — 2023-12-19
- 0.3.6 — 2023-11-28
- 0.3.5 — 2023-11-13
- 0.3.4 — 2023-10-16
- 0.3.3 — 2023-10-10
- 0.3.2 — 2023-10-05
- 0.3.1 — 2023-09-28
- 0.3.0 — 2023-09-28
- 0.0.6 — 2023-02-23
- 0.0.5 — 2023-02-23
- 0.0.4 — 2023-02-17
- 0.0.3 — 2023-02-17
- 0.0.2 — 2023-01-26
- … 1 more at https://npm.io/package/@hashflow/taker-js/versions

## README

# taker-js

Typescript library which exposes the hashflow taker APIs

## Initializing the API

All necessary functions are exposed through the `HashflowApi` object. This API object requires the following arguments to its constructor:

1. **_mode_**: The type of taker you are. Set this to `'taker'` if you are a known taker application (identified by application name) OR set it to `'wallet'` if you are an individual trader (identified by wallet address).
2. **_name_**: Your identifier. Based on your mode (see above), this will either be a taker name (e.g. `'1inch'`) or an EVM address.
3. **_authKey_**: Your authentication key. These are unique keys generated by the Hashflow team during the vetting phase. If you haven't gone through this process, you can contact us on [Discord](https://discord.gg/gw56asV5k3).
4. **_environment_** (optional): Allows specifying `'staging'` for connecting to the non-production API. By default, this is set to `'production'`.

Start by importing and initializing the `HashflowApi` object.

```ts
import { HashflowApi } from '@hashflow/taker-js';

const hashflow = new HashflowApi(
  'wallet',
  '0x123...ff', // address
  '!XYZ...ABC' // auth key
);
```

## Using the API

This API object exposes a few functions for interacting with the Hashflow backend and contracts.

### Backend: `getMarketMakers`, `getPriceLevels` _(Optional)_

These two functions are optional helpers to inform the `requestQuote` calls (described below). For known taker applications, we recommend using both functions. For individual traders, they may be helpful but are not required.

##### Getting market makers: `getMarketMakers`

This function returns all available market makers on a given chain. This allows taker applications to separately track pricing per market maker and request quotes for specific makers only.

The interface for this function is

```
async getMarketMakers(chainId: number) => string[]
```

##### Getting price levels: `getPriceLevels`

This function gives access to indicative pricing from each market maker. This can be used for pre-determining which quotes to request and when to do so. It is especially helpful for taker applications looking to compare prices across various venues before requesting hard quotes.

The interface for this function is

```
async getPriceLevels(chainId: number, marketMakers: string[]) => Record<string, PairPriceLevels[]>
```

The result of this function is a dictionary where the keys are market makers, and the values are `PairPriceLevels` arrays for the respective market makers. These entries have the following structure:

```ts
interface PairPriceLevels {
  includesFees?: boolean;
  pair: {
    baseTokenName: string; // short name (e.g. ETH)
    quoteTokenName: string; // short name (e.g. ETH)
    baseToken: string; // EVM address
    quoteToken: string; // EVM address
  };
  levels: PriceLevel[];
}

// Individual price level ( e.g. "2.5 ETH for 2000 USDC/ETH")
interface PriceLevel {
  level: string; // Level-string (e.g. "2.5" for 2.5 ETH)
  price: string; // Price-string (e.g. "2000" for 2000 USDC per ETH)
}
```

It's important to note these **levels are cumulative**, with each level representing the total amount supported and the incremental price compared to the previous level. Also, the first level represents the minimum supported amount.

For example, suppose our levels for ETH-USDC are:

```js
[
  { level: '0.5', price: '3000' },
  { level: '1.5', price: '3000' },
  { level: '5', price: '2999' },
];
```

This tells us the following:

1. The trader needs to sell at least _0.5 ETH_
2. The trader can sell up to _5 ETH_
3. The first _1.5 ETH_ will be sold for _3000 USDC_
4. The next _3.5 ETH_ will be sold for _2999 USDC_

Note that, in general, as liquidity goes up, rates go down. This is expected, as market maker prices generally mirror Centralized Exchange order books.

Some other things to note about these price levels:

1. **One entry per pair**. There will be exactly one `PairPriceLevels` object for each supported pair direction.
2. **Values are not in decimals**. The `levels` and `prices` are not in decimals (e.g. 1 means 1 ETH and not 1 WEI).
3. **0x0...0 for native tokens**. For native tokens (ETH on mainnet, AVAX on avalanche), we use `'0x0...0'` as an address.

### Backend: `requestQuote`

This is the main function for getting signed quotes from the Hashflow backend. For taker applications, we recommend using the two functions above to determine when to request quotes and for what price.

The interface of this function is

```
async requestQuote(input: RfqInput) => SignedQuote
```

with

```ts
interface RfqInput {
  chainId: number;
  dstChainId?: number; // Optional - used for x-chain quotes
  baseToken: string; // EVM address
  quoteToken: string; // EVM address
  baseTokenAmount?: string; // decimal-string for baseToken amount (e.g. '1000000' for 1 USDT)
  quoteTokenAmount?: string; // exactly one of baseTokenAmount/quoteTokenAmount must be set
  wallet?: string; // YOUR wallet – only specify if using 'taker' mode
  effectiveTrader?: string; // TRADER wallet – only specify if using 'taker' mode
  marketMakers?: string[]; // Optional - restrict to specific market makers
}

interface SignedQuote {
  status: 'success' | 'fail';
  rfqId: string; // Unique ID of your request for quote;
  quoteData?: QuoteData; // Quote object – present if status = 'success'
  signature?: string; // Quote signature
  gasEstimate?: number; // Estimated number of gas units
  nativeTokenPriceUsd?: number; // Current USD price of 'gas' token
}

interface QuoteData {
  rfqType: 0 | 1;
  txid: string; // Unique ID of quote (different from RFQ-ID)
  eoa?: string;
  baseToken: string;
  quoteToken: string;
  baseTokenAmount: string;
  quoteTokenAmount: string;
  quoteExpiry: number; // Timestamp when this quote will expire
  fees: string;
  trader: string;
  effectiveTrader?: string;
  pool: string; // Hashflow pool you're trading with
  dstPool?: string;
  nonce?: number;
}
```

### Contracts: `executeTrade`

After calling `requestQuote(...)` and looking at the quote price (`baseTokenAmount` / `quoteTokenAmount`), you can decide to make the swap using `executeTrade`. This function interacts with the blockchain and calls Hashflow's smart contracts.

The interface of this function is

```js
async executeTrade(
  signer: Signer,
  chainId: number,
  quoteData: QuoteData,
  signature: string,
  options?: Options  // Optional – EVM options to use with the contract call
) => string
```

The return value of this function call is the *transactionHash* of your submitted trade. All of the input fields (except for `signer`, as detailed below) can be taken from the result of calling `requestQuote`.

NOTE: To call this function, you'll need to pass an [ethers.Signer](https://docs.ethers.io/v5/api/signer/) object to `executeTrade`. This signer is then used to call the smart contract with your address and key. You should be able to find many tutorials online for creating your Signer object.

---
_Source: https://npm.io/package/@hashflow/taker-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._