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

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

```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

<AccordionGroup>
  <Accordion title="0 - WAITING" icon="clock">
    **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>

  <Accordion title="1 - CONFIRMING" icon="check-circle">
    **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>

  <Accordion title="2 - EXCHANGING" icon="arrows-rotate">
    **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>

  <Accordion title="3 - ANONYMIZING" icon="user-secret">
    **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 Integration Guide](/developer-hub/swap-flows/private-swap).
    </Tip>
  </Accordion>
</AccordionGroup>

### Terminal States

<AccordionGroup>
  <Accordion title="4 - COMPLETED" icon="circle-check">
    **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>

  <Accordion title="5 - EXPIRED" icon="hourglass-end">
    **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>

  <Accordion title="6 - FAILED" icon="circle-xmark">
    **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>

  <Accordion title="7 - REFUNDED" icon="rotate-left">
    **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>

  <Accordion title="8 - DELETED" icon="ban">
    **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
  </Accordion>
</AccordionGroup>

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Private Swap Guide" icon="user-secret" href="/developer-hub/swap-flows/private-swap">
    Complete integration guide for private swaps
  </Card>

  <Card title="Standard Swap Guide" icon="bolt" href="/developer-hub/swap-flows/standard-swap">
    Fast single-hop CEX swap integration
  </Card>

  <Card title="DEX Swap Guide" icon="arrows-rotate" href="/developer-hub/swap-flows/dex-swap">
    On-chain decentralized swap integration
  </Card>

  <Card title="API v2 Reference" icon="code" href="/api-reference">
    Detailed status endpoint documentation
  </Card>
</CardGroup>