Standard Swap Flow

Overview

Standard swaps route through a single centralized exchange (CEX) for fast execution. In API v2, all swap types — standard, private, and DEX — share the same /quotes and /exchanges endpoints. Pass types=standard to get only standard quotes, or filter the response by type: "standard". Tokens are identified by their ID (not symbol), and orders are created by passing a quoteId.

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

Looking for the v1 standard swap guide? See API v1 — Standard Swap.

Need to guarantee the output amount? Add fixed=true and a refundAddress to your quote request to lock the rate. See the Fixed Rate Swap Guide for the full flow.

How It Works

Get Tokens

Bulk fetch CEX-supported tokens and cache to your DB, or search by name/symbol. Note each token’s id.

Get Quotes

Call GET /quotes with token IDs. The response returns quotes from all available providers — select the one with type: "standard".

Create Order

Call POST /exchanges with the selected quoteId and the user’s destination address.

Send Deposit

Send exactly inAmount of the input token to the depositAddress returned in the order.

Monitor Status

Poll GET /orders/{houdiniId} until statusLabel is FINISHED.

Integration Guide

Step 1: Get Tokens

There are two approaches for getting tokens. Choose the one that fits your integration:

Bulk Fetch + Cache
Token Search

Fetch all CEX-supported tokens once and store them in your backend database. This is the best approach for production integrations — it keeps your UI fast and avoids hammering the API.

Cache the token list in your backend database. Load on server startup or via a scheduled job, and refresh periodically (e.g., every 24 hours). Never call /tokens on every user request.

// Paginate through all CEX tokens and store in your DB
async function fetchAllCexTokens() {
  let page = 1;
  let allTokens = [];

  while (true) {
    const response = await fetch(
      `https://api-partner.houdiniswap.com/v2/tokens?hasCex=true&pageSize=20&page=${page}`,
      {
        headers: { 'Authorization': `${API_KEY}:${API_SECRET}` }
      }
    );

    const { tokens, totalPages } = await response.json();
    allTokens = allTokens.concat(tokens);

    if (page >= totalPages) break;
    page++;
  }

  return allTokens; // save to your DB
}

curl -X GET "https://api-partner.houdiniswap.com/v2/tokens?hasCex=true&pageSize=20&page=1" \
  -H "Authorization: your_api_key:your_api_secret"

Search for specific tokens by name or symbol on demand. Useful for lightweight integrations or when you want to let users search without prefetching everything.

// Search tokens as user types
async function searchTokens(query) {
  const params = new URLSearchParams({
    term: query,        // e.g. "bitcoin" or "ETH"
    hasCex: 'true',
    pageSize: '20',
    page: '1'
  });

  const response = await fetch(
    `https://api-partner.houdiniswap.com/v2/tokens?${params}`,
    {
      headers: { 'Authorization': `${API_KEY}:${API_SECRET}` }
    }
  );

  const { tokens } = await response.json();
  return tokens; // use token `id` in /quotes requests
}

curl -X GET "https://api-partner.houdiniswap.com/v2/tokens?term=bitcoin&hasCex=true&pageSize=20&page=1" \
  -H "Authorization: your_api_key:your_api_secret"

Step 2: Get Quotes

Call GET /quotes using token IDs (not symbols). The response includes quotes from all available providers across all swap types.

const params = new URLSearchParams({
  amount: '1',
  from: '6689b73ec90e45f3b3e51566',  // ETH token id from /tokens
  to:   '6689b73ec90e45f3b3e51558',  // USDC token id from /tokens
  types: 'standard',                 // only return standard quotes
});

const response = await fetch(
  `https://api-partner.houdiniswap.com/v2/quotes?${params}`,
  {
    headers: {
      'Authorization': `${API_KEY}:${API_SECRET}`,
      'x-user-ip': userIp,
      'x-user-agent': userAgent,
      'x-user-timezone': userTimezone
    }
  }
);

const { quotes } = await response.json();

