Preferred & restricted liquidity

If you integrate the FX API and run Stitch, you can steer the book toward your own operator wallets. Two alternate fields — pick one:

Field	Behavior
preferredLiquidityWallets	Use these wallets first, then fall back to the open book
restrictedLiquidityWallets	Use only these wallets — no open-market fallback

Up to 10 Stitch operator addresses. Omit both and nothing changes. Sending both is a 400.

What it does

Instant swaps (/v1/quote, /v1/order-book, /v1/swaps) match funded operator orders from your listed wallets. minRate is still a hard floor. Preferred falls back to the rest of the book when your wallets can't complete the trade; restricted never does. /quote and /swaps return a routing object with preferenceApplied, restrictionApplied, matched amounts, and fallbackUsed. /order-book reports the same via offer counts (preferredOffers, restrictedOffers).

Limit orders (/v1/limit-orders/quote, /v1/limit-orders/prepare) price FastFill against a listed maker when one can fund the whole order. Preferred falls back to the market when they can't; restricted returns fastFillUnavailableReason: "no_restricted_liquidity" instead. When listed 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 on-chain window is unchanged by which API field you used; restricted only controls whether pricing may leave your wallet list.

Instant swap

Prefer your wallets (with fallback):

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

Restrict to your wallets only:

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

Execute with the same field:

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

See Quotes and Swaps.

Limit order

Quote:

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

Or restrict:

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

The response tells you whether listed liquidity was used (usedPreferredLiquidity, usedRestrictedLiquidity, 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,
  "restrictedLiquidityWallets": ["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). With restricted wallets, prepare rejects instead of falling back. Zero addresses are rejected at the request boundary.

Full flow: Limit orders.

Rules of thumb

• Same wallet field on quote and trade — don't mix preferred on quote with restricted on execute.
• Maximum 10 addresses; duplicates are deduped; checksum or lowercase both work.
• Listed wallets must be Stitch operator liquidity. User limit orders don't count.
• Restricted means no open-market matching/pricing fallback. The on-chain 15-second preferred-filler window still opens afterward so a resting limit order doesn't stall if your bot is offline.