Standard Swap Flow - Houdini documentation

Overview

Standard swaps use a single centralized exchange (CEX) for routing, providing the fastest execution times. These swaps use CEX tokens from the /tokens endpoint and are routed directly through one exchange, completing in 3-30 minutes on average.

Best For: Users who prioritize speed and want the fastest completion times (typically 3-30 minutes) with straightforward single-hop routing.

How It Works

Standard swaps follow this flow:

Get Supported Assets

Fetch available tokens from /tokens

Request Quote

Get a quote with anonymous: false for standard routing

Create Order

Submit swap order with user’s destination address

Single CEX Routing

Funds are routed through one centralized exchange

Receive Funds

Output tokens sent directly to destination address

Integration Guide

Step 1: Get Supported Assets

Before requesting a quote, fetch the available tokens. Learn more about CEX tokens.

Performance Note: The /tokens endpoint can take several seconds to minute to respond due to the large token list.

Save tokens in your backend database
Load tokens on server startup or via scheduled job
Serve token list from your database to frontend
Refresh cache periodically (e.g., every 24 hours)

const tokens = await fetchFromHoudini('/tokens');

console.log('Available tokens:', tokens.length);

# Get CEX tokens
curl -X GET "https://api-partner.houdiniswap.com/tokens" \
  -H "Authorization: your_api_key:your_api_secret" \
  -H "x-user-ip: 192.168.1.1" \
  -H "x-user-agent: Mozilla/5.0..." \
  -H "x-user-timezone: America/New_York"

Step 2: Request Quote

Request a quote with anonymous: false for standard routing. Use token symbols from the /tokens endpoint:

const quote = await fetchFromHoudini('/quote', {
  amount: '1',
  from: 'ETH',         // Token symbol from /tokens
  to: 'USDC',          // Token symbol from /tokens
  anonymous: 'false',  // Standard routing
  useXmr: 'false'
});

console.log('Quote type:', quote.type); // "standard"
console.log('CEX provider:', quote.swapName); // e.g., "Changelly"
console.log('ETA:', quote.duration, 'minutes');

curl -X GET "https://api-partner.houdiniswap.com/quote?amount=1&from=ETH&to=USDC&anonymous=false&useXmr=false" \
  -H "Authorization: your_api_key:your_api_secret" \
  -H "x-user-ip: 192.168.1.1" \
  -H "x-user-agent: Mozilla/5.0..." \
  -H "x-user-timezone: America/New_York"

Quote Response

{
  "amountOut": 2456.78,
  "amountIn": 1,
  "min": 0.01021009,
  "max": 9007199254740991,
  "type": "standard",
  "duration": 3,
  "path": "cl",
  "swap": "cl",
  "swapName": "Changelly",
  "logoUrl": "https://api.houdiniswap.com/assets/logos/changelly.jpg",
  "quoteId": "694cd4ef6ca7023b5e00a288",
  "markupSupported": false,
  "amountOutUsd": 2916.1990075863,
  "rewardsAvailable": true
}

Key Fields:

type: "standard" for single-hop routing
swap: CEX provider code (e.g., "cl" for Changelly)
swapName: Human-readable CEX name
path: Single CEX routing path
duration: Estimated completion time in minutes
markupSupported: Whether markup/fees can be added

Step 3: Create Swap

Create the swap order using the /exchange endpoint:

const swapRequest = {
  amount: 1,
  from: 'ETH',
  to: 'USDC',
  addressTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  receiverTag: '',
  anonymous: false,  // Standard routing
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)',
  timezone: 'America/New_York',
  useXmr: false
};

const response = await fetch(`${API_BASE_URL}/exchange`, {
  method: 'POST',
  headers: {
    'Authorization': `${API_KEY}:${API_SECRET}`,
    'Content-Type': 'application/json',
    'x-user-ip': swapRequest.ip,
    'x-user-agent': swapRequest.userAgent,
    'x-user-timezone': swapRequest.timezone
  },
  body: JSON.stringify(swapRequest)
});

const swap = await response.json();
console.log('Swap created:', swap.houdiniId);
console.log('Deposit to:', swap.senderAddress);

curl -X POST "https://api-partner.houdiniswap.com/exchange" \
  -H "Authorization: your_api_key:your_api_secret" \
  -H "Content-Type: application/json" \
  -H "x-user-ip: 192.168.1.1" \
  -H "x-user-agent: Mozilla/5.0..." \
  -H "x-user-timezone: America/New_York" \
  -d '{
    "amount": 1,
    "from": "ETH",
    "to": "USDC",
    "addressTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "receiverTag": "",
    "anonymous": false,
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "timezone": "America/New_York",
    "useXmr": false
  }'

Exchange Response