// Pick a standard (single-hop CEX) quote
const standardQuote = quotes.find(q => q.type === 'standard');
console.log('Provider:', standardQuote.swapName);
console.log('Amount out:', standardQuote.amountOut);
console.log('ETA:', standardQuote.duration, 'minutes');
console.log('Quote ID:', standardQuote.quoteId); // needed for next step

curl -X GET "https://api-partner.houdiniswap.com/v2/quotes?amount=1&from=6689b73ec90e45f3b3e51566&to=6689b73ec90e45f3b3e51558&types=standard" \
  -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"

Quotes Response

{
  "quotes": [
    {
      "quoteId": "69af9e02f9c5affabcaccc14",
      "type": "standard",
      "swap": "cc",
      "swapName": "Coincraddle",
      "logoUrl": "https://api.houdiniswap.com/assets/logos/coincraddle.jpg",
      "amountIn": 1,
      "amountOut": 23.56,
      "amountOutUsd": 2019.09,
      "min": 0.098169,
      "max": 4688.581529,
      "duration": 30,
      "rewardsAvailable": true
    }
  ],
  "total": 5
}

Key Fields:

quoteId: Pass this to /exchanges to create the order
type: "standard" for single-hop CEX routing
swap / swapName: CEX provider code and human-readable name
amountOut: Output amount
duration: Estimated completion time in minutes
min / max: Valid input amount range

Step 3: Create Order

Pass the quoteId and destination address to POST /exchanges:

const response = await fetch('https://api-partner.houdiniswap.com/v2/exchanges', {
  method: 'POST',
  headers: {
    'Authorization': `${API_KEY}:${API_SECRET}`,
    'Content-Type': 'application/json',
    'x-user-ip': userIp,
    'x-user-agent': userAgent,
    'x-user-timezone': userTimezone
  },
  body: JSON.stringify({
    quoteId: '694cd4ef6ca7023b5e00a288',  // from /quotes
    addressTo: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
  })
});

const order = await response.json();
console.log('Order ID:', order.houdiniId);
console.log('Deposit to:', order.depositAddress);
console.log('Send amount:', order.inAmount, order.inSymbol);
console.log('Expires:', order.expires);

curl -X POST "https://api-partner.houdiniswap.com/v2/exchanges" \
  -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 '{
    "quoteId": "694cd4ef6ca7023b5e00a288",
    "addressTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

Order Response

{
  "houdiniId": "iBQMRX3xvXrFMGQi71ogo9",
  "created": "2025-12-25T06:13:46.673Z",
  "expires": "2025-12-25T06:43:46.673Z",
  "depositAddress": "0x7364a0b6c55004427a4a7c26355ce9c75ef56194",
  "receiverAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "anonymous": false,
  "status": -1,
  "statusLabel": "NEW",
  "inAmount": 1,
  "inSymbol": "ETH",
  "inStatus": 0,
  "inStatusLabel": "NEW",
  "outAmount": 2456.78,
  "outSymbol": "USDC",
  "outStatus": 0,
  "outStatusLabel": "NEW",
  "eta": 3,
  "inAmountUsd": 2937,
  "swapName": "Changelly",
  "inToken": {
    "id": "6689b73ec90e45f3b3e51566",
    "symbol": "ETH",
    "name": "Ethereum",
    "decimals": 18,
    "chain": "ethereum"
  },
  "outToken": {
    "id": "6689b73ec90e45f3b3e51558",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "chain": "ethereum"
  }
}

Key Response Fields:

houdiniId: Unique order identifier — use for status polling
depositAddress: Send input funds here
inAmount / inSymbol: Exact amount and token to send
expires: Deposit deadline (typically 30 minutes)
statusLabel: Human-readable order status
eta: Estimated completion time in minutes

Send exactly inAmount of inSymbol to depositAddress before expires.

Step 4: Send Deposit

After creating the order, send the input tokens to depositAddress. The status will advance automatically once the deposit is detected on-chain.

Step 5: Monitor Order Status

Poll GET /orders/{houdiniId} to track progress, or subscribe via the WebSocket API for real-time updates:

const response = await fetch(
  `https://api-partner.houdiniswap.com/v2/orders/${order.houdiniId}`,
  {
    headers: {
      'Authorization': `${API_KEY}:${API_SECRET}`,
      'x-user-ip': userIp,
      'x-user-agent': userAgent,
      'x-user-timezone': userTimezone
    }
  }
);

const status = await response.json();
console.log('Status:', status.statusLabel);
// WAITING     — awaiting deposit
// CONFIRMING  — deposit detected, awaiting confirmations
// EXCHANGING  — CEX is processing the swap
// FINISHED    — swap complete, funds sent
// FAILED      — swap failed
// EXPIRED     — deposit not received in time
// REFUNDED    — funds returned to sender

curl -X GET "https://api-partner.houdiniswap.com/v2/orders/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

NEW / WAITING
  ↓ Deposit sent and detected
CONFIRMING
  ↓ Blockchain confirmations received
EXCHANGING
  ↓ CEX processes the swap
FINISHED

Poll every 30 seconds. Standard swaps typically complete in 3–30 minutes. For real-time updates without polling, use the WebSocket API.

Best Practices

Token Fetching

Bulk fetch + cache: Paginate through /v2/tokens?hasCex=true on server startup and store in your DB. Refresh every 24 hours.
Search: Use ?term=<query> for on-demand token lookup — good for lightweight integrations.
Never call /tokens on every user request in production.

Transaction Monitoring

Poll /orders/{houdiniId} every 30 seconds
Store houdiniId for future reference and support lookups
Handle all statusLabel values: FINISHED, FAILED, EXPIRED, REFUNDED

Error Handling

Re-fetch quotes if quote is expired before calling /exchanges
Validate addressTo format before submitting
Implement retry logic with backoff for API calls

Security

Never expose API keys in frontend code
Use backend-only API integration
Validate all addresses before submitting
Store order records for audit trail

Common Issues

Swap Taking Longer Than Expected

Causes: Network congestion, CEX processing delays, slow block confirmations.Solution: Continue monitoring. Most swaps complete within 2× the estimated time.

Wrong Amount Deposited

Issue: User sent an incorrect amount to the deposit address.Solution: A partial refund may be processed. Contact support with the houdiniId.

Order Expired

Cause: Deposit was not received before the expires timestamp.Solution: Fetch a new quote and create a new order.

Status Stuck at CONFIRMING

Solution: Wait for blockchain confirmations. Check the deposit transaction on a block explorer and verify the correct amount was sent.

Example Repositories

See full working integrations on GitHub:

Next.js Example

Full Next.js integration showing standard, private, and DEX swap flows

Node.js Example

Backend Node.js integration with token fetching, quoting, and order tracking

Next Steps

Private Swaps

Multi-hop privacy swaps

DEX Swaps

On-chain decentralized swaps

Order Lifecycle

Understand all order statuses

Error Handling

Handle errors and edge cases

Overview

Getting Started

Core Concepts

Swap Flow Guides

Widget Integration

Troubleshooting

Partner Operations

Overview

How It Works

Integration Guide

Step 1: Get Tokens

Step 2: Get Quotes

Quotes Response

Step 3: Create Order

Order Response

Step 4: Send Deposit

Step 5: Monitor Order Status

Status Progression

Best Practices

Common Issues

Example Repositories

Next.js Example

Node.js Example

Next Steps

Private Swaps

DEX Swaps

Order Lifecycle

Error Handling

​Overview

​How It Works

​Integration Guide

​Step 1: Get Tokens

​Step 2: Get Quotes

​Quotes Response

​Step 3: Create Order

​Order Response

​Step 4: Send Deposit

​Step 5: Monitor Order Status

​Status Progression

​Best Practices

​Common Issues

​Example Repositories

Next.js Example

Node.js Example

​Next Steps

Private Swaps

DEX Swaps

Order Lifecycle

Error Handling

Overview

How It Works

Integration Guide

Step 1: Get Tokens

Step 2: Get Quotes

Quotes Response

Step 3: Create Order

Order Response

Step 4: Send Deposit

Step 5: Monitor Order Status

Status Progression

Best Practices

Common Issues

Example Repositories

Next Steps