> ## Documentation Index
> Fetch the complete documentation index at: https://docs.houdini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Lifecycle

> Understanding order states, status transitions, and lifecycle management

## What is an Order?

An **order** represents a single swap transaction in Houdini's system. Each order:

* Has a unique `houdiniId` for tracking
* Progresses through numeric status codes (0-8)
* Contains swap details (tokens, amounts, addresses)
* Tracks execution progress and completion

## Status Code Overview

Houdini API returns numeric status codes to represent the current state of an order:

```javascript theme={null}
const ORDER_STATUS = {
  WAITING: 0,      // Waiting for deposit
  CONFIRMING: 1,   // Deposit being confirmed
  EXCHANGING: 2,   // Swap executing
  ANONYMIZING: 3,  // Private swap routing (private swaps only)
  COMPLETED: 4,    // Swap completed successfully
  EXPIRED: 5,      // Order expired before deposit
  FAILED: 6,       // Swap failed
  REFUNDED: 7,     // Funds refunded to user
  DELETED: 8       // Order cancelled/deleted
};
```

## Order Status Flow

### Standard Swap Flow

> [!NOTE]
>
> Fixed rate swaps follow the same status flow as standard swaps. The only difference is the `refundAddress` field — if the swap fails, the order moves to `REFUNDED` and funds may be returned there, depending on the provider.

```mermaid theme={null}
stateDiagram-v2
    [*] --> 0_WAITING
    0_WAITING --> 1_CONFIRMING: Deposit received
    0_WAITING --> 5_EXPIRED: Time expired
    1_CONFIRMING --> 2_EXCHANGING: Deposit confirmed
    2_EXCHANGING --> 4_COMPLETED: Swap successful
    2_EXCHANGING --> 6_FAILED: Swap error
    6_FAILED --> 7_REFUNDED: Refund processed
    6_FAILED --> 8_DELETED: Order cancelled
    4_COMPLETED --> [*]
    5_EXPIRED --> [*]
    7_REFUNDED --> [*]
    8_DELETED --> [*]
```

### Private Swap Flow

Private swaps include an additional `ANONYMIZING` (3) status for multi-hop routing:

```mermaid theme={null}
stateDiagram-v2
    [*] --> 0_WAITING
    0_WAITING --> 1_CONFIRMING: Deposit received
    0_WAITING --> 5_EXPIRED: Time expired
    1_CONFIRMING --> 2_EXCHANGING: Deposit confirmed
    2_EXCHANGING --> 3_ANONYMIZING: First hop complete
    3_ANONYMIZING --> 4_COMPLETED: Privacy routing complete
    3_ANONYMIZING --> 6_FAILED: Routing error
    6_FAILED --> 7_REFUNDED: Refund processed
    4_COMPLETED --> [*]
    5_EXPIRED --> [*]
    7_REFUNDED --> [*]
```

## Status Definitions

### Active States

> [accordion] 0 - WAITING
>
> **Status Code**: `0`
>
> **Description**: Order created, waiting for user to send deposit.
>
> **What's Happening**:
>
> * Deposit address generated and active
> * Monitoring blockchain for incoming transaction
> * Quote validity timer counting down
> * Order will expire if no deposit received in time
>
> **Integrator Action**:
>
> * **Display deposit address prominently**
> * Show exact amount to send
> * Show correct network/chain
> * Display expiration countdown
> * Optionally show QR code for easy deposit
>
> **Typical Duration**: User-dependent (0-30 minutes)
>
> **Next States**: `1` (CONFIRMING), `5` (EXPIRED)

> [accordion] 1 - CONFIRMING
>
> **Status Code**: `1`
>
> **Description**: Deposit received, waiting for blockchain confirmations.
>
> **What's Happening**:
>
> * Deposit transaction detected on-chain
> * Waiting for required block confirmations
> * Once confirmed, swap will begin execution
>
> **Integrator Action**:
>
> * Update UI to show deposit detected
> * Display "Confirming deposit..." message
> * Show confirmation progress if available
> * Continue polling status
>
> **Typical Duration**: 30 seconds - 5 minutes (chain-dependent)
>
> **Next States**: `2` (EXCHANGING)

