> ## 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.

# Standard Swap Flow

> Integrate standard swaps with single-hop CEX routing for fast execution

## Overview

Standard swaps use a single centralized exchange (CEX) for routing, providing the fastest execution times. These swaps use [CEX tokens](/developer-hub/core-concepts/tokens-networks#cex-tokens) from the `/tokens` endpoint and are routed directly through one exchange, completing in 3-30 minutes on average.

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

## How It Works

Standard swaps follow this flow:

<Steps>
  <Step title="Get Supported Assets">
    Fetch available tokens from `/tokens`
  </Step>

  <Step title="Request Quote">
    Get a quote with `anonymous: false` for standard routing
  </Step>

  <Step title="Create Order">
    Submit swap order with user's destination address
  </Step>

  <Step title="Single CEX Routing">
    Funds are routed through one centralized exchange
  </Step>

  <Step title="Receive Funds">
    Output tokens sent directly to destination address
  </Step>
</Steps>

## Integration Guide

### Step 1: Get Supported Assets

Before requesting a quote, fetch the available tokens. Learn more about [CEX tokens](/developer-hub/core-concepts/tokens-networks#cex-tokens).

<Warning>
  **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)
</Warning>

<CodeGroup>
  ```javascript JavaScript theme={null}
  const tokens = await fetchFromHoudini('/tokens');

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

  ```bash cURL theme={null}
  # 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"
  ```
</CodeGroup>

### Step 2: Request Quote

Request a quote with `anonymous: false` for standard routing. Use token symbols from the [`/tokens`](/developer-hub/core-concepts/tokens-networks#fetch-cex-tokens) endpoint:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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');
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

### Quote Response

```json theme={null}
{
  "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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

### Exchange Response

```json theme={null}
{
  "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

<Warning>
  **Important**: Send exactly `inAmount` of `inSymbol` to the `senderAddress` within the expiration time.
</Warning>

### Step 4: Send Deposit

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

<Steps>
  <Step title="Get Deposit Address">
    Use `senderAddress` from the exchange response
  </Step>

  <Step title="Send Exact Amount">
    Send exactly `inAmount` of the source token
  </Step>

  <Step title="Wait for Confirmations">
    Status will change from `0` (WAITING) to `1` (CONFIRMING)
  </Step>
</Steps>

### Step 5: Monitor Status

Poll the status endpoint to track swap progress:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

### Status Progression

Standard swaps follow this status flow:

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

<Tip>
  **Polling**: Check status every 30 seconds. Standard swaps typically complete in 3-30 minutes.
</Tip>

## Complete Example

For a complete, runnable Node.js example:

<Card title="Standard Swap Example" icon="github" href="https://github.com/HoudiniSwap/houdini-api-examples/blob/main/examples/standard-swap-example.ts">
  Complete standard swap script with status monitoring
</Card>

## Best Practices

<AccordionGroup>
  <Accordion title="Transaction Monitoring" icon="chart-line">
    * Poll status every 30 seconds
    * Handle all status codes properly (0-8)
    * Store `houdiniId` for future reference
  </Accordion>

  <Accordion title="Error Handling" icon="triangle-exclamation">
    * 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)
  </Accordion>

  <Accordion title="User Experience" icon="users">
    * Show clear deposit instructions
    * Display countdown for quote expiration
    * Provide CEX provider information
    * Show estimated completion time
    * Display transaction progress clearly
  </Accordion>

  <Accordion title="Security" icon="shield">
    * 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
  </Accordion>
</AccordionGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Wrong Amount Deposited">
    **Issue**: User sent incorrect amount to deposit address

    **Solution**:

    * Partial refund may be processed
    * Contact support with `houdiniId`
    * Always send exact `inAmount`
  </Accordion>

  <Accordion title="Quote Expired">
    **Cause**: Took too long to deposit after creating swap

    **Solution**: Create new swap with fresh quote. Quotes expire after 30 minutes.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Private Swaps" icon="lock" href="/developer-hub/swap-flows/private-swap">
    Learn about private multi-hop swaps
  </Card>

  <Card title="DEX Swaps" icon="arrows-rotate" href="/developer-hub/swap-flows/dex-swap">
    Integrate on-chain DEX swaps
  </Card>

  <Card title="Order Lifecycle" icon="rotate" href="/developer-hub/core-concepts/order-lifecycle">
    Understand swap status progression
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/developer-hub/troubleshooting/errors">
    Handle errors and edge cases
  </Card>
</CardGroup>