Skip to content
This repository was archived by the owner on Apr 14, 2026. It is now read-only.

Commit bc1c2f0

Browse files
vladwulfvladwulf
authored
Merge pull request #22 from catalystsystem/chore_docs-update-quotes
chore: update quotes endpoints docs
2 parents 1527d86 + 29e61c6 commit bc1c2f0

1 file changed

Lines changed: 261 additions & 39 deletions

File tree

‎src/content/docs/3-solver/303-quoting.mdx‎

Lines changed: 261 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -6,47 +6,74 @@ sidebar:
66
order: 3
77
---
88

9-
The order server will deliver quotes to intent issuers. These are based on the available inventory provided by solvers. To avoid the need for solvers to respond to every individual quote request, the order server allows solvers to regularly push their inventory to the order server in the format of `quote chunks`.
9+
:::note
10+
You can interact with the API through the [swagger docs](https://order-dev.li.fi/docs#/Quotes/QuotesController_submitQuotes) endpoint when the server is running, providing a complete reference for all available endpoints and their schemas.
11+
:::
12+
13+
The order server will deliver quotes to intent issuers.
14+
These are based on the available inventory provided by solvers.
15+
To avoid the need for solvers to respond to every individual quote request, the order server allows solvers to regularly push their inventory to the order server in the format of `solver quotes`.
1016
This approach significantly reduces the overhead for solvers and improves the efficiency of the quoting process.
1117

12-
The following code chunk provides an example implementation of quoting between USDC and USDC between Ethereum and Base.
18+
## Submitting Quotes
19+
20+
Solvers can submit their inventory quotes using the `/quotes/submit` endpoint. This endpoint requires API key authentication and accepts an array of quote objects.
21+
22+
### Quote Structure
23+
24+
Each quote contains the following information:
1325

1426
```json
1527
{
16-
"chainId": 1, // Ethereum
17-
"asset": "0xA0b86991c...", // USDC on Ethereum, address(0) for native tokens
18-
"fromPrice": "1000000000000000000", // price of token in USDC when sold to the solver
19-
"toPrice": "1100000000000000000", // price of token in USDC when bought from the solver
20-
"fromCost": "1000", // cost of token in token when sold to the solver
21-
"toCost": "1000", // cost of token in token when bought from the solver
22-
"maxAmount": 1000000000, // max the solver will handle
23-
"minAmount": 1000000, // minimum amount the solver will process
24-
"expiry": 1713296400 // quote expires at this timestamp
25-
}, {
26-
"chainId": 8453, // Base
27-
"asset": "0x833589fCD...", // USDC on Base, address(0) for native tokens
28-
"fromPrice": "1000000000000000000", // price of token in USDC when sold to the solver
29-
"toPrice": "1100000000000000000", // price of token in USDC when bought from the solver
30-
"fromCost": "1000", // cost of token in token when sold to the solver
31-
"toCost": "1000", // cost of token in token when bought from the solver
32-
"maxAmount": 1000000000, // max the solver will handle
33-
"minAmount": 1000000, // minimum amount the solver will process
34-
"expiry": 1713296400 // quote expires at this timestamp
28+
"fromChain": "84532", // Source chain network ID (Base Sepolia)
29+
"toChain": "11155420", // Destination chain network ID (Optimism Sepolia)
30+
"fromAsset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // Source asset address (address(0) for native tokens)
31+
"toAsset": "0x5fd84259d66Cd46123540766Be93DFE6D43130D7", // Destination asset address (address(0) for native tokens)
32+
"fromDecimals": 6, // Decimals of the source token
33+
"toDecimals": 6, // Decimals of the destination token
34+
"ranges": [
35+
{
36+
"minAmount": "1000000", // Minimum amount that can be swapped (in token units)
37+
"maxAmount": "1000000000", // Maximum amount that can be swapped (in token units)
38+
"quote": "0.99" // Quote rate for this range (as decimal string)
39+
}
40+
],
41+
"expiry": 1672531200, // Quote expires at this Unix timestamp (seconds, no milliseconds)
42+
"exclusiveFor": "0x1234567890123456789012345678901234567890" // Optional: exclusive for specific address
3543
}
3644
```
3745

38-
Prices are specified in an abstract intermediary that has to be consistent between **your** quotes. We recommended using USDC with 18 decimals. Everything is integer priced. Make sure that your decimals are correct. The final quote will be derived as: $$Quote = \frac{\left(inputAmount\ -\ inputFee\right)\ \cdot\ inputPrice}{outputPrice} - outputFee$$
46+
### Complete Submit Request Example
3947

48+
```json
49+
{
50+
"quotes": [
51+
{
52+
"fromChain": "84532",
53+
"toChain": "11155420",
54+
"fromAsset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
55+
"toAsset": "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
56+
"fromDecimals": 6,
57+
"toDecimals": 6,
58+
"ranges": [
59+
{
60+
"minAmount": "1000000",
61+
"maxAmount": "1000000000",
62+
"quote": "0.99"
63+
}
64+
],
65+
"expiry": 1672531200
66+
}
67+
]
68+
}
69+
```
4070

4171
:::caution
42-
It is important to factor token decimals into your quotes; otherwise, assets will be priced incorrectly.
43-
For example, for a 1000 USDC to Ether swap with the price of $1500 USDC per Ether:
44-
45-
$$Quote = \frac{\left(1000'000'000 - 1'000'000\right) \cdot 1'000'000'000'000'000'000}{1500'000'000} - outputFee = 666'666'666'666'666'666 = 0.67\ Ether$$
46-
47-
Note that the decimals are inversely represented. If a USDC quote is provided with 18 decimals, then an Ether quote should have $$6+18-18=6$$ decimals, while another USDC quote should have $$6+18-6=18$$ decimals. A token with 8 decimals should have its quote with $$6+18-8=16$$ decimals.
72+
It is important to factor token decimals into your quotes; otherwise, assets will be priced incorrectly
4873
:::
4974

75+
### Quote Management
76+
5077
It is important that solvers update their quotes periodically as market conditions change, with correct expiry dates. If your quotes expire, the order server will stop using them to match user requests.
5178

5279
:::note[You can overwrite old quotes by sending new quotes]
@@ -55,30 +82,225 @@ To avoid sending short-lived quotes, the order server will overwrite existing qu
5582

5683
By broadcasting quotes in this manner, solvers can:
5784

58-
- Efficiently communicate their available liquidity across multiple chain and token pairs.
59-
- Set their own pricing and fee structure.
60-
- Define limits on transaction sizes they're willing to process.
61-
- Update their quotes as market conditions change.
62-
- The order server then uses these broadcast quotes to match incoming user requests without needing to query solvers in real-time for every request, resulting in faster quote responses for users and reduced operational overhead for solvers.
85+
- Efficiently communicate their available liquidity across multiple chain and token pairs
86+
- Set their own pricing and fee structure
87+
- Define limits on transaction sizes they're willing to process
88+
- Update their quotes as market conditions change
89+
- The order server then uses these broadcast quotes to match incoming user requests without needing to query solvers in real-time for every request, resulting in faster quote responses for users and reduced operational overhead for solvers
90+
91+
## Requesting Quotes
92+
93+
Users can request quotes using the `/quote/request` endpoint. This endpoint does not require authentication and accepts an OIF (Order Intent Format) quote request.
94+
95+
### Open Intent Framework (OIF) Compliance
96+
97+
The quote request endpoint adheres to the [Open Intent Framework (OIF) specifications](https://github.com/openintentsframework/oif-specs), which provides standardized protocols for intent-based interactions in decentralized systems. This compliance ensures:
6398

64-
Submit quotes to [`/quotes/submit`](https://order-dev.li.fi/docs#/Quotes/QuotesController_submitQuote).
99+
- **Interoperability**: The API follows established standards that enable seamless integration with other OIF-compliant systems
100+
- **Consistency**: Quote requests and responses follow a well-defined schema that developers can rely on
101+
- **Future-proofing**: Adherence to the OIF specification ensures compatibility with evolving intent protocols
102+
103+
The OIF specification defines machine-readable schemas, TypeScript interfaces, and OpenAPI documentation that govern how intent-based quote requests should be structured and processed. Our implementation follows these standards to provide a robust and standardized quoting experience.
104+
105+
### Quote Request Structure
106+
107+
```json
108+
{
109+
"user": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
110+
"intent": {
111+
"intentType": "oif-swap",
112+
"inputs": [
113+
{
114+
"user": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
115+
"asset": "0x0001000003014a3414036cbd53842c5426634e7929541ec2318f3dcf7e",
116+
"amount": "23940002"
117+
}
118+
],
119+
"outputs": [
120+
{
121+
"receiver": "0x0001000003aa36a714841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
122+
"asset": "0x0001000003aa36a7141c7d4b196cb0c7b01d743fbc6116a902379c7238",
123+
"amount": null
124+
}
125+
],
126+
"swapType": "exact-input",
127+
"preference": "price"
128+
},
129+
"supportedTypes": ["oif-escrow-v0", "oif-resource-lock-v0"]
130+
}
131+
```
132+
133+
### Quote Response Structure
134+
135+
```json
136+
{
137+
"quotes": [
138+
{
139+
"order": null,
140+
"eta": null,
141+
"validUntil": null,
142+
"quoteId": null,
143+
"metadata": {
144+
"exclusiveFor": "0x1234567890123456789012345678901234567890",
145+
"inputs": [
146+
{
147+
"user": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
148+
"asset": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
149+
"amount": "23940002"
150+
}
151+
],
152+
"outputs": [
153+
{
154+
"receiver": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
155+
"asset": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
156+
"amount": "23592576"
157+
}
158+
]
159+
},
160+
"provider": null,
161+
"partialFill": false,
162+
"failureHandling": "refund-automatic"
163+
}
164+
]
165+
}
166+
```
65167

66168
## Chain & Asset Support
67169

68170
The order server uses quotes to determine supported chains and assets. This allows solvers to add support for new chains and assets simply by producing quotes for them.
69171

70-
## Authentication (WIP)
172+
Currently supported chains:
173+
174+
- **Ethereum Sepolia** (Chain ID: 11155111)
175+
- **Base Sepolia** (Chain ID: 84532)
176+
- **Optimism Sepolia** (Chain ID: 11155420)
177+
178+
Currently supported tokens:
179+
180+
- **USDC** on all supported chains
71181

72-
While authentication is not necessary to subscribe to the order server's WebSocket events, it is required to use some of the order server's API services.
182+
## API Endpoints
183+
184+
### Submit Quotes
185+
186+
- **Endpoint**: `POST /quotes/submit`
187+
- **Authentication**: Required (API Key)
188+
- **Content-Type**: `application/json`
189+
- **Rate Limit**: None specified
190+
191+
### Request Quote
192+
193+
- **Endpoint**: `POST /quote/request`
194+
- **Authentication**: Not required
195+
- **Content-Type**: `application/json`
196+
- **Rate Limit**: None specified
197+
198+
## Authentication
199+
200+
While authentication is not necessary to request quotes, it is required to submit quotes to the order server.
73201
All solvers must be authenticated with the order server to be able to push their inventory. Without authentication, the order server won't be able to offer your quotes to users.
74202
Authentication is handled via API tokens that provide secure access to the order server's protected API services.
75203

76-
##### Obtaining API Access
204+
### Obtaining API Access
77205

78206
To get your API token, please reach out to the order server team.
79207

80-
##### Using Your API Token
208+
### Using Your API Token
81209

82210
If you have an API token, it must be included in all requests to the order server for reputation purposes:
83211

84-
- For HTTP requests: Include the token in the request headers as `x-api-key: YOUR_API_TOKEN`
212+
- For HTTP requests: Include the token in the request headers as `x-api-key: YOUR_API_TOKEN`
213+
214+
### Example Request with Authentication
215+
216+
```bash
217+
curl -X POST "https://your-api-server.com/quotes/submit" \
218+
-H "Content-Type: application/json" \
219+
-H "x-api-key: sk_your_api_key_here" \
220+
-d '{
221+
"quotes": [
222+
{
223+
"fromChain": "84532",
224+
"toChain": "11155420",
225+
"fromAsset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
226+
"toAsset": "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
227+
"fromDecimals": 6,
228+
"toDecimals": 6,
229+
"ranges": [
230+
{
231+
"minAmount": "1000000",
232+
"maxAmount": "1000000000",
233+
"quote": "0.99"
234+
}
235+
],
236+
"expiry": 1672531200
237+
}
238+
]
239+
}'
240+
```
241+
242+
## Error Handling
243+
244+
The API returns standard HTTP status codes:
245+
246+
- **200 OK**: Request successful
247+
- **400 Bad Request**: Invalid request data or validation errors
248+
- **401 Unauthorized**: Missing or invalid API key
249+
- **403 Forbidden**: API key expired or insufficient permissions
250+
- **404 Not Found**: No quotes available for the requested parameters
251+
- **500 Internal Server Error**: Server error
252+
253+
## Rate Limits and Constraints
254+
255+
- Maximum quotes per request: 200,000
256+
- Batch processing: Quotes are processed in batches.
257+
- Quote validation: All quotes must have non-zero values
258+
- Expiry validation: Must be valid Unix timestamp in seconds (10 digits)
259+
260+
## Reputation System
261+
262+
The order server implements a sophisticated reputation system that tracks solver performance and influences quote selection. This system ensures that reliable solvers are prioritized while maintaining fair competition.
263+
264+
### How Reputation Works
265+
266+
**Reputation Accumulation:**
267+
268+
- Solvers earn reputation points when they successfully fill orders
269+
- The reputation is directly tied to the reward amount from filled orders
270+
- Each successful order execution increases the solver's reputation by the reward amount
271+
272+
**Reputation Normalization:**
273+
274+
- The system maintains two reputation metrics: `reputation` (raw points) and `reputationNorm` (normalized value)
275+
- `reputationNorm` is calculated as the square root of the current reputation: `reputationNorm = √(reputation)`
276+
- This normalization prevents high-reputation solvers from completely dominating the market
277+
278+
**Daily Decay:**
279+
280+
- Reputation naturally decays over time to prevent stale reputation from having excessive influence
281+
- Daily decay rate: 1/120 (approximately 0.83% per day)
282+
- Formula: `new_reputation = current_reputation - (current_reputation / 120)`
283+
- This ensures that active solvers maintain their standing while inactive ones gradually lose influence
284+
285+
### Quote Selection Algorithm
286+
287+
When multiple solvers have quotes for the same trade, the system uses a weighted random selection based on reputation:
288+
289+
1. **Filter by Price**: Only quotes within acceptable price ranges are considered
290+
2. **Reputation Weighting**: Each solver's selection probability is proportional to their `reputationNorm` value
291+
3. **Weighted Random Selection**: A random number is generated and matched against cumulative reputation weights
292+
4. **Fair Distribution**: Higher reputation solvers have better chances but don't guarantee selection
293+
294+
### Benefits of the Reputation System
295+
296+
1. **Quality Assurance**: Reliable solvers who consistently fill orders gain higher reputation
297+
2. **Fair Competition**: The square root normalization prevents monopolization
298+
3. **Dynamic Market**: Daily decay ensures the system adapts to changing solver performance
299+
4. **Incentive Alignment**: Solvers are incentivized to provide competitive quotes and execute successfully
300+
5. **User Experience**: Users benefit from higher-quality quotes from proven solvers
301+
302+
### Monitoring Your Reputation
303+
304+
Solver reputation can be monitored through the [Dashboard](https://order-server-dashboard-temp.vercel.app/), which provides a way to view your reputation & manage your api keys:
305+
306+
This transparency allows solvers to understand their standing in the ecosystem and make informed decisions about their quoting strategies.

0 commit comments

Comments
 (0)