Getting Started - API v3

Taker API V3 is a REST API, similar to Taker API V2.

This section will walk you through the required steps to add Hashflow as a liquidity source for your platform. This could be an aggregator, an algorithmic trading bot, or any software intended to run trades against Hashflow liquidity.

1. Set up authentication

Hashflow authenticates all incoming requests based on the source field (passed in the requests below). This helps us track usage, as well as prevent DDoS attacks.

The first step in setting up your taker is reaching out to the Hashflow team, in order to have credentials generated. Depending on the type of taker, the team will provide you with different types of credentials.

A. Aggregators / API Multi-Wallet Traders

This type of API integration is viable for takers such as aggregators (e.g. 1inch, paraswap). The team will provide you with two important pieces of information:

your source name
the authentication key for your source

B. API Wallet Traders

This type of API integration is viable for individual takers that generally rely on one or very few wallets (e.g. retail traders, funds).

The team will provide you with an authentication key that is bound to the wallet you will be using to access the API.

Authenticating requests

Regardless of the integration type, you have to submit a header with each request:

Authorization: <generated credential key>

This, in conjunction with your identity parameters, will authenticate your request. For identity, parameters, the type of integration matters.

A. Aggregators / API Multi-Wallet Traders

You will have to provide the source field to every request (GET or POST).

B. API Wallet Traders

You will have to set source: 'api' to every request, and also send a field named wallet which is populated with your wallet address (e.g. 0x01ae...b3).

2. Query `/market-makers`

Next, you will need to query which market makers (liquidity sources) are currently available on Hashflow for a given network. You can do this by sending the following HTTP REST request:

GET https://api.hashflow.com/taker/v3/market-makers
  ?source=<source>
  &baseChainType=<string> # use 'evm' for EVM chains 
  &baseChainId=<string>   # Chain ID
  &marketMaker=<string>   # Optional

OR, for single wallet traders

GET https://api.hashflow.com/taker/v3/marketMakers
  ?source=api
  &baseChainType=<string>    # use 'evm' for EVM chains
  &baseChainId=<string>      # Chain ID
  &wallet=<wallet-address>

For <source> use your source identifier (e.g. my_aggregator) or api
For <baseChainType> use either evm | solana
For <baseChainId> use your network ID (e.g. 1 for Ethereum, 137 for Polygon).
For <wallet> use the 0x -prefixed wallet address (only populate when you are single wallet traders)
Make sure you also use the header that authenticates your source

The response to this request includes all available market makers on that chain and has format

{
  marketMakers: string[]
}

For example: {marketMakers: ['mm1', 'mm2']}.

You'll want to re-run this request periodically for each chain so that you can tell which market makers are available.

3. Query Price Levels (for price discovery)

In order to understand indicative order flow, we expose price levels for the different market makers. These levels tell you, at any given time:

what pairs are available for a given network (chain)
how much liquidity is available for each particular pair
what the rough prices will be once you query signed quotes for those pairs

In general, this step will allow you to do price discovery (which is inexpensive), before requesting signed quotes (which is more expensive).

The price levels APIs benefit from caching and can be queried frequently (e.g. every second).

You can get those by querying:

GET https://api.hashflow.com/taker/v3/price-levels
  ?source=<source>
  &baseChainType=<string>
  &baseChainId=<string>
  &marketMakers[]=<mm1>
  &marketMakers[]=<mm2>
  &baseToken=<token address> //optional
  &quotToken=<token address> //optional

OR, for single wallet traders

GET https://api.hashflow.com/taker/v3/price-levels
  ?source=api
  &wallet=<string>
  &baseChainType=<string>
  &baseChainId=<string>
  &marketMakers[]=<mm1>
  &marketMakers[]=<mm2>
  &baseToken=<token address> //optional
  &quotToken=<token address> //optional

This endpoint allows you query levels for an arbitrary number of market makers.

You will then get a response of the following format:

{ 
  status: "success" | "fail",
  baseChain: {
    chainType: "evm" | "solona",
    chainId: number,
  }
  levels: Record<
    string, // They key is the market maker name
    Array<{
      pair: {
        baseToken: string,  // The address of the base token
        quoteToken: string,  // The address of the quote token
        baseTokenName: string,  // The name of the base token (e.g. ETH)
        quoteTokenName: string,  // The name of the quote token (e.g. USDC)
      },
      // string representation of the level e.g. (2.5 for 2.5 ETH)
      levels: {
        // string representation of the level (e.g. for 2.5 ETH, this will be "2.5")
        q: string,
        
        // string representation of the price per unit at that level 
        // (e.g. 3500 for "up to 2.5 ETH at 3500 USDT per ETH")
        // this price is not in decimals -- it's the actual exchange rate, 
        // in floating point notation
        p: string
      }[]
    }>
  >
}

