Order Tracking and Monitoring

Learn how to track cross-chain order status and manage secret submission

Order tracking is essential for monitoring the progress of cross-chain swaps and ensuring secrets are submitted at the right time. This guide covers the order lifecycle, status checking, and secret management.

Order Lifecycle

Cross-chain orders progress through several states:

Order States

Status	Description	Action Required
Created	Order created but not yet submitted	Submit order
Pending	Order submitted, waiting for resolver	Monitor for escrows
PartiallyFilled	Some fills completed	Submit remaining secrets
Executed	All fills completed successfully	None - swap complete
Expired	Order expired before completion	Check for refunds
Refunded	Order refunded to user	None - funds returned

Getting Order Status

Use getOrderStatus() to check the current state of an order:

const status = await sdk.getOrderStatus(orderHash)

console.log('Order status:', status.status)
console.log('Fills:', status.fills)

Status Response Structure

interface OrderStatusResponse {
    status: OrderStatus
    orderHash: string
    fills: Fill[]
    createdAt: number
    // ... other fields
}

enum OrderStatus {
    Created = 'created',
    Pending = 'pending',
    PartiallyFilled = 'partially-filled',
    Executed = 'executed',
    Expired = 'expired',
    Refunded = 'refunded'
}

Secret Management

Secrets are the cryptographic keys that allow resolvers to complete the swap. You must submit secrets when escrows are ready.

Checking for Ready Escrows

Use getReadyToAcceptSecretFills() to check which secrets need to be submitted:

const secretsToShare = await sdk.getReadyToAcceptSecretFills(orderHash)

if (secretsToShare.fills.length > 0) {
    console.log(`${secretsToShare.fills.length} escrows ready for secrets`)
    
    for (const { idx } of secretsToShare.fills) {
        console.log(`Secret ${idx} needed`)
    }
}

Submitting Secrets

Once escrows are deployed, submit the corresponding secrets:

for (const { idx } of secretsToShare.fills) {
    // Verify escrow details before submitting
    await sdk.submitSecret(orderHash, secrets[idx])
    console.log(`Submitted secret ${idx}`)
}

Always verify escrow addresses and parameters before submitting secrets. The getReadyToAcceptSecretFills() response includes escrow details for verification.

Complete Monitoring Loop

Here’s a complete example of monitoring an order and submitting secrets:

Basic Monitoring Loop

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

async function monitorOrder(
    sdk: SDK,
    orderHash: string,
    secrets: string[]
): Promise<void> {
    const alreadyShared = new Set<number>()

    while (true) {
        // Check for ready escrows
        const secretsToShare = await sdk.getReadyToAcceptSecretFills(orderHash)

        // Submit new secrets
        if (secretsToShare.fills.length) {
            for (const { idx } of secretsToShare.fills) {
                if (!alreadyShared.has(idx)) {
                    // It is your responsibility to verify escrow addresses
                    await sdk.submitSecret(orderHash, secrets[idx])
                    alreadyShared.add(idx)
                    console.log(`Submitted secret ${idx}`)
                }
            }
        }

        // Check order status
        const { status } = await sdk.getOrderStatus(orderHash)
        console.log('Current status:', status)

        // Exit when order is complete
        if (
            status === OrderStatus.Executed ||
            status === OrderStatus.Expired ||
            status === OrderStatus.Refunded
        ) {
            console.log('Order completed with status:', status)
            break
        }

        // Wait before next check
        await new Promise(resolve => setTimeout(resolve, 1000))
    }
}

// Usage
await monitorOrder(sdk, orderHash, secrets)

Monitoring with Solana Orders

For Solana orders, the monitoring process is the same, but use setTimeout from node:timers/promises:

import { setTimeout } from 'node:timers/promises'

const alreadyShared = new Set<number>()

while (true) {
    const readyToAcceptSecretes = await sdk.getReadyToAcceptSecretFills(orderHash)
    const idxes = readyToAcceptSecretes.fills.map((f) => f.idx)

    for (const idx of idxes) {
        if (!alreadyShared.has(idx)) {
            await sdk.submitSecret(orderHash, secrets[idx])
            alreadyShared.add(idx)
            console.log('submitted secret', secrets[idx])
        }
    }

    const { status } = await sdk.getOrderStatus(orderHash)

    if (
        status === OrderStatus.Executed ||
        status === OrderStatus.Expired ||
        status === OrderStatus.Refunded
    ) {
        break
    }

    await setTimeout(5000) // 5 second interval for Solana
}

WebSocket Tracking (Optional)

For real-time updates, you can use the WebSocket API:

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

const wsClient = new WSClient({
    url: 'wss://api.1inch.com/fusion-plus/ws',
    authKey: 'your-auth-key'
})

// Subscribe to order updates
wsClient.onOrderUpdate(orderHash, (update) => {
    console.log('Order update:', update)
    
    if (update.status === OrderStatus.Executed) {
        console.log('Order executed!')
    }
})

// Subscribe to secret requests
wsClient.onSecretRequest(orderHash, async (request) => {
    console.log('Secret requested for fill:', request.fillIndex)
    await sdk.submitSecret(orderHash, secrets[request.fillIndex])
})

WebSocket tracking is optional but provides lower latency than polling. See the WebSocket documentation for more details.

Best Practices

Secret Verification

Always verify escrow details before submitting secrets:

const secretsToShare = await sdk.getReadyToAcceptSecretFills(orderHash)

for (const fill of secretsToShare.fills) {
    // Verify escrow address
    console.log('Escrow address:', fill.escrowAddress)
    
    // Verify amounts
    console.log('Expected amount:', fill.amount)
    
    // Add your own verification logic here
    const isValid = verifyEscrowDetails(fill)
    
    if (isValid) {
        await sdk.submitSecret(orderHash, secrets[fill.idx])
    } else {
        console.error('Escrow verification failed!')
    }
}

Polling Intervals

Use appropriate polling intervals:

// EVM chains: 1-2 seconds
await new Promise(resolve => setTimeout(resolve, 1000))

// Solana: 5 seconds (longer block times)
await setTimeout(5000)

// Production: Consider exponential backoff
const backoff = Math.min(1000 * Math.pow(1.5, attempts), 30000)
await new Promise(resolve => setTimeout(resolve, backoff))

Error Handling

Handle errors gracefully:

try {
    await sdk.submitSecret(orderHash, secrets[idx])
} catch (error) {
    if (error.code === 'ALREADY_SUBMITTED') {
        console.log('Secret already submitted, skipping')
    } else if (error.code === 'ESCROW_NOT_READY') {
        console.log('Escrow not ready yet, will retry')
    } else {
        console.error('Failed to submit secret:', error)
        // Decide whether to retry or abort
    }
}

State Management

Track submitted secrets to avoid duplicates:

const alreadyShared = new Set<number>()

// Before submitting
if (!alreadyShared.has(idx)) {
    await sdk.submitSecret(orderHash, secrets[idx])
    alreadyShared.add(idx) // Mark as submitted
}

// Or use a more detailed tracking structure
const secretStatus = new Map<number, {
    submitted: boolean
    submittedAt?: Date
    retries: number
}>()

Handling Order Failures

Expired Orders

Orders expire if not completed within the time limit:

const { status } = await sdk.getOrderStatus(orderHash)

if (status === OrderStatus.Expired) {
    console.log('Order expired - checking for refund')
    // Check if source funds were refunded
    // Notify user to retry the swap
}

Refunded Orders

Orders may be refunded in certain conditions:

if (status === OrderStatus.Refunded) {
    console.log('Order refunded - funds returned to source wallet')
    // Notify user
    // Log for analytics
}

Integration Patterns

Backend Service

// Example: Express.js endpoint for monitoring
app.post('/api/swap', async (req, res) => {
    const { srcChainId, dstChainId, amount, ... } = req.body
    
    // Create and submit order
    const { hash, quoteId, order } = await sdk.createOrder(...)
    await sdk.submitOrder(...)
    
    // Start background monitoring
    monitorOrderInBackground(hash, secrets)
    
    // Return order hash to client
    res.json({ orderHash: hash })
})

app.get('/api/swap/:orderHash', async (req, res) => {
    const status = await sdk.getOrderStatus(req.params.orderHash)
    res.json(status)
})

Next Steps

• Learn about EVM to EVM swaps for the complete flow
• Explore WebSocket API for real-time updates
• See integrator fees for monetizing your integration