Order Lifecycle

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:

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

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.

Private Swap Flow

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

Status Definitions

Active States

0 - WAITING

Status Code: 0Description: 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)

1 - CONFIRMING

Status Code: 1Description: 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)

2 - EXCHANGING

Status Code: 2Description: 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)

3 - ANONYMIZING

Status Code: 3Description: 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

Learn more about private swaps in the Private Swap Integration Guide.

Terminal States

4 - COMPLETED

Status Code: 4Description: 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

5 - EXPIRED

Status Code: 5Description: 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: ✅ YesCommon Cause: User took too long to send deposit

6 - FAILED

Status Code: 6Description: 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

7 - REFUNDED

Status Code: 7Description: 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

8 - DELETED

Status Code: 8Description: 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:

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:

{
  "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:

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:

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

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

Private Swap Guide

Complete integration guide for private swaps

Standard Swap Guide

Fast single-hop CEX swap integration

DEX Swap Guide

On-chain decentralized swap integration

API v2 Reference

Detailed status endpoint documentation

Overview

Getting Started

Core Concepts

Swap Flow Guides

Widget Integration

Troubleshooting

Partner Operations

What is an Order?

Status Code Overview

Order Status Flow

Standard Swap Flow

Private Swap Flow

Status Definitions

Active States

Terminal States

InStatus and OutStatus Tracking (Optional)

Status Fields

Standard and DEX Swaps (Single Hop)

Private Swaps (Multi-Hop)

Next Steps

Private Swap Guide

Standard Swap Guide

DEX Swap Guide

API v2 Reference

​What is an Order?

​Status Code Overview

​Order Status Flow

​Standard Swap Flow

​Private Swap Flow

​Status Definitions

​Active States

​Terminal States

​InStatus and OutStatus Tracking (Optional)

​Status Fields

​Standard and DEX Swaps (Single Hop)

​Private Swaps (Multi-Hop)

​Next Steps

Private Swap Guide

Standard Swap Guide

DEX Swap Guide

API v2 Reference

What is an Order?

Status Code Overview

Order Status Flow

Standard Swap Flow

Private Swap Flow

Status Definitions

Active States

Terminal States

InStatus and OutStatus Tracking (Optional)

Status Fields

Standard and DEX Swaps (Single Hop)

Private Swaps (Multi-Hop)

Next Steps