Order Status

Check the status and details of a cross-chain order

Overview

The getOrderStatus method retrieves comprehensive information about an order’s current state, including its lifecycle status, validation state, fill information, and auction details.

Method Signature

async getOrderStatus(orderHash: string): Promise<OrderStatusResponse>

Parameters

orderHash · string · required

The unique identifier of the order. Hex string for EVM orders (e.g., 0x...), base58 string for Solana orders

Returns

OrderStatusResponse · object

orderHash · string

The order’s unique identifier

status · OrderStatus

Current order status: pending, executed, expired, cancelled, refunding, or refunded

validation · ValidationStatus

Validation state: valid, not-enough-balance, not-enough-allowance, invalid-signature, etc.

points · AuctionPoint[]

Auction curve points defining the price over time

approximateTakingAmount · string

Estimated destination token amount at current auction price

positiveSurplus · string

Positive surplus earned by the maker

fills · Fill[]

Array of fill objects for this order

status · FillStatus

Fill status: pending, executed, refunding, or refunded

txHash · string

Transaction hash of the fill

filledMakerAmount · string

Amount filled on the source chain

filledAuctionTakerAmount · string

Amount filled on the destination chain

escrowEvents · EscrowEventData[]

Events related to the escrow

transactionHash · string

Transaction hash of the event

escrow · string

Escrow contract address

side · EscrowEventSide

Which chain: src or dst

action · EscrowEventAction

Event type: src_escrow_created, dst_escrow_created, withdrawn, funds_rescued, or escrow_cancelled

blockTimestamp · number

Unix timestamp in milliseconds

auctionStartDate · number

Unix timestamp in seconds when the auction started

auctionDuration · number

Auction duration in seconds

initialRateBump · number

Initial rate bump percentage for the auction

createdAt · number

Unix timestamp in milliseconds when the order was created

srcTokenPriceUsd · string | null

USD price of the source token

dstTokenPriceUsd · string | null

USD price of the destination token

cancelTx · string | null

Cancellation transaction hash if the order was cancelled

dstChainId · SupportedChain

Destination chain ID

cancelable · boolean

Whether the order can be cancelled

takerAsset · string

Destination token address

timeLocks · string

Hex encoded time lock parameters (with 0x prefix)

srcChainId · SupportedChain

Source chain ID (EVM or Solana)

order · LimitOrderV4Struct | SolanaOrderJSON

The order data structure (format depends on source chain)

extension · string

Extension data (EVM orders only)

Order Lifecycle States

OrderStatus Enum

enum OrderStatus {
  Pending = 'pending',      // Order is active and awaiting fills
  Executed = 'executed',    // Order has been successfully filled
  Expired = 'expired',      // Order deadline has passed
  Cancelled = 'cancelled',  // Order was cancelled by maker or resolver
  Refunding = 'refunding',  // Refund process initiated
  Refunded = 'refunded'     // Funds have been refunded
}

ValidationStatus Enum

enum ValidationStatus {
  Valid = 'valid',
  OrderPredicateReturnedFalse = 'order-predicate-returned-false',
  NotEnoughBalance = 'not-enough-balance',
  NotEnoughAllowance = 'not-enough-allowance',
  InvalidPermitSignature = 'invalid-permit-signature',
  InvalidSignature = 'invalid-signature',
  UnknownFailure = 'unknown-failure'
  // ... additional validation states
}

FillStatus Enum

enum FillStatus {
  Pending = 'pending',      // Fill initiated but not completed
  Executed = 'executed',    // Fill completed successfully
  Refunding = 'refunding',  // Fill being refunded
  Refunded = 'refunded'     // Fill has been refunded
}

Example Usage

Basic Status Check

import { SDK } from '@1inch/cross-chain-sdk'

const sdk = new SDK({
  url: 'https://api.1inch.dev/fusion-plus',
  authKey: 'your-auth-key'
})

const orderHash = '0x1234...'
const status = await sdk.getOrderStatus(orderHash)

console.log('Order Status:', status.status)
console.log('Validation:', status.validation)
console.log('Fills:', status.fills.length)

Check Fill Details

const status = await sdk.getOrderStatus(orderHash)

if (status.status === OrderStatus.Executed) {
  status.fills.forEach((fill, index) => {
    console.log(`Fill ${index + 1}:`)
    console.log('  Status:', fill.status)
    console.log('  Tx Hash:', fill.txHash)
    console.log('  Maker Amount:', fill.filledMakerAmount)
    console.log('  Taker Amount:', fill.filledAuctionTakerAmount)
    
    fill.escrowEvents.forEach(event => {
      console.log(`  Event: ${event.action} on ${event.side} chain`)
      console.log(`    Tx: ${event.transactionHash}`)
    })
  })
}

