1
Quote
GET /quote?inputMint=…&outputMint=…&amount=…&slippageBps=50 answers the route, the amounts and otherAmountThreshold. Every quote is checked to be buildable before it is served.2
Build
POST /swap-instructions with userPublicKey and the quote (quoteResponse) answers the instructions; add "serialize": true for an unsigned transaction.3
Sign and send
Sign the v1 transaction with the user’s key and send it right away:
lastValidBlockHeight is its deadline, and the router’s blockhash can already be up to 30 seconds old.Three ways to name the route at build time
The build takes the route in one of three forms, in this order of precedence:
Send the quote back unchanged. Its
routePlan is checked before anything is read: every route must chain from inputMint to outputMint, with at most 4 steps per route and 2 routes, and every label must be a dex of /venues; anything else is 400 bad_request. With a quote or a ticket, any inputMint, outputMint (and with a ticket, amount) you also send must match it, or the build answers 400 quote_mismatch / route_ticket_mismatch. If a pinned route crosses a venue the router has since stopped serving, the build answers 409 venue_red: quote again.
routeTicket is not authentication. It is the quote, readable by anyone, with an HMAC so it cannot be altered. A router without ROUTER_TICKET_SECRET puts no ticket on its quotes and answers 400 invalid_route_ticket to one.ExactIn and ExactOut
swapMode is ExactIn (default) or ExactOut.
How an ExactOut is executed depends on the route:
- One hop on a venue with an exact-output instruction (
onchainExactOutin/venues): the output is pinned and the input is at mostotherAmountThreshold. - Anything else (several hops, or a venue without that instruction): the route is built as an exact-in that spends the slippage cap (
otherAmountThreshold) with a minimum output equal to the requested amount. The user pays the cap, notinAmount, and any output above the requested amount stays with the user.
shape (exact_out, or an exact-in shape such as token_exact_in) and gives the bounds as minReturn and maxAmountIn.
Slippage
slippageBpsdefaults to 50 (0.5%). On/quotea value above 10000 is400; in a build body it is taken as 10000.- A
slippageBpsin the build body replaces the quote’s (or the ticket’s). Send it only on purpose. - Your deploy’s admin can cap slippage per venue on chain. A lower cap makes a route revert beyond it, even inside the slippage you asked for.
Choosing venues
Lists are comma-separated in the query string, or JSON arrays in a
POST /quote body. Venues the router’s price checks currently hold out are removed from every quote automatically; GET /ready lists them in red_pass.
Split routes
allowSplit=true lets the router split an ExactIn across two routes in one transaction, when the split beats the best single route by at least 1 bps and still fits the transaction. In the quote, routePlan lists route A’s steps then route B’s; the first step of each carries its share in percent (rounded) and bps (exact).
Splits are not served for ExactOut or with a platform fee.
Wrapping SOL
wrapAndUnwrapSol (alias unwrapSol) defaults to true:
- SOL in: the build moves the lamports into the user’s wrapped-SOL account (creating it) and closes it after the swap.
- SOL out: the build unwraps by closing the user’s wrapped-SOL account, except when the output goes to another wallet (
destinationTokenAccount), which receives wrapped SOL.
false, the swap spends from and pays into the user’s wrapped-SOL token account and nothing is wrapped or closed.
Sending the output elsewhere
destinationTokenAccount (alias recipient) is the wallet that receives the output, not a token account: the output lands in that wallet’s associated token account, created if missing. A token account there is refused with 400 bad_recipient (it would have received into a nested account the owner cannot see); an SPL multisig is accepted like a wallet.
When the last hop pays native SOL (selling on a SOL-quoted Pump.fun curve or on Moonit), the output can only go to userPublicKey: another destination is 422 declined / wire.