Skip to main content
This page is part of the Webhook Integration (V1) guide. It describes the webhook endpoints your service implements and the request and response contract Jupiter uses to call them.

​
Webhook API

You provide a base URL; Jupiter registers the endpoints below against it. If your endpoints require an API key, provide it during registration. Jupiter passes it to the webhook in the X-API-KEY header.

​
Response codes

Return appropriate HTTP status codes with error messages:

​
Timeouts

Quote requests carry two headers: x-request-start (millisecond timestamp when the request was sent) and x-request-timeout (the millisecond timeout, currently 250 ms). Swap requests have a 25-second timeout.

​
Advertising supported tokens

To receive relevant quote requests, advertise the tokens you support: respond to GET /tokens with a JSON array of mint addresses. Jupiter refreshes the list every 10 minutes, so you can add and remove tokens dynamically based on inventory. Only advertise tokens you hold liquidity for and can fill at the 95% rate, and make sure every advertised token has its Associated Token Account (ATA) configured on your maker wallet, including wSOL. A missing ATA fails simulation and your quotes are silently dropped.

​
Permissioned tokens

GET /permissioned-tokens is optional. It advertises tokens you cannot hold as ordinary inventory but mint or burn just-in-time alongside the fill, such as tokenised RWAs (Ondo, xStocks). Same response shape as /tokens; a non-200 response is treated as an empty list. Your supported set is the union of both lists, and a mint is flagged permissioned only if it appears in /permissioned-tokens. For permissioned pairs:
  • No quote-time simulation. Jupiter skips straight to the maximum compute unit limit (200,000 by default), so your fill must complete within that budget. A fill that would have failed simulation now fails on-chain and counts against your fill rate.
  • No taker balance pre-check. The taker’s input balance is only enforced on-chain. If the taker cannot pay, reject the swap with InsufficientBalance; Jupiter re-checks the balance itself and only penalises rejections it finds dishonest.
  • The mint or burn must land atomically with the fill through your own execution infrastructure. The transaction message is fixed by the time it reaches /swap, so you cannot append instructions.
Moving a mint from /tokens to /permissioned-tokens alone is a no-op: Jupiter hashes the sorted union to detect changes, and the union is identical. Introduce the move together with another change to your token set, or ask your Jupiter contact to force a re-sync.

​
Request ID and Quote ID

  • Request ID: a deterministic identifier Jupiter generates by hashing the quote request parameters. Identical parameters produce the same Request ID, which enables idempotency and deduplication. Use it for traceability.
  • Quote ID: a unique identifier for each quote response, derived from your webhook’s internal UUID and the Request ID. Unique even for repeated identical requests. The Quote ID in a swap request identifies exactly which quote to execute, so track quote validity and expiry by Quote ID.