> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dzap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Trade Status

> Monitor and track trade transaction status using the DZap SDK

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

<Note>
  **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](https://t.me/shivam0x).
</Note>

## Basic Status Tracking

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

```typescript theme={null}
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          |

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`:

```typescript theme={null}
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

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

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