Skip to main content

​
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

​
Private Swap Flow

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

​
Status Definitions

​
Active States

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

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
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
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
Status Code: 7Description: Swap failed and original funds returned to user.What’s Happening:
  • Original deposit being returned to refund address
  • Sent to refundAddress provided when creating order
  • May be partial refund if network fees deducted
  • Refund transaction confirmed on-chain
Integrator Action:
  • Display refund status
  • Provide support contact for questions
  • Stop status polling
This State is Final: ✅ Yes
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