Getting Started

This doc will walk you through the required steps to add Hashflow as a liquidity source for your Taker endpoint. 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 /marketMakers
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/v1/marketMakers
  ?source=<source>
  &networkId=<chain-id> 
OR, for single wallet traders
GET https://api.hashflow.com/taker/v1/marketMakers
  ?source=api
  &wallet=<wallet-address>
  &networkId=<chain-id> 
For <source> use your source identifier (e.g. my_aggregator) or api
For <chain-id> use your network ID (e.g. 1 for Ethereum, 137 for Polygon).
For <wallet-address> use the 0x -prefixed wallet address
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/v2/price-levels
  ?source=<source>
  &networkId=<chain-id>
  &marketMakers[]=<mm1>
  &marketMakers[]=<mm2>
OR, for single wallet traders
GET https://api.hashflow.com/taker/v2/price-levels
  ?source=api
  &wallet=<wallet-address>
  &networkId=<chain-id>
  &marketMakers[]=<mm1>
  &marketMakers[]=<mm2>
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",
  networkId: 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)
      },a
      // string representation of the level e.g. (2.5 for 2.5 ETH)
      levels: Array<{
        // string representation of the level (e.g. for 2.5 ETH, this will be "2.5")
        level: 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
        price: 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 5 ETH
the first 1.5 ETH will be sold for 3000 USDC
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.
Cross-Chain price levels
In order to get cross-chain price levels, simply add dstNetworkId as a parameter, indicating the destination Chain ID for the cross-chain trade.
For example:
GET https://api.hashflow.com/taker/v2/price-levels
  ?source=<source>
  &networkId=<src-chain-id>
  &dstNetworkId=<dst-chain-id>
  &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/v2/rfq
​
// JSON body
{
  networkId: number, // 1 for mainnet
  source: string, // Your identifier (e.g. "1inch", "zerion")
  
  rfqType: number,  // RFQ type (e.g. who has the last look). 0: RFQ-t(aker) and 1: RFQ-m(aker)
​
  // Base token (the token the trader sells).
  baseToken: string,  // contract address (e.g. "0x123a...789")
  baseTokenAmount: ?string,  // decimal amount (e.g. "1000000" for 1 USDT)
​
  // Quote token (the token the trader buys).
  quoteToken: string,  // contract address (e.g. "0x123a...789")
  quoteTokenAmount: ?string,  // decimal amount (e.g. "1000000" for 1 USDT)
​
  /* NOTE: Exactly one of base/quote tokenAmount must be present. */
    
  // The trader wallet address that will swap with our contract. This can be a proxy
  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 market maker to request. If missing, we query all MMs and pick the best quote
  marketMakers: ?string[],  // e.g. ["mm1"]
}
NB: 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
  signature?: string,
  
  quoteData?: {
    rfqType: number,
    txid: string,  // Unique quote identifier. Different from RFQ ID.
    pool: string,
    dstPool?: string,  // For cross-chain quotes, the pool on the destination chain ID
    eoa: ?string,  // EOA address if market maker uses an EOA
    
    // Quote
    baseToken: string,
    baseTokenAmount: string,
    quoteToken: string,
    quoteTokenAmount: string,
  
    // UNIX timestamp when quote expires
    quoteExpiry: number,   
​
    trader: string,
    effectiveTrader: ?string,
​
    // The following parameter is used by Hashflow contracts to prevent replay.
    nonce: number
  },
  
  gasEstimate?: number,  // Estimated number of gas units
  nativeTokenPriceUsd?: number,  // USD price of gas currency (ETH, MATIC, etc)
}
Cross-Chain RFQ
In order to request a cross-chain quote, a dstNetworkId field needs to be added to the /rfq request, which represents the Chain ID of the destination chain. quoteToken has to be a valid ERC-20 (or native token) address on the destination chain.
For example:
POST https://api.hashflow.com/taker/v2/rfq
​
// JSON body
{
  networkId: number, // source chain ID
  dstNetworkId: number, // destination chain ID
  source: string, // Your identifier (e.g. "1inch", "zerion")
  
  rfqType: number,  // RFQ type (e.g. who has the last look). 0: RFQ-t(aker) and 1: RFQ-m(aker)
​
  // Base token (the token the trader sells).
  baseToken: string,  // contract address (e.g. "0x123a...789")
  baseTokenAmount: ?string,  // decimal amount (e.g. "1000000" for 1 USDT)
​
  // Quote token (the token the trader buys).
  quoteToken: string,  // contract address (e.g. "0x123a...789")
  quoteTokenAmount: ?string,  // decimal amount (e.g. "1000000" for 1 USDT)
​
  /* NOTE: Exactly one of base/quote tokenAmount must be present. */
    
  // The trader wallet address that will swap with our contract. This can be a proxy
  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 market maker to request. If missing, we query all MMs and pick the best quote
  marketMakers: ?string[],  // e.g. ["mm1"]
}
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 to swap the funds between trader and market maker.
The tradeSingleHop 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).
The contract has the following addresses:
"HashflowRouter": {
  "1": {
    "address": "0xF6a94dfD0E6ea9ddFdFfE4762Ad4236576136613"
  },
  "10": {
    "address": "0xb3999F658C0391d94A37f7FF328F3feC942BcADC",
  },
  "56": {
    "address": "0x0ACFFB0fb2cddd9BD35d03d359F3D899E32FACc9",
  },
  "137": {
    "address": "0x72550597dc0b2e0beC24e116ADd353599Eff2E35",
  },
  "42161": {
    "address": "0x1F772fA3Bc263160ea09bB16CE1A6B8Fc0Fab36a",
  },
  "43114": {
    "address": "0x64D2f9F44FE26C157d552aE7EAa613Ca6587B59e",
  }
},
and the following ABI:
{
    "inputs": [
        {
            "components": [
                {
                    "internalType": "address",
                    "name": "pool",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "externalAccount",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "trader",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "effectiveTrader",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "baseToken",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "quoteToken",
                    "type": "address"
                },
                {
                    "internalType": "uint256",
                    "name": "effectiveBaseTokenAmount",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "maxBaseTokenAmount",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "maxQuoteTokenAmount",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "quoteExpiry",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "nonce",
                    "type": "uint256"
                },
                {
                    "internalType": "bytes32",
                    "name": "txid",
                    "type": "bytes32"
                },
                {
                    "internalType": "bytes",
                    "name": "signature",
                    "type": "bytes"
                }
            ],
            "internalType": "struct IQuote.RFQTQuote",
            "name": "quote",
            "type": "tuple"
        }
    ],
    "name": "tradeSingleHop",
    "outputs": [],
    "stateMutability": "payable",
    "type": "function"
}
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 is available via API calls, as such:
GET https://api.hashflow.com/taker/v2/xchain-fee-estimate
  ?source=<source>
  &protocol=0 // this represents Wormhole
  &srcNetworkId=<src-chain-id>
  &dstNetworkId=<dst-chain-id>
