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

# Private Swap (API v1)

> Complete guide to integrating multi-hop private swaps with maximum privacy

<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

Private swaps route through **multiple CEX hops** to provide maximum privacy. Like standard swaps, they use [CEX tokens](/developer-hub/core-concepts/tokens-networks#cex-tokens) from the `/tokens` endpoint. Optionally uses Monero (XMR) for enhanced anonymity. This breaks transaction trails across exchanges, providing enhanced anonymity without requiring wallet connections.

<Info>
  **Best For**: Users who prioritize privacy and are willing to accept longer completion times (15-45 minutes) for enhanced anonymity.
</Info>

## Key Features

<CardGroup cols={2}>
  <Card title="Multi-Hop Routing" icon="route">
    Routes through 2 exchanges to break transaction trail
  </Card>

  <Card title="Optional XMR Privacy Layer" icon="lock">
    Can use Monero for untraceable intermediate transactions
  </Card>

  <Card title="No Wallet Connection" icon="shield">
    No browser wallet or approvals required
  </Card>

  <Card title="Maximum Anonymity" icon="user-secret">
    No direct on-chain link between source and destination
  </Card>
</CardGroup>

## How It Works

Private swaps follow this multi-hop flow:

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

  <Step title="Request Private Quote">
    Get a quote with `anonymous: true` to request private routing
  </Step>

  <Step title="Create Swap Order">
    Submit swap with destination address
  </Step>

  <Step title="Multi-Hop Routing">
    Funds route through multiple CEXs (optionally via Monero)
  </Step>

  <Step title="Privacy Delivery">
    Final output sent to destination with broken trail
  </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 Private Quote

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

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Request a private quote
  const quote = await fetchFromHoudini('/quote', {
    amount: '1',
    from: 'ETH',         // Token symbol from /tokens
    to: 'SOL',           // Token symbol from /tokens
    anonymous: 'true',   // Enable private routing
    useXmr: 'false'      // System decides XMR usage
  });

  console.log('Route type:', quote.type);      // "private"
  console.log('Privacy hops:', quote.path);    // "se:cl" (multi-hop)
  console.log('XMR amount:', quote.xmrAmount); // Amount routed via Monero
  console.log('ETA:', quote.duration, 'minutes');
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api-partner.houdiniswap.com/quote?amount=1&from=ETH&to=SOL&anonymous=true&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": 23.6634,
  "amountIn": 1,
  "type": "private",
  "duration": 11,
  "path": "cl:qx",
  "xmrAmount": 38.231647970000004,
  "inQuoteId": "694cd4b5d924391f000561da",
  "outQuoteId": "694cd4b5d924391f000561e3",
  "quoteId": "694cd4b5d924391f000561e3",
  "amountOutUsd": 2893.323918,
  "rewardsAvailable": true
}
```

**Key Private Route Fields:**

* `type`: `"private"` indicating multi-hop routing
* `path`: Multi-hop CEX path (e.g., `"cl:qx"` = Changelly → Quickex)
* `xmrAmount`: Amount routed through Monero privacy layer
* `inQuoteId` / `outQuoteId`: Separate quotes for each hop
* `duration`: Estimated time to complete the exchange, longer completion time (15-45 min) due to multi-hop

### Step 3: Create Private Swap

Create the swap order using the `/exchange` endpoint:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create a private swap
  const swapRequest = {
    amount: 1,
    from: 'ETH',
    to: 'SOL',
    addressTo: '1nc1nerator11111111111111111111111111111111',
    receiverTag: '',
    anonymous: true,   // Enable private 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('Private 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": "SOL",
      "addressTo": "1nc1nerator11111111111111111111111111111111",
      "receiverTag": "",
      "anonymous": true,
      "ip": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "timezone": "America/New_York",
      "useXmr": false
    }'
  ```
</CodeGroup>

### Exchange Response

```json theme={null}
{
  "houdiniId": "bwc5iKVeeW5GiQpLHCm65w",
  "created": "2025-12-25T06:13:21.293Z",
  "senderAddress": "0xA2fC2BD472aB6FAF3176EBcBCaeeC7f95F563Ada",
  "receiverAddress": "1nc1nerator11111111111111111111111111111111",
  "anonymous": true,
  "status": 0,
  "inAmount": 1,
  "inSymbol": "ETH",
  "outAmount": 23.66258493,
  "outSymbol": "SOL",
  "eta": 28,
  "expires": "2025-12-25T06:43:21.293Z",
  "quote": {
    "path": "se:cl",
    "xmrAmount": 10393.30176114,
    "type": "private"
  },
  "inStatus": 0,
  "outStatus": 0
}
```

<Warning>
  **Critical**: Send exactly `inAmount` of `inSymbol` to the `senderAddress` within the expiration time (typically 30 minutes).
</Warning>

### Step 4: Monitor Swap Status

Poll the status endpoint to track the multi-hop progress:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Check swap status
  const status = await fetchFromHoudini('/status', {
    id: swap.houdiniId
  });

  console.log('Overall status:', status.status);
  console.log('Input leg:', status.inStatus);   // First hop status
  console.log('Output leg:', status.outStatus); // Second hop status
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api-partner.houdiniswap.com/status?id=bwc5iKVeeW5GiQpLHCm65w" \
    -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>

### Private Swap Status Progression

Private swaps have additional status stages for multi-hop routing:

```text theme={null}
0 (WAITING)
  ↓ User sends deposit
1 (CONFIRMING)
  ↓ Deposit confirmed
2 (EXCHANGING)
  ↓ First CEX hop processing
3 (ANONYMIZING)
  ↓ Routing through privacy layer (XMR)
  ↓ Second CEX hop processing
4 (COMPLETED)
```

**Status Fields:**

* `status`: Overall swap status (0-8)
* `inStatus`: First hop status
* `outStatus`: Second hop status (private swaps only)

<Tip>
  **Polling**: Check status every 30 seconds or more. Private swaps take 15-45 minutes due to multi-hop routing.
</Tip>

## Complete Example

For a complete, runnable Node.js example:

<Card title="Private Swap Example" icon="github" href="https://github.com/HoudiniSwap/houdini-api-examples/blob/main/examples/private-swap-example.ts">
  Complete private swap script with multi-hop status tracking
</Card>

## Best Practices

<AccordionGroup>
  <Accordion title="Set Proper Expectations" icon="info">
    Clearly communicate the 15-45 minute completion time for private swaps. Users should understand they're trading speed for privacy.
  </Accordion>

  <Accordion title="Privacy Education" icon="book">
    Explain how multi-hop routing provides privacy benefits. Help users understand what they're getting.
  </Accordion>

  <Accordion title="Handle Long Waits" icon="clock">
    Implement proper loading states and progress indicators. Private swaps take longer due to multiple hops.
  </Accordion>
</AccordionGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Longer Than Expected Completion">
    **Cause**: Multi-hop routing through 2 exchanges takes longer

    **Solution**: This is normal for private swaps. Monitor `inStatus` and `outStatus` to see which hop is processing.
  </Accordion>

  <Accordion title="Privacy Questions">
    **Question**: "How private is this really?"

    **Answer**: Private swaps break the transaction trail by routing through multiple exchanges. When XMR routing is used, it adds an untraceable intermediate step. However, this is not absolute anonymity - compliance checks still apply.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="DEX Swap" icon="arrows-rotate" href="/developer-hub/swap-flows/dex-swap">
    On-chain decentralized swaps
  </Card>

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

  <Card title="Routing Types" icon="route" href="/developer-hub/core-concepts/routing-types">
    Learn about private vs standard routing
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.