Preferred liquidity

If you integrate the FX API and run Stitch, you can ask the book to consume your own operator wallets before anyone else's. Pass the same optional list — up to 10 Stitch operator addresses — on quote and trade endpoints.

This is opt-in. Omit the field and nothing changes.

What it does

Instant swaps (/v1/quote, /v1/order-book, /v1/swaps) match funded operator orders from your preferred wallets first. minRate is still a hard floor. If preferred liquidity can't complete the trade, the API falls back to the rest of the book. /quote and /swaps return a routing object with preferenceApplied, preferredOrdersMatched, preferredFillableAmount, and fallbackUsed. /order-book returns the same preference flags as preferenceApplied, preferredOffers, and fallbackUsed (offer count, not fillable amount).

Limit orders (/v1/limit-orders/quote, /v1/limit-orders/prepare) price FastFill against a preferred maker when one can fund the whole order, then fall back to the market. When preferred wallets are used on prepare, the signed order gives those wallets an exclusive fill window for 15 seconds, then opens to every filler automatically — no second signature. That exclusivity is enforced on-chain by the preferred-filler validation callback, not just API ordering.

Instant swap

Preview:

GET /v1/quote?chainId=8453&sellToken=0xCNGN&buyToken=0xUSDT&sellAmount=1000000000&preferredLiquidityWallets=0xYourStitchWallet

Execute with the same list:

POST /v1/swaps
{
  "chainId": 8453,
  "sellToken": "0xCNGN",
  "buyToken": "0xUSDT",
  "sellAmount": "1000000000",
  "minRate": "600000000000000000000000000",
  "taker": "0xYourWallet",
  "preferredLiquidityWallets": ["0xYourStitchWallet"]
}

See Quotes and Swaps.

Limit order

Quote:

GET /v1/limit-orders/quote?...&preferredLiquidityWallets=0xBotA,0xBotB

The response tells you whether preferred liquidity was used (usedPreferredLiquidity, fallbackUsed, targetFillerWallet).

Prepare with the same wallets when you want the 15-second exclusivity window. Set deadline to now + 600 (unix seconds) — submit rejects TTLs longer than about a year, so don't paste a far-future constant:

POST /v1/limit-orders/prepare
{
  "chainId": 8453,
  "maker": "0xYourWallet",
  "sellToken": "0xCNGN",
  "sellAmount": "1550000000",
  "buyToken": "0xUSDT",
  "pricing": { "mode": "fastFill" },
  "deadline": 1785667200,
  "preferredLiquidityWallets": ["0xYourStitchWallet"]
}

(1785667200 here is just now + 600 as of writing — compute it at request time.)

If preferred wallets can't fund a FastFill-priced order, prepare falls back to market pricing and does not attach exclusivity (so you don't lock the order to wallets that couldn't take it). Zero addresses are rejected at the request boundary.

Full flow: Limit orders.

Rules of thumb

• Same wallet list on quote and trade — don't surprise yourself with a different route at execute time.
• Maximum 10 addresses; duplicates are deduped; checksum or lowercase both work.
• Preferred wallets must be Stitch operator liquidity. User limit orders don't count as preferred.
• After the 15-second exclusive window, any filler can take the order — that's intentional so it doesn't stall if your bot is offline.