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.
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.
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
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.
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.
You will have to provide the
source
field to every request (GET
or POST
).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
).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
) orapi
- For
<chain
-id>
use your network ID (e.g.1
for Ethereum,137
for Polygon). - For
<wallet-address>
use the0x
-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.
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.
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>
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)
}
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"]
}
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 toeoa
, if set in your signed quote. Otherwise, use0x0000000000000000000000000000000000000000
address.maxBaseTokenAmount
/maxQuoteTokenAmount
: These are what you receive in the API asbaseTokenAmount
/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 tomaxBaseTokenAmount
. We suggest to keep them equal unless there's a discrepancy with the requested amount. If theeffectiveBaseTokenAmount
is less thanmaxBaseTokenAmount
, the exchange ratemaxQuoteTokenAmount / maxBaseTokenAmount
will be preserved and applied toeffectiveBaseTokenAmount
value
: If the baseToken is the native token (e.g. ETH on Ethereum), theeffectiveBaseTokenAmount
needs to be passed asvalue
to the contract call
You can use Etherscan (or similar tools for non-Ethereum chains) to confirm the trade went through.
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 thebaseToken
is a native token, the value passed should bebaseTokenAmount
plus the cross-chain fee estimate computed above. If not, only the cross-chain fee estimate should be passed.srcChainId
anddstChainId
are Hashflow Chain IDs. The mapping betweennetworkId
and Hashflow chain ID can be found belowprotocol
will be1
for Wormhole. You should use the protocol enum returned by the RFQ APIdstPool
anddstExternalAccount
should be prefixed with0
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 |
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
}>
}
Congrats! You've successfully integrated with Hashflow as a taker 🥳
Last modified 4d ago