The response, if successful will look like:
{ "status": "success", "estimatedFees": "58250613439028287" }
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.
The ABI is the following:
{
    "inputs": [
        {
            "components": [
                {
                    "internalType": "uint16",
                    "name": "srcChainId",
                    "type": "uint16"
                },
                {
                    "internalType": "uint16",
                    "name": "dstChainId",
                    "type": "uint16"
                },
                {
                    "internalType": "address",
                    "name": "srcPool",
                    "type": "address"
                },
                {
                    "internalType": "bytes32",
                    "name": "dstPool",
                    "type": "bytes32"
                },
                {
                    "internalType": "address",
                    "name": "srcExternalAccount",
                    "type": "address"
                },
                {
                    "internalType": "bytes32",
                    "name": "dstExternalAccount",
                    "type": "bytes32"
                },
                {
                    "internalType": "address",
                    "name": "trader",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "baseToken",
                    "type": "address"
                },
                {
                    "internalType": "address",
                    "name": "quoteToken",
                    "type": "address"
                },
                {
                    "internalType": "uint256",
                    "name": "baseTokenAmount",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "quoteTokenAmount",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "quoteExpiry",
                    "type": "uint256"
                },
                {
                    "internalType": "uint256",
                    "name": "nonce",
                    "type": "uint256"
                },
                {
                    "internalType": "bytes32",
                    "name": "txid",
                    "type": "bytes32"
                },
                {
                    "internalType": "bytes",
                    "name": "signature",
                    "type": "bytes"
                }
            ],
            "internalType": "struct IQuote.XChainRFQTQuote",
            "name": "quote",
            "type": "tuple"
        },
        {
            "internalType": "enum IHashflowXChainUA.XChainMessageProtocol",
            "name": "protocol",
            "type": "uint8"
        }
    ],
    "name": "tradeXChain",
    "outputs": [],
    "stateMutability": "payable",
    "type": "function"
}
Things to note:
value: This method should always be passed value. If the baseToken is a native token, the value passed should be baseTokenAmount plus the cross-chain fee estimate computed above. If not, only the cross-chain fee estimate should be passed.
srcChainId and dstChainId are Hashflow Chain IDs. The mapping between networkId and Hashflow chain ID can be found below
protocol will be 1 for Wormhole. You should use the protocol enum returned by the RFQ API
dstPool and dstExternalAccount should be prefixed with 0 up until they reach 32 bytes, for EVM chains, where they will be 20-byte addresses
Network ID
Hashflow Chain ID
1
1
56
6
43114
4
137
5
42161
2
10
3
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/v2/restrictions?source=<your-source>&trader=<0x...>&chainId=<chainId>
 The response will be in the following shape  
{ 
  isTraderRestricted: boolean; 
  restrictions?: Array<{ 
    restrictionReason: string; 
    restrictionExpiryTimestampMs?: number; //UTC milliseconds timestamps
    makerName?: string; 
    networkId?: string
  }> 
}
7. Success!
Congrats! You've successfully integrated with Hashflow as a taker 🥳
Network ID	Hashflow Chain ID
1	1
56	6
43114	4
137	5
42161	2
10	3
Last modified 4d ago
Getting Started

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 `/marketMakers`

3. Query Price Levels (for price discovery)

Cross-Chain price levels

4. Query `/rfq`

Cross-Chain RFQ

5. Execute quote on-chain

Executing cross-chain quotes

6. Query `/restrictions`

7. Success!