> [accordion] 2 - EXCHANGING
>
> **Status Code**: `2`
>
> **Description**: Deposit confirmed, swap actively executing.
>
> **What's Happening**:
>
> * **DEX Routes**: On-chain swap transaction being confirmed
> * **Standard Swaps**: Single exchange processing
> * **Private Swaps**: First hop of multi-hop route executing
>
> **Integrator Action**:
>
> * Show active progress indicator
> * Poll status regularly
>
> **Typical Duration**:
>
> * Standard: 3-30 minutes
> * Private: Moves to status `3` (ANONYMIZING)
> * DEX: 30 seconds - 15 minutes
>
> **Next States**: `3` (ANONYMIZING - private only), `4` (COMPLETED), `6` (FAILED)

> [accordion] 3 - ANONYMIZING
>
> **Status Code**: `3`
>
> **Description**: Private swap routing through privacy layer (private swaps only).
>
> **What's Happening**:
>
> * First exchange hop completed
> * Routing through privacy layer (potentially via Monero)
> * Second exchange hop executing
> * Breaking transaction trail across multiple venues
>
> **Integrator Action**:
>
> * Show multi-hop progress indicator
> * Continue polling
>
> **Typical Duration**: 10-40 minutes (multi-hop routing)
>
> **Next States**: `4` (COMPLETED), `6` (FAILED)
>
> **Only Appears In**: Private swaps with `anonymous: true`
>
> > [!TIP]
> >
> > Learn more about private swaps in the [Private Swap guide](https://docs.houdini.com/developer-hub/swap-flows/private-swap.md).

### Terminal States

> [accordion] 4 - COMPLETED
>
> **Status Code**: `4`
>
> **Description**: Swap successfully completed, funds delivered to destination.
>
> **What's Happening**:
>
> * Destination tokens sent to user's `addressTo`
> * Transaction confirmed on destination chain
> * Order fully settled and complete
>
> **Integrator Action**:
>
> * **Display success message prominently**
> * Show final amount received
> * Provide destination transaction hash
> * Link to blockchain explorer
> * **Stop status polling**
>
> **This State is Final**: ✅ Yes

> [accordion] 5 - EXPIRED
>
> **Status Code**: `5`
>
> **Description**: Order expired before deposit was received.
>
> **What's Happening**:
>
> * Quote validity window passed (typically 30 minutes)
> * Deposit address deactivated
> * No deposit transaction detected
> * Order automatically expired by system
>
> **Integrator Action**:
>
> * Inform user order expired
> * Explain they need to create a new order for a fresh quote
> * **Important**: If user claims they sent funds to expired address, escalate to support immediately
> * **Stop status polling**
>
> **This State is Final**: ✅ Yes
>
> **Common Cause**: User took too long to send deposit

> [accordion] 6 - FAILED
>
> **Status Code**: `6`
>
> **Description**: Swap encountered an error and could not complete.
>
> **What's Happening**:
>
> * CEX unavailable, insufficient liquidity, or technical error
> * Deposit was received but swap execution failed
> * System determining if refund is possible
> * Error details available in response
>
> **Integrator Action**:
>
> * Display error message from `message` field
> * Show refund status if available
> * Provide customer support contact
>
> **This State is Final**: ✅ Yes

> [accordion] 7 - REFUNDED
>
> **Status Code**: `7`
>
> **Description**: Swap failed and original funds returned to user.
>
> **What's Happening**:
>
> * Swap failed; system attempting to return original deposit
> * Sent to `refundAddress` if provided when creating the order
> * May be partial refund if network fees deducted
> * **Note**: Refund behavior depends on the provider — some providers automatically return funds, others require the user to contact customer support
>
> **Integrator Action**:
>
> * Display refund status
> * Provide support contact for questions
> * **Stop status polling**
>
> **This State is Final**: ✅ Yes

> [accordion] 8 - DELETED
>
> **Status Code**: `8`
>
> **Description**: Order was automatically deleted from the system.
>
> **What's Happening**:
>
> * Order was automatically removed after a retention period
> * This is a normal cleanup process for old orders
> * No issues or problems with the order - it completed its lifecycle
> * Historical data cleanup to maintain system performance
>
> **Integrator Action**:
>
> * Inform user that order data is no longer available
> * This typically occurs for orders that are several hours old
> * **Stop status polling**
>
> **This State is Final**: ✅ Yes

## InStatus and OutStatus Tracking (Optional)

All swap types (Standard, DEX, and Private) provide additional status fields to track detailed progress:

### Status Fields

* **`status`**: Overall order status (0-8) - applies to all swap types
* **`inStatus`**: Input leg status - tracks the progress of receiving and processing the deposit
* **`outStatus`**: Output leg status - only used in **private swaps** to track the second hop

### Standard and DEX Swaps (Single Hop)

For standard CEX swaps and DEX swaps, only `inStatus` is used to track progress:

```javascript theme={null}
const SWAP_STATUS_STANDARD_AND_DEX = {
  IN_STATUS_1: 1,  // Waiting for deposit
  IN_STATUS_2: 2,  // Deposit detected on-chain
  IN_STATUS_3: 3,  // Swapping (executing trade)
  IN_STATUS_4: 4,  // Sending output to destination
  IN_STATUS_5: 5   // Completed (swap finished)
};
```

**Example - Standard Swap Progress**:

```json theme={null}
{
  "houdiniId": "abc123",
  "status": 2,      // EXCHANGING
  "inStatus": 3,    // Currently swapping
}
```

### Private Swaps (Multi-Hop)

Private swaps use **both** `inStatus` and `outStatus` to track each hop separately:

```javascript theme={null}
const SWAP_STATUS_PRIVATE = {
  // First hop (input leg)
  IN_STATUS_1: 1,   // Waiting for deposit
  IN_STATUS_2: 2,   // Deposit detected on-chain
  IN_STATUS_3: 3,   // Swapping on first exchange
  IN_STATUS_4: 4,   // Sending to privacy layer/second exchange

  // Second hop (output leg) - only for private swaps
  OUT_STATUS_2: 2,  // Exchange - receiving from first hop
  OUT_STATUS_3: 3,  // Swapping on second exchange
  OUT_STATUS_4: 4,  // Sending final output to destination
  OUT_STATUS_5: 5   // Completed - final delivery done
};
```

**Example - Private Swap in Progress**:

```json theme={null}
{
  "houdiniId": "bwc5iKVeeW5GiQpLHCm65w",
  "status": 3,        // ANONYMIZING (overall status)
  "inStatus": 4,      // First hop: sending to second exchange
  "outStatus": 2,     // Second hop: receiving from first hop
}
```

> [!NOTE]
>
> **Key Difference**: Standard and DEX swaps only use `inStatus` (single hop), while private swaps use both `inStatus` and `outStatus` (multi-hop) to track each exchange leg separately.

## Next Steps

> [card] [Private Swap](https://docs.houdini.com/developer-hub/swap-flows/private-swap.md)
>
> Complete integration guide for private swaps

> [card] [Standard Swap](https://docs.houdini.com/developer-hub/swap-flows/standard-swap.md)
>
> Fast single-hop CEX swap integration

> [card] [DEX Swap](https://docs.houdini.com/developer-hub/swap-flows/dex-swap.md)
>
> On-chain decentralized swap integration

> [card] [API v2 Reference](https://docs.houdini.com/api-reference)
>
> Detailed status endpoint documentation


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