{
  "houdiniId": "iBQMRX3xvXrFMGQi71ogo9",
  "created": "2025-12-25T06:13:46.673Z",
  "senderAddress": "0x7364a0b6c55004427a4a7c26355ce9c75ef56194",
  "receiverAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "anonymous": false,
  "expires": "2025-12-25T06:43:46.673Z",
  "status": 0,
  "inAmount": 1,
  "inSymbol": "ETH",
  "outAmount": 23.85541415,
  "outSymbol": "USDC",
  "eta": 3,
  "inAmountUsd": 2937,
  "inCreated": "2025-12-25T06:13:46.673Z",
  "id": "694cd61a3544ef38231cc6f4",
  "quote": {
    "amountIn": 1,
    "amountOut": 23.85353526,
    "min": 0.01021398,
    "max": 9007199254740991,
    "path": "cl",
    "type": "standard"
  },
  "outToken": {
    "id": "6689b73ec90e45f3b3e51558",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "price": 1.0,
    "chain": "ethereum"
  },
  "inToken": {
    "id": "6689b73ec90e45f3b3e51566",
    "symbol": "ETH",
    "name": "Ethereum",
    "decimals": 18,
    "price": 2937,
    "chain": "ethereum"
  },
  "inStatus": 0
}

Key Response Fields:

houdiniId: Unique swap identifier - use this to check status
senderAddress: Deposit address where you send funds
receiverAddress: Your destination address
inAmount / outAmount: Expected amounts for the swap
status: Current swap status (0 = pending deposit)
inStatus: Detailed status for the swap
expires: Quote expiration time (typically 30 minutes)
eta: Estimated time to completion in minutes
quote.path: Single CEX provider code

Important: Send exactly inAmount of inSymbol to the senderAddress within the expiration time.

Step 4: Send Deposit

After creating the swap, send the tokens to the deposit address:

Get Deposit Address

Use senderAddress from the exchange response

Send Exact Amount

Send exactly inAmount of the source token

Wait for Confirmations

Status will change from 0 (WAITING) to 1 (CONFIRMING)

Step 5: Monitor Status

Poll the status endpoint to track swap progress:

const status = await fetchFromHoudini('/status', {
  id: swap.houdiniId
});

console.log('Status:', status.status);
// 0 = WAITING (awaiting deposit)
// 1 = CONFIRMING (deposit received)
// 2 = EXCHANGING (processing on CEX)
// 4 = COMPLETED (swap complete)

curl -X GET "https://api-partner.houdiniswap.com/status?id=iBQMRX3xvXrFMGQi71ogo9" \
  -H "Authorization: your_api_key:your_api_secret" \
  -H "x-user-ip: 192.168.1.1" \
  -H "x-user-agent: Mozilla/5.0..." \
  -H "x-user-timezone: America/New_York"

Status Progression

Standard swaps follow this status flow:

0 (WAITING)
  ↓ User sends deposit
1 (CONFIRMING)
  ↓ Deposit confirmed
2 (EXCHANGING)
  ↓ CEX processes swap
4 (COMPLETED)

Polling: Check status every 30 seconds. Standard swaps typically complete in 3-30 minutes.

Complete Example

For a complete, runnable Node.js example:

Standard Swap Example

Complete standard swap script with status monitoring

Best Practices

Transaction Monitoring

Poll status every 30 seconds
Handle all status codes properly (0-8)
Store houdiniId for future reference

Error Handling

Check for quote expiration before creating swap
Validate deposit address format
Handle network congestion delays
Implement retry logic for API calls
Check final states: COMPLETED (4), FAILED (6), EXPIRED (5), REFUNDED (7)

User Experience

Show clear deposit instructions
Display countdown for quote expiration
Provide CEX provider information
Show estimated completion time
Display transaction progress clearly

Security

Validate all addresses before submitting
Never expose API keys in frontend
Verify compliance headers are correct
Store swap records for audit trail
Use backend-only API integration

Common Issues

Swap Taking Longer Than Expected

Causes:

Network congestion on source/destination chain
CEX processing delays
Deposit confirmation delays

Solution: Continue monitoring. Most swaps complete within 2x the estimated time.

Wrong Amount Deposited

Issue: User sent incorrect amount to deposit addressSolution:

Partial refund may be processed
Contact support with houdiniId
Always send exact inAmount

Quote Expired

Cause: Took too long to deposit after creating swapSolution: Create new swap with fresh quote. Quotes expire after 30 minutes.

Status Stuck at CONFIRMING

Issue: Swap stuck at status 1 (CONFIRMING)Solution:

Wait for blockchain confirmations
Check transaction on block explorer
Verify correct amount was sent

Next Steps

Private Swaps

Learn about private multi-hop swaps

DEX Swaps

Integrate on-chain DEX swaps

Order Lifecycle

Understand swap status progression

Error Handling

Handle errors and edge cases

​Overview

​How It Works

​Integration Guide

​Step 1: Get Supported Assets

​Step 2: Request Quote

​Quote Response

​Step 3: Create Swap

​Exchange Response

​Step 4: Send Deposit

​Step 5: Monitor Status

​Status Progression

​Complete Example

Standard Swap Example

​Best Practices

​Common Issues

​Next Steps

Private Swaps

DEX Swaps

Order Lifecycle

Error Handling

Overview

How It Works

Integration Guide

Step 1: Get Supported Assets

Step 2: Request Quote

Quote Response

Step 3: Create Swap

Exchange Response

Step 4: Send Deposit

Step 5: Monitor Status

Status Progression

Complete Example

Best Practices

Common Issues

Next Steps