Track Trade Status

After executing a trade, you need to monitor its progress, especially for cross-chain transactions that may take several minutes to complete.

The DZap SDK provides status tracking for all trade types, from simple swaps to complex cross-chain bridges.

Rate Limits: Our API and SDK have rate limits in place to ensure fair usage. If you need increased rate limits for your application, please reach out to our team on Telegram.

Basic Status Tracking

Here’s how to check the status of a completed trade:

import { DZapClient } from "@dzapio/sdk";

const dZap = DZapClient.getInstance();

const statusResult = await dZap.getTradeTxnStatus({
  txHash: "0x1234567890abcdef...", // Your transaction hash
  chainId: 42161, // Source chain ID
});

console.log("Trade status:", statusResult);

Status Request Parameters

The getTradeTxnStatus function accepts either a txHash or a txId, always paired with chainId:

Parameter	Type	Required	Description
`txHash`	string	one of `txHash`/`txId`	The on-chain transaction hash from the executed trade
`txId`	string	one of `txHash`/`txId`	The DZap transaction ID returned when building the trade
`chainId`	number	yes	The chain ID where the transaction was executed

type Params = { txHash: string; chainId: number } | { txId: string; chainId: number };

Status Response Structure

The status response follows the TradeStatusResponse type — a single flat object (not keyed by pair), with a transactions array covering each leg of the trade:

type TradeStatusResponse = {
  status: StatusResponse; // Overall status
  gasless: boolean;
  txHash: string;
  chainId: number;
  timestamp: number;
  transactions: TxStatusForPair[];
  type: "swap" | "bridge" | "zap";
};

type StatusResponse = "COMPLETED" | "FAILED" | "PENDING" | "PARTIAL" | "REFUNDED";

type TxStatusForPair = {
  source: TransactionInfo;
  destination: TransactionInfo & { timestamp?: number };
  expected?: Omit<TransactionInfo, "txHash" | "status">;
  status: StatusResponse;
  provider: { id: string; name: string; icon: string };
  allowUserTxOnDestChain: boolean;
  message?: string;
  protocolExplorerLink?: string;
};

type TransactionInfo = {
  asset: {
    contract: string;
    chainId: number;
    name?: string;
    symbol?: string;
    decimals?: number;
    logo?: string;
    underlyingTokens?: { chainId: number; address: string; name?: string; symbol: string; decimals: number; logo?: string | null }[];
  };
  amount: string;
  amountUSD: number;
  txHash: string;
  account: string;
};

Polling for Trade Completion

For cross-chain trades, poll until the transaction reaches a terminal state:

import { DZapClient, TxnStatus } from "@dzapio/sdk";

const dZap = DZapClient.getInstance();

async function waitForTradeCompletion(
  txHash: string,
  chainId: number,
  options?: { intervalMs?: number; timeoutMs?: number }
) {
  const interval = options?.intervalMs ?? 10_000; // 10 seconds
  const timeout = options?.timeoutMs ?? 600_000; // 10 minutes
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const statusResult = await dZap.getTradeTxnStatus({ txHash, chainId });

    // Terminal states: COMPLETED, FAILED, PARTIAL, REFUNDED
    if (statusResult.status !== "PENDING") {
      if (statusResult.status === "FAILED" || statusResult.status === "REFUNDED") {
        const failedLeg = statusResult.transactions.find(
          (t) => t.status === "FAILED" || t.status === "REFUNDED"
        );
        throw new Error(
          `Trade ${statusResult.status.toLowerCase()}. ${failedLeg?.message ?? ""}`
        );
      }
      return statusResult; // COMPLETED or PARTIAL
    }

    console.log(`Waiting... overall status: ${statusResult.status}`);
    await new Promise((resolve) => setTimeout(resolve, interval));
  }

  throw new Error(`Trade timed out after ${timeout / 1000}s`);
}

// Usage after executing a trade
const tradeResult = await dZap.trade({ request, signer });
if (tradeResult.status === TxnStatus.success) {
  const finalStatus = await waitForTradeCompletion(
    tradeResult.txnHash!,
    request.fromChain
  );
  console.log("Trade completed:", finalStatus);
}

Checking Multiple Transactions

Use getTradeMultiTxnStatus to check several transactions in one call. It accepts comma-separated txHashes/txIds aligned positionally to comma-separated chainIds, and returns an array of TradeStatusResponse:

const multiStatus = await dZap.getTradeMultiTxnStatus({
  txHashes: "0x123...,0x456...",
  chainIds: "1,42161",
});
// multiStatus: TradeStatusResponse[]

Parameter	Type	Required	Description
`txHashes`	string	one of `txHashes`/`txIds`	Comma-separated transaction hashes
`txIds`	string	one of `txHashes`/`txIds`	Comma-separated DZap transaction IDs
`chainIds`	string	yes	Comma-separated chain IDs, aligned to `txHashes`/`txIds`

Best Practices

Implement proper polling intervals - Don’t poll too frequently to avoid rate limits (recommended: 10s+)
Handle all status types - Prepare for successful, failed, and pending states
Set a timeout - Cross-chain trades can take minutes, but shouldn’t hang indefinitely

Cross-chain transactions can take anywhere from a few minutes to an hour depending on the bridge used and network congestion.

​Basic Status Tracking

​Status Request Parameters

​Status Response Structure

​Polling for Trade Completion

​Checking Multiple Transactions

​Best Practices

Basic Status Tracking

Status Request Parameters

Status Response Structure

Polling for Trade Completion

Checking Multiple Transactions

Best Practices