> ## 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 (API v1)

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

<Danger>
  Deprecation of the REST v1 swap endpoints begins on September 30, 2026. Please migrate to the Partner API v2. Dashboard and authentication endpoints remain on v1 GraphQL and are not affected. [Read the migration guide](https://docs.houdiniswap.com/migration/v1-to-v2)
</Danger>

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

```text theme={null}
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 Swap" icon="lock" href="/developer-hub/swap-flows/private-swap">
    Learn about private multi-hop swaps
  </Card>

  <Card title="DEX Swap" 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>