REST API
This page explains how solvers can interact with the Liquorice RFQ REST API.
1. Authentication
Include the following headers with each request:
solver
- name of the Solverauthorization
- authorization token
2. Connected makers
Use the following endpoint to retrieve a list of currently connected makers:
URL: https://api.liquorice.tech/v1/solver/connected-makers
Method: GET
Response:
[
"maker-a",
"maker-b"
]
3. RFQ
To obtain a quote from Liquorice, send an RFQ to the following endpoint:
URL: https://api.liquorice.tech/v1/solver/rfq
Method: POST
Body:
{
/// Chain ID (e.g for ArbitrumOne chainId = 42161)
chainId: number;
/// UUID of the RFQ (Must be generated by caller)
rfqId: string;
/// RFQ expiration UNIX timestamp (seconds)
expiry: number,
/// Address of token to be sent by trader
baseToken: string;
/// Address of the token to be received by trader
quoteToken: string;
/// Address of the account receiving quoteToken
trader: string;
/// Optional address of the account sending baseToken
/// If omitted, the system assumes that baseToken will be sent from trader address
effectiveTrader?: string;
/// Note: Exactly one of the following two fields must be present
/// Amount of baseToken with up to 18 decimal places, e.g. 100000000 (1 WBTC)
baseTokenAmount?: string;
/// Amount of quoteToken with up to 18 decimal places
quoteTokenAmount?: string;
/// List of maker names excluded from RFQ processing
excludedMakers?: string[];
/// Optional metadata that provides context about the intent origin
intentMetadata?: {
source: 'cow_protocol';
content: {
/// CoW auction ID
auctionId: number;
}
}
}
The RFQ must include either
baseTokenAmount
orquoteTokenAmount
, but not both. WhenbaseTokenAmount
is specified, thetrader
(order initiator) is requesting the amount ofquoteToken
they would receive in exchange for a specific amount ofbaseToken
. WhenquoteTokenAmount
is specified, thetrader
(order initiator) is requesting the amount ofbaseToken
they need to provide to receive a specific amount ofquoteToken
.excludedMakers
- to exclude specific makers from RFQ processing, obtain the complete maker list from the relevant API endpointintentMetadata
- For the moment, only CoW Protocol is supported. Omit this setting when requesting quotes for other intent origins.
Response
{
/// UUID of the RFQ
rfqId: string,
/// Indicates whether liquidity is available to fulfill RFQ
liquidityAvailable: boolean,
/// Array of available quote levels.
/// Empty when liquidityAvailable is false
levels: [{
/// UUID of the maker RFQ that sourced this quote level
makerRfqId: string,
/// Name of the maker providing this quote level
maker: string,
/// Hex-encoded 32-byte nonce
nonce: string,
/// Quote expiration UNIX timestamp (seconds)
expiry: number,
/// Transaction details
tx: {
/// Address of the LiquoriceSettlement contract
to: string,
/// 0x-prefixed calldata string for the function within
/// LiquoriceSettlement contract
data: string
},
/// Address of token to be sent by trader
baseToken: string,
/// Address of the token to be received by trader
quoteToken: string,
/// Amount of baseToken with up to 18 decimal places, e.g. 100000000 (1 WBTC)
baseTokenAmount: string,
/// Amount of quoteToken with up to 18 decimal places
quoteTokenAmount: string,
/// Settings for partial fill functionality.
/// If absent, the order cannot be filled partially
partialFill?: {
/// Byte offset of the fill amount parameter in tx.data
offset: number,
/// Minimum fillable amount of baseToken, with up to 18 decimal places
minBaseTokenAmount: string
}
}]
}
Market makers can provide multiple quote levels with different amounts, but the quoted amounts will not exceed those specified in the RFQ.
Example For an RFQ where:
baseToken = ETH
quoteToken = USDT
baseTokenAmount = 1 ETH
The resulting quote may contain these levels:
Level 0: Exchange 1 ETH for 3,000 USDT
Level 1: Exchange 0.5 ETH for 1,502 USDT
Level 2: Exchange 0.1 ETH for 310 USDT
IMPORTANT NOTE: While solvers typically execute a single quote level, it is technically possible to execute multiple quote levels if they come from different market makers. When using multiple quote levels, ensure that they come from different makers, as quotes from the same maker will result in only one successful execution.
3.1. Partial fills
The quote level's partialFill.offset
field specifies the byte offset of filledTakerAmount
parameter within tx.data.
The partial fill amount must be greater than or equal to partialFill.minBaseTokenAmount
.
If the partialFill
field is not present, the quote level must be filled completely.
let calldata = tx.data.slice(0, 10 + partialFill.offset * 2) // Calldata up to offset. 2 is for `0x` prefix and 8 for the function selector.
+ fillAmount.toString(16).padStart(64, "0") // Replace with partial fill amount in hex, padded to 64 chars
+ tx.data.slice(10 + partialFillOffset * 2 + 64); // Remaining calldata after filledTakerAmount
Last updated