|
| 1 | +--- |
| 2 | +sidebar_label: "Jupiter Z (RFQ)" |
| 3 | +description: "Integrate your DEX into Jupiter." |
| 4 | +title: "RFQ Integration" |
| 5 | +--- |
| 6 | + |
| 7 | +<head> |
| 8 | + <title>RFQ Integration</title> |
| 9 | + <meta name="twitter:card" content="summary" /> |
| 10 | +</head> |
| 11 | + |
| 12 | +This section will cover the integration of your RFQ service into Jupiter's routing system. |
| 13 | + |
| 14 | +:::caution |
| 15 | +The integration requirements are subjected to change and please provide suggestions or feedbacks on ways to improve the integration process. |
| 16 | +::: |
| 17 | + |
| 18 | +<img src="/dev/rfq-flow.png" alt="RFQ Flow" width="700" /> |
| 19 | + |
| 20 | +## Integration Prerequisites |
| 21 | + |
| 22 | +- Host a service that adheres to our RFQ API schema |
| 23 | +- Provide a webhook for Jupiter to send quotes and swap transactions |
| 24 | +- Complete end-to-end integration tests |
| 25 | +- When ready, you will be onboarded to Edge before going live on production |
| 26 | + |
| 27 | +:::note |
| 28 | +[Please reach out to us in Discord](https://discord.gg/jup) |
| 29 | +- If you are interested to participate in Jupiter Z |
| 30 | +- If you need any help or clarification regarding the integration. |
| 31 | +- To begin onboarding to Edge. |
| 32 | +::: |
| 33 | + |
| 34 | +### Example Integration |
| 35 | + |
| 36 | +To facilitate the integration, we provide an [integration SDK in this repository](https://github.com/jup-ag/rfq-webhook-toolkit). |
| 37 | + |
| 38 | +- [**Sample server**](https://github.com/jup-ag/rfq-webhook-toolkit/tree/main/server-example/): Implements the webhook API in Rust. |
| 39 | +- [**API Schema**](https://github.com/jup-ag/rfq-webhook-toolkit/tree/main/openapi): OpenAPI schema for the RFQ API. |
| 40 | +- [**Integration tests**](https://github.com/jup-ag/rfq-webhook-toolkit/tree/main/tests/): Verify the implementation of the webhook. |
| 41 | +- [**Troubleshooting**](https://github.com/jup-ag/rfq-webhook-toolkit/tree/main/tests/README.md#troubleshooting): Common issues that arise during integration. |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +### RFQ API Schema |
| 46 | + |
| 47 | +To facilitate the integration into Jupiter's RFQ module, you will need to provide a webhook for us to register the quotation and swap endpoints with the corresponding request and response format. |
| 48 | + |
| 49 | +| Endpoint | Method | URL | Description | |
| 50 | +|----------|--------|-----|-------------| |
| 51 | +| Base URL | - | `https://your-api-endpoint.com/jupiter/rfq` | Example URL that we will register into our API | |
| 52 | +| Quote | POST | `https://your-api-endpoint.com/jupiter/rfq/quote` | Called to request quotes | |
| 53 | +| Swap | POST | `https://your-api-endpoint.com/jupiter/rfq/swap` | Called to execute swaps | |
| 54 | +| Tokens | GET | `https://your-api-endpoint.com/jupiter/rfq/tokens` | Called periodically to fetch supported tokens (see [below](#advertising-supported-tokens)) | |
| 55 | + |
| 56 | +:::note API Key |
| 57 | +If you require an API key to access your endpoints, please provide it to us during the registration process. The API Key will be passed to the webhook as a header `X-API-KEY`. |
| 58 | +::: |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +### Response Codes |
| 63 | + |
| 64 | +Market Makers should return appropriate HTTP status codes along with error messages. |
| 65 | + |
| 66 | +| Status Code | Description | |
| 67 | +|--------------|-------------| |
| 68 | +| `200 OK` | The request was successful, and the webhook will return a quote | |
| 69 | +| `404 Not Found` | The webhook will not return a quote for this request (e.g. the pair or the size are not supported) | |
| 70 | +| `400 Bad Request` | The request sent to the webhook is malformed (e.g. missing an expected parameter) | |
| 71 | +| `401 Unauthorized` | Authorization failed. For example the `X-API-KEY` is missing or incorrect | |
| 72 | +| `50x Server Errors` | The webhook is offline or unable to respond. If the status persist, the webhook will be temporarily suspended and will not receive requests | |
| 73 | + |
| 74 | +:::note Timeouts |
| 75 | +A webhook must adhere to the [fullfillment and response time requirements](#fulfillment-requirements). When sending the quote request, the RFQ system includes the following headers: |
| 76 | + |
| 77 | +| Header | Description | |
| 78 | +|--------|-------------| |
| 79 | +| `x-request-start` | The millisecond timestamp indicating when the request was sent | |
| 80 | +| `x-request-timeout` | The millisecond timeout for the request (currently set to 250 ms) | |
| 81 | +::: |
| 82 | + |
| 83 | +## Integration Notes |
| 84 | + |
| 85 | +### Order Engine |
| 86 | + |
| 87 | +The RFQ functionality depends on the mainnet deployment of the [Order Engine Program](https://solscan.io/account/61DFfeTKM7trxYcPQCM78bJ794ddZprZpAwAnLiwTpYH) for order fulfillment. |
| 88 | + |
| 89 | +- **Source Code**: The program's source is located in the [programs/order-engine](https://github.com/jup-ag/rfq-webhook-toolkit/tree/main/programs/order-engine) directory. |
| 90 | +- **IDL**: The Interface Definition Language (IDL) file is available [here](https://github.com/jup-ag/rfq-webhook-toolkit/tree/main/idls). |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +### Non-standard payload |
| 95 | +The transaction data includes, beside the instruction data for the order-engine, 3 additional bytes that are appended to the instruction data. These bytes are not processed by the program and are only information and to be consumed by an off-chain consumer. The first 2 bytes contains the fee amount in basis points (u16) and the third byte (u8) is a bit mask where the least significant bit indicates if the swap is exact-in (0) or exact-out (1). |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +### Fulfillment Requirements |
| 100 | + |
| 101 | +To ensure market makers stay competitive and responsive, we enforce a minimum benchmark for fulfillment and response times. |
| 102 | + |
| 103 | +- **Fulfillment**: Market makers are expected to comply and fulfill **95%** of the quotes provided within a 1-hour window. If this is not met, the market maker will be turned off. |
| 104 | +- **Response Time**: A webhook must respond within **250 ms** of receiving a quote request. If it fails to do so, the RFQ system will proceed with the available quotes at the time. |
| 105 | + |
| 106 | +:::caution |
| 107 | +To resume operations, we will need to manually re-enable your webhook, please reach out to us if this happens. |
| 108 | +::: |
| 109 | + |
| 110 | +:::danger need clarification |
| 111 | +are we penalizing the market maker if they consistently take more than 250ms to respond? |
| 112 | +::: |
| 113 | + |
| 114 | +--- |
| 115 | + |
| 116 | +### Expiry |
| 117 | + |
| 118 | +We enforce a fixed expiry timing flow for all quotes and transactions. This simplifies the integration by removing the need for market makers to specify custom expiry times in quote requests, providing consistent behavior across all quotes and transactions, and establishing clear timeout boundaries at different stages of the flow. |
| 119 | + |
| 120 | +**Breakdown of the expiry flow:** |
| 121 | + |
| 122 | +- **Total of 50 seconds**: Transaction expiry time |
| 123 | +- **1st 25 seconds**: Reserved for the webhook to verify, sign, and send the transaction on-chain |
| 124 | +- **2nd 25 seconds**: Allocated for the user to accept the quote |
| 125 | + |
| 126 | +:::note |
| 127 | +The frontend automatically re-quotes every 5 seconds. |
| 128 | +::: |
| 129 | + |
| 130 | +:::caution |
| 131 | +These expiry thresholds may be adjusted based on performance and feedback. |
| 132 | +::: |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +### Fees |
| 137 | + |
| 138 | +Jupiter RFQ allows MMs a way to provide liquidity, adjust their quotes without being subject to the volatility of on-chain gas prices or chain health. RFQ fills are also much less CU intensive (< 10x) compared to AMM swaps, and can save gas in the long run on fills. Today, RFQ, when operating in Ultra mode, charges a dynamic fee that is selected based on factors like tokens and size. |
| 139 | + |
| 140 | +**Dynamic Fee** |
| 141 | + |
| 142 | +The dynamic fee amount is forwarded to webhooks in the quote request parameters and it is contained in the message that both taker and maker sign ([see the payload section above](#non-standard-payload)). In manual mode, the fee is a flat 2pbs. |
| 143 | + |
| 144 | +**Fee Calculation** |
| 145 | + |
| 146 | +Webhooks do not need to account for fees when quoting, the fee is applied directly by the RFQ system during transaction building. |
| 147 | + |
| 148 | +- For example, for a quote of 1 SOL to 1,000 USDC with a fee of 100 bps |
| 149 | +- Only 990 USDC will be transferred out of the market maker account |
| 150 | +- While 10 USDC will be collected as a fee |
| 151 | + |
| 152 | +:::note |
| 153 | +The fee is not automatically transferred and will be accounted for asynchronously on a regular basis. |
| 154 | + |
| 155 | +This is subject to change in the future. |
| 156 | +::: |
| 157 | + |
| 158 | +--- |
| 159 | + |
| 160 | +## FAQ |
| 161 | + |
| 162 | +**Does RFQ support native SOL?** |
| 163 | + |
| 164 | +Yes, native SOL is fully supported in the order-engine program for both the taker (user) and the maker. However, for now, we assume the maker will use WSOL (Wrapped SOL). |
| 165 | + |
| 166 | +**Do faster quotes receive priority?** |
| 167 | + |
| 168 | +No, the RFQ system dispatches the quote request to all registered webhooks simultaneously. All quotes received within the quote timeout are compared to select the best one. The selection prioritizes the quote value first (In the unlikely scenario where two quotes have identical values, the quote from the webhook with the faster response time will be actually prioritized). |
| 169 | + |
| 170 | +**Shall a webhook verify swap requests?** |
| 171 | + |
| 172 | +Yes, the RFQ system will verify the swap requests before forwarding them to the webhooks. However, webhooks are encouraged to verify the swap requests as well to ensure the integrity of the system. The checks that the RFQ system performs can be found in the [validate_similar_fill_sanitized_message](https://github.com/jup-ag/rfq-webhook-toolkit/blob/de46a38c3cfbda730c026a9b4bea85591c83f9e5/order-engine-sdk/src/fill.rs#L151) function. |
| 173 | + |
| 174 | +**Is there a penalty for not providing a quote (status code 404)?** |
| 175 | + |
| 176 | +No, there is no penalty. It is up to the webhook to decide whether to respond with a quote (`200 OK`) or indicate that it cannot provide one (`404 Not Found`). |
| 177 | + |
| 178 | +For example, suppose a webhook provides quotes for USDC/SOL only within a range of 100 to 1000 USDC. If it receives a quote request for 10 USDC → SOL, it will respond with `404 Not Found`, since the amount is outside its quoting range. |
| 179 | + |
| 180 | +In another case, a webhook may only support one-way quotes (USDC → SOL) but not SOL → USDC. If it receives a request for SOL → USDC, it will also return `404 Not Found`. |
| 181 | + |
| 182 | +**Is there a fee applied to stable-to-stable swaps?** |
| 183 | + |
| 184 | +No. Stable to stable swaps are exempt from fees. |
0 commit comments