Monitor Auction

const status = await sdk.getOrderStatus(orderHash)

// Check auction timing
const now = Math.floor(Date.now() / 1000)
const auctionEnd = status.auctionStartDate + status.auctionDuration

if (now < status.auctionStartDate) {
  console.log('Auction has not started yet')
} else if (now < auctionEnd) {
  const elapsed = now - status.auctionStartDate
  const progress = (elapsed / status.auctionDuration) * 100
  console.log(`Auction ${progress.toFixed(1)}% complete`)
  console.log('Current estimated amount:', status.approximateTakingAmount)
} else {
  console.log('Auction has ended')
}

Validation Check

const status = await sdk.getOrderStatus(orderHash)

switch (status.validation) {
  case ValidationStatus.Valid:
    console.log('Order is valid and fillable')
    break
  case ValidationStatus.NotEnoughBalance:
    console.log('Maker has insufficient balance')
    break
  case ValidationStatus.NotEnoughAllowance:
    console.log('Maker has not approved tokens')
    break
  case ValidationStatus.InvalidSignature:
    console.log('Order signature is invalid')
    break
  default:
    console.log('Order validation failed:', status.validation)
}

Status Polling Pattern

For monitoring order progress, implement polling with exponential backoff:

async function pollOrderStatus(
  sdk: SDK,
  orderHash: string,
  maxAttempts = 60,
  initialDelay = 2000
): Promise<OrderStatusResponse> {
  let attempt = 0
  let delay = initialDelay

  while (attempt < maxAttempts) {
    const status = await sdk.getOrderStatus(orderHash)

    // Check if order reached a final state
    if (
      status.status === OrderStatus.Executed ||
      status.status === OrderStatus.Cancelled ||
      status.status === OrderStatus.Expired ||
      status.status === OrderStatus.Refunded
    ) {
      return status
    }

    // Wait before next poll
    await new Promise(resolve => setTimeout(resolve, delay))
    
    // Exponential backoff (cap at 30 seconds)
    delay = Math.min(delay * 1.5, 30000)
    attempt++
  }

  throw new Error('Order status polling timeout')
}

// Usage
try {
  const finalStatus = await pollOrderStatus(sdk, orderHash)
  console.log('Order completed with status:', finalStatus.status)
} catch (error) {
  console.error('Polling failed:', error)
}

Advanced Polling with Event Filtering

async function waitForEscrowEvent(
  sdk: SDK,
  orderHash: string,
  targetAction: EscrowEventAction,
  targetSide: EscrowEventSide
): Promise<EscrowEventData> {
  const pollInterval = 3000
  const maxWait = 300000 // 5 minutes
  const startTime = Date.now()

  while (Date.now() - startTime < maxWait) {
    const status = await sdk.getOrderStatus(orderHash)

    for (const fill of status.fills) {
      const event = fill.escrowEvents.find(
        e => e.action === targetAction && e.side === targetSide
      )
      if (event) {
        return event
      }
    }

    await new Promise(resolve => setTimeout(resolve, pollInterval))
  }

  throw new Error(`Event ${targetAction} on ${targetSide} not found`)
}

// Wait for source escrow creation
const srcEscrowEvent = await waitForEscrowEvent(
  sdk,
  orderHash,
  EscrowEventAction.SrcEscrowCreated,
  EscrowEventSide.Src
)

console.log('Source escrow created:', srcEscrowEvent.transactionHash)

Error Handling

try {
  const status = await sdk.getOrderStatus(orderHash)
  
  if (status.status === OrderStatus.Cancelled) {
    console.log('Order was cancelled')
    if (status.cancelTx) {
      console.log('Cancel transaction:', status.cancelTx)
    }
  }
} catch (error) {
  if (error.response?.status === 404) {
    console.error('Order not found')
  } else {
    console.error('Failed to get order status:', error)
  }
}

Notes

• Order hash format differs by chain: hex (EVM) vs base58 (Solana)
• approximateTakingAmount changes during the auction based on the current time
• Escrow events track the complete cross-chain flow
• Multiple fills are possible for orders with multipleFillsAllowed: true
• Polling frequency should be adjusted based on expected fill times
• The validation field helps diagnose why orders aren’t being filled
• Price data (srcTokenPriceUsd, dstTokenPriceUsd) may be null for some tokens

Related Methods

• Submit Order - Submit orders before checking status
• Get Active Orders - List all active orders
• Get Orders By Maker - Get all orders for an address