Things to note:

for each market maker, there will be one entry in the top level array for each supported pair
levels and prices are not in decimals (e.g. 1 means 1 ETH and not 1 WEI)
for native tokens (e.g. AVAX on avalanche, ETH on ethereum) Hashflow uses the 0 address (0x00..00)

Each level represents up to how much liquidity can be accessed at a given price. Also, the first level represents the minimum amount that the market maker is willing to take a quote for.

For example, suppose our levels for ETH-USDC are

{ level: "0.5", "price": "3000" }
{ level: "1.5", price: "3000"}
{ level: "5", price: "2999"}

This tells us the following:

the trader needs to sell at least 0.5 ETH
the trader can sell up to 7 ETH
the first 2 ETH will be sold at a price of 3000 USDC
the next 5 ETH will be sold at a price 2999 USDC

For example, if the trader wants to sell 3 ETH they will get 2 * 3000 + 2999 = 8999 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.

Cross-Chain price levels

In order to get cross-chain price levels, simply add quoteChainType, quoteChainId as a parameter, indicating the destination Chain ID and type for the cross-chain trade.

For example:

GET https://api.hashflow.com/taker/v3/price-levels
  ?source=<source>
  &baseChainType=<evm or solana>
  &baseChainId=<chain-id>
  &quoteChainType=<evm or solana> //optional
  &quoteChainId=<chain-id> //optional
  &marketMakers[]=<mm1>
  &marketMakers[]=<mm2>

4. Query `/rfq`

By this point, you should have an index of what market makers are available on each chain and which trading pairs they offer, as well as prices they are offering. The next step is to request a signed quote that is ready for execution.

This can target specific market makers, or be sent to all available market makers.

This request will look like:

POST https://api.hashflow.com/taker/v3/rfq

// JSON body
{
  source: string, // Your identifier (e.g. "1inch", "zerion")
  baseChain: {
    chainType: string, // evm | solana
    chainId: number
  }
  quoteChain: {
    chainType: string, // evm | solana
    chainId: number
  }
  rfqs: {
    // Contract address (e.g. "0x123a...789")
    baseToken: string,
    // Contract address (e.g. "0x123a...789")
    quoteToken: string,
    // Decimal amount (e.g. "1000000" for 1 USDT)
    baseTokenAmount: ?string 
    // Decimal amount (e.g. "1000000" for 1 USDT)
    quoteTokenAmount: ?string,
    // The address that will receive quoteToken on-chain.
    trader: string,
    // The wallet address of the actual trader (e.g. end user wallet).
    // If effectiveTrader is not present, we assume trader == effectiveTrader.
    effectiveTrader: ?string,
    // The wallet address to claim trading rewards for api user.
    // Cannot be set unless source == 'api'
    // This is useful when api users needs a separate wallet to claim rewards
    // If left empty, rewards will be sent to trader address
    rewardTrader: ?string,
    
    marketMakers: ?string[], // e.g. ["mm1"]    
    excludeMarketMakers: ?string[],
    options:{
      doNotRetryWithOtherMakers: ?boolean, //Default to false
    }
    
    // The amount to be charged in fees, in basis points.
    feesBps: ?number
  }[],
  calldata: ?boolean, // If this is true, contract calldata will be provided.
}

When provide marketMakers field, to provide better success rate, we by default will route your RFQ to other makers provide liquidity for the same maker if your specified maker failed the initial request. If you do NOT want us to re-route your RFQ to other available maker instead return failed request, please set doNotRetryWithOtherMakers to true in side options when you send RFQ request.

If you're a Wallet API trader, the trader field will be used in lieu of the wallet field, which does not need to be passed. However, you still need to pass source:api in order to avoid rate limits.

You will then get a response of the following format:

{
  status: 'success' | 'fail',
  error?: string,
  rfqId: string,  // Unique RFQ identifier
  internalRfqIds: ?string[] 
  
  quotes?: {
    quoteData: {
      baseChain: {
        chainType: string, // evm | solana
        chainId: number
      }, 
      quoteChain: {
        chainType: string, // evm | solana
        chainId: number
      },
      baseToken: string,
      baseTokenAmount: string,
      quoteToken: string,
      quoteTokenAmount: string,
      trader: string,
      effectiveTrader: ?string,
      txid: string,  // Unique quote identifier. Different from RFQ ID.
      pool: string,
      dstPool: ?string,  // For cross-chain quotes, the pool on the destination chain ID
      quoteExpiry: number,
      nonce: number,
      externalAccount: ?string,
      dstExternalAccount: ?string
    },
    signature: string,
    xChainFeeEstimate: ?string,
    targetContract: ?string,
    calldata: ?string
    value: ?string
    hftTradingRewards: ?string
  }[],
}

5. Execute quote on-chain

Once you have obtained a signed quote and decided to execute it, you can submit it on-chain to the HashflowRouter contract via the tradeRFQT call.

The call is meant to be composable. However, since it is most often composed with AMMs that have slippage, the Hashflow contracts allow you to tune the token amounts in order to account for slippage (see the description of maxBaseTokenAmount below).

HashflowRouter Contract: https://github.com/hashflownetwork/x-protocol/blob/main/evm/deployed-contracts/IHashflowRouter.json

ABIs: https://github.com/hashflownetwork/x-protocol/blob/main/evm/abi/IHashflowRouter.json

Some clarification for the ABI fields:

externalAccount. External account address. Set to eoa, if set in your signed quote. Otherwise, use 0x0000000000000000000000000000000000000000 address.
maxBaseTokenAmount / maxQuoteTokenAmount : These are what you receive in the API as baseTokenAmount / quoteTokenAmount. Sometimes you can receive a quote for higher than what you requested. It is essential that you use the requested amount in the effectiveBaseTokenAmount field.
effectiveBaseTokenAmount : The actual swapped amount. This has to be less than or equal to maxBaseTokenAmount. We suggest to keep them equal unless there's a discrepancy with the requested amount. If the effectiveBaseTokenAmount is less than maxBaseTokenAmount, the exchange rate maxQuoteTokenAmount / maxBaseTokenAmount will be preserved and applied to effectiveBaseTokenAmount
value: If the baseToken is the native token (e.g. ETH on Ethereum), the effectiveBaseTokenAmount needs to be passed as value to the contract call

You can use Etherscan (or similar tools for non-Ethereum chains) to confirm the trade went through.

Executing cross-chain quotes

Cross-chain quotes are executed via our interoperability partner, Wormhole. Wormhole operates with 2 parties:

a set of Guardians to attest the transaction
a Relayer on the destination chain

Both of these entities could charge a small fee. However, once the transaction is submitted on the source chain, they will take care of execution on the destination chain.

Therefore, a fee has to be paid by the trader on the source chain, in the source chain's native token (e.g. ETH for Ethereum). This fee will pay for:

Guardian fees
Relayer fees
Gas fees on the destination chain

The fee that needs to be paid for each quote is returned in the rfqs response's xChainFeeEstimate field.

The amount provided is in WEI (decimals -- usually 10^-18).

Once we have a quote, as well as a fee estimate, we can go ahead and submit the quote for execution via the tradeXChainRFQT contract call.

6. Query `/restrictions`

Market makers can set rate_limit on given a trader and a network. All rate_limit restrictions will have an expiry window, which means traders can re-gain access to the market maker after the specified expiry time. To understand the restriction status, takers can query /restrictions endpoint to better understand error messages from market maker and adjust routing accordingly. When a trader has been restricted, we will automatically route their RFQs to other makers (if present) until restriction expires.

We suggest you use the response you get from this endpoint to display proper error message as well as route your RFQs requests to other available makers accordingly.

For example:

GET https://api.hashflow.com/taker/v3/restrictions?source=<your-source>&trader=<0x...>&chainId=<chainId>&chainType=<chainType>

The response will be in the following shape

{ 
  isTraderRestricted: boolean; 
  restrictions?: Array<{ 
    reason: 'rate_limit'; 
    expiryTimestampMs?: number; //UTC milliseconds timestamps
    marketMaker?: string; 
    chainId?: string
    chainType: string
  }> 
}

PreviousHow To Guides

Last updated 5 days ago

1. Set up authentication

A. Aggregators / API Multi-Wallet Traders

B. API Wallet Traders

Authenticating requests

A. Aggregators / API Multi-Wallet Traders

B. API Wallet Traders

2. Query /market-makers

3. Query Price Levels (for price discovery)

Cross-Chain price levels

4. Query /rfq

5. Execute quote on-chain

Executing cross-chain quotes

6. Query /restrictions

2. Query `/market-makers`

4. Query `/rfq`

6. Query `/restrictions`