Documentation Index
Fetch the complete documentation index at: https://docs.houdiniswap.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Fixed rate swaps lock the exchange rate at the moment you request a quote. The user receives exactly the quotedamountOut regardless of market movement between quote time and swap execution — as long as the exchange is created before the rate lock expires.
Best For: Partners and users who want price certainty and are willing to plan around a short rate-lock window. Ideal for high-value swaps where slippage risk is unacceptable.
Key Features
Guaranteed Output
User receives exactly
amountOut as quoted — no slippage, no surprises at settlementRate Lock Window
validUntil timestamp gives you a window to create the exchange before the rate expiresRefund on Failure
If the swap fails after the rate is locked, the
refundAddress is used for any potential refund — though refund handling depends on the providerProvider-Bound Rate
The rate is held by a specific CEX provider via
rateId — no silent fallback to a different provider or rateHow It Works
Get a Fixed Rate Quote
Call
GET /quotes with fixed=true. The response includes a quoteId, guaranteed amountOut, and validUntil expiry.Create the Exchange
Call
POST /exchanges with the quoteId, addressTo, and a refundAddress. The refundAddress is required for fixed rate orders.Integration Guide
Step 1: Get Tokens
Token fetching is the same as for standard swaps — paginate through/v2/tokens?hasCex=true and cache the results. See Standard Swap — Step 1 for the full code example.
Use each token’s id field (not symbol) in the /quotes request.
Step 2: Get a Fixed Rate Quote
Addfixed=true to your /quotes request. The API will automatically restrict results to standard (CEX) quotes only — you do not need to pass types=standard separately.
Pass refundAddress at quote time so it is validated early. It must be a valid address on the source chain.
Fixed Rate Quote Response
| Field | Type | Description |
|---|---|---|
quoteId | string | Pass to /exchanges to create the order |
fixed | boolean | true confirms this is a fixed-rate quote |
rateId | string | Provider-internal rate lock identifier — carried automatically via quoteId |
validUntil | string (ISO 8601) | Hard deadline — create the exchange before this timestamp |
amountOut | number | Guaranteed output amount |
Step 3: Create the Exchange
PassquoteId, addressTo, and refundAddress to POST /exchanges. The refundAddress is required for fixed rate orders — omitting it returns a 422 error.
Exchange Response
| Field | Type | Description |
|---|---|---|
houdiniId | string | Unique order ID — use for status polling |
depositAddress | string | Send input funds here |
inAmount / inSymbol | number / string | Exact amount and token to send |
expires | string (ISO 8601) | Deposit deadline (typically 30 minutes) |
fixed | boolean | Confirms the order is rate-locked |
validUntil | string (ISO 8601) | Rate lock expiry echoed from the quote |
refundAddress | string | Address used for refunds if the swap fails — whether a refund is issued depends on the provider |
The rate is bound to a single provider via the
rateId embedded in the quoteId. If that provider loses fixed-rate capability between quote and exchange time, you will receive FIXED_RATE_QUOTE_EXPIRED — there is no silent fallback to a different provider or rate.Step 4: Send Deposit
After creating the order, send the input tokens todepositAddress. The status advances automatically once the deposit is detected on-chain.
Step 5: Monitor Order Status
PollGET /orders/{houdiniId} to track progress, or subscribe via the WebSocket API for real-time updates:
Status Progression
Error Codes
| Code | HTTP | When |
|---|---|---|
REFUND_ADDRESS_REQUIRED_FOR_FIXED_RATE | 422 | /exchanges called without refundAddress |
ANONYMOUS_AND_FIXED_RATE_NOT_SUPPORTED | 422 | fixed=true combined with private/anonymous swap mode |
DEX_AND_FIXED_RATE_NOT_SUPPORTED | 422 | fixed=true combined with a DEX quote type |
FIXED_RATE_QUOTE_EXPIRED | 422 | validUntil has passed, or the provider lost fixed-rate capability after the quote was issued |
ADDRESS_INVALID_FOR_CHAIN | 422 | refundAddress fails format validation for the source chain |
Best Practices
Always check validUntil before creating the exchange
Always check validUntil before creating the exchange
Build in a buffer — don’t wait until the last second. Check
Date.now() < new Date(quote.validUntil) immediately before calling /exchanges. If the window is too short, fetch a fresh quote rather than risk FIXED_RATE_QUOTE_EXPIRED.refundAddress must be on the source chain
refundAddress must be on the source chain
The refund wallet is validated against source-chain address format rules (including Solana, XRP, and other non-EVM chains). Pass it at quote time so validation happens early — not when you create the exchange.
No fallback if the provider becomes unavailable
No fallback if the provider becomes unavailable
Show the rate lock to the user
Show the rate lock to the user
Display
amountOut and validUntil prominently in your UI before the user confirms. This sets clear expectations about the guaranteed output and how long they have to act.Common Issues
FIXED_RATE_QUOTE_EXPIRED
FIXED_RATE_QUOTE_EXPIRED
Cause: The exchange was created after
validUntil, or the provider lost fixed-rate capability between quote and exchange time.Solution: Fetch a new quote. If the error recurs, the provider may have temporarily disabled fixed rate — try again after a short delay or present the user with a floating-rate quote as a fallback.REFUND_ADDRESS_REQUIRED_FOR_FIXED_RATE
REFUND_ADDRESS_REQUIRED_FOR_FIXED_RATE
Cause:
refundAddress was not included in the /exchanges request body.Solution: Always include refundAddress when creating a fixed rate exchange. Collect and validate the address before the user submits.Order failed / status is REFUNDED
Order failed / status is REFUNDED
Cause: The swap failed after the rate lock was accepted — for example, the CEX rejected the transaction.Solution: Refund handling depends on the provider. Some providers automatically return funds to
refundAddress; others require the user to contact customer support. Inform the user of the failure and direct them to support if a refund is not issued automatically.Next Steps
Standard Swaps
Fast single-hop CEX swaps without rate lock
Private Swaps
Multi-hop privacy swaps via CEX routing
Order Lifecycle
Understand all order statuses
Error Handling
Handle errors and edge cases