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

# Request Trade Quotes

> Get the best swap and bridge quotes using the DZap SDK

The DZap SDK provides functionality to request trade quotes, as well as to execute them. This guide will walk you through the process of making a request using `getTradeQuotes`.

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

## How to Request Trade Quotes

To get started, here is a simple example of how to request quotes to bridge and swap 1 USDC on Arbitrum to ETH on Base.

```typescript theme={null}
import { DZapClient } from "@dzapio/sdk";
import type { TradeQuotesRequest } from "@dzapio/sdk";

const dZap = DZapClient.getInstance();

const quotesRequest: TradeQuotesRequest = {
  fromChain: 42161, // Arbitrum
  data: [
    {
      amount: "1000000", // 1 USDC (6 decimals)
      srcToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
      destToken: "0x4200000000000000000000000000000000000006", // WETH on Base
      toChain: 8453, // Base Chain
      slippage: 1, // 1% slippage
    },
  ],
  account: userAccount, // User's wallet address (optional)
};

// getTradeQuotes returns the response directly (object keyed by pair key)
const quotes = await dZap.getTradeQuotes(quotesRequest);
const pairKey = Object.keys(quotes)[0];
const pairData = quotes[pairKey];
```

When you request quotes, you receive an object keyed by pair identifier; each entry contains `recommendedSource`, `bestReturnSource` (fallback), and `quoteRates`. Transaction data is not included and must be built separately for `trade()` or `buildTradeTxn()`.

## Trade Quotes Request Parameters

The `getTradeQuotes` function expects a `TradeQuotesRequest` object, which specifies a desired trade and includes all the information needed to calculate the most efficient routes.

### Request Parameters

| Parameter           | Type                      | Required | Description                                                                               |
| ------------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `fromChain`         | number                    | yes      | The ID of the source chain (e.g., Ethereum mainnet is 1)                                  |
| `data`              | TradeQuotesRequestData\[] | yes      | Array of trade request data objects                                                       |
| `account`           | string                    | no       | User's wallet address for the trade (optional)                                            |
| `filter`            | QuoteFilter               | no       | Filter type for quote results (default is "all")                                          |
| `gasless`           | boolean                   | no       | Request gasless-eligible quotes                                                           |
| `private`           | boolean                   | no       | Request private/MEV-protected quotes                                                      |
| `disableEstimation` | boolean                   | no       | Skip gas/output estimation for faster response times                                      |
| `bridges`           | ProtocolFilter            | no       | Allow/deny list of bridge providers to consider (`{ allow?: string[]; deny?: string[] }`) |
| `dexes`             | ProtocolFilter            | no       | Allow/deny list of DEX providers to consider (`{ allow?: string[]; deny?: string[] }`)    |

### TradeQuotesRequestData Parameters

| Parameter        | Type   | Required | Description                                                                                     |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `amount`         | string | yes      | The amount to be transferred from the source chain, specified in the smallest unit of the token |
| `srcToken`       | string | yes      | The contract address of the token on the source chain                                           |
| `srcDecimals`    | number | no       | Decimals of the source token (skips an on-chain/metadata lookup if provided)                    |
| `destToken`      | string | yes      | The contract address of the token on the destination chain                                      |
| `destDecimals`   | number | no       | Decimals of the destination token (skips an on-chain/metadata lookup if provided)               |
| `toChain`        | number | yes      | The ID of the destination chain                                                                 |
| `slippage`       | number | yes      | The slippage tolerance as a percentage (e.g., 1 for 1%)                                         |
| `selectedSource` | string | no       | Restrict/prefer quoting to a specific provider ID                                               |

## Quote Filter Options

You can filter quotes based on different criteria:

* `all` - Returns all available quotes. This is the default option and provides the fastest response time.
* `best` - Return only the best quote
* `fastest` - Return the fastest execution time quote (for bridge operations)

```typescript theme={null}
const quotesRequest: TradeQuotesRequest = {
  fromChain: 42161,
  data: [
    {
      amount: "1000000",
      srcToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      destToken: "0x4200000000000000000000000000000000000006",
      toChain: 8453,
      slippage: 1,
    },
  ],
  account: userAccount,
  filter: "best", // Only return the best quote
};
```

## Advanced Quote Configuration

For applications requiring fine-tuned control over quote optimization, the SDK provides advanced configuration options:

### Advanced Parameters

| Parameter        | Type           | Required | Description                                  |
| ---------------- | -------------- | -------- | -------------------------------------------- |
| `timingStrategy` | TimingStrategy | no       | Fine-tune quote optimization timing behavior |

### TimingStrategy Configuration

The `timingStrategy` parameter allows fine-grained control over how the SDK optimizes quote collection:

#### minWaitTimeMs

| Property        | Type   | Default | Description                                                                                                                                                                                                                                                     |
| --------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minWaitTimeMs` | number | `1000`  | **Minimum wait time before returning results.** Sets the floor for how long the SDK will wait before returning quotes, ensuring adequate time for providers to respond. Useful when you want to guarantee a minimum collection time for better quote diversity. |

#### maxWaitTimeMs

| Property        | Type   | Default | Description                                                                                                                                                                                                                                                       |
| --------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxWaitTimeMs` | number | `5000`  | **Maximum wait time for quote optimization.** Sets the ceiling for quote collection time. The SDK will stop waiting for additional quotes after this duration, even if more providers might respond. Helps balance quote quality with response time requirements. |

#### subsequentDelayMs

| Property            | Type   | Default | Description                                                                                                                                                                                                                                             |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subsequentDelayMs` | number | `500`   | **Delay between subsequent quote requests.** Controls the interval between batched quote requests to providers. Lower values may overwhelm providers, while higher values may slow down quote collection. Optimize based on provider response patterns. |

#### preferredResultCount

| Property               | Type   | Default | Description                                                                                                                                                                                                                         |
| ---------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preferredResultCount` | number | `3`     | **Target number of quote results to collect.** The SDK will attempt to gather this many quotes before potentially stopping early (if within timing constraints). Higher values provide more options but may increase response time. |

#### relaxMinSuccessOnDelay

| Property                 | Type    | Default | Description                                                                                                                                                                                            |
| ------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `relaxMinSuccessOnDelay` | boolean | -       | **Relax the minimum-success requirement once `maxWaitTimeMs` is reached.** When enabled, the SDK returns whatever quotes it has collected instead of continuing to wait once the delay ceiling is hit. |

### Advanced Configuration Example

```typescript theme={null}
const quotesRequest: TradeQuotesRequest = {
  fromChain: 42161,
  data: [
    {
      amount: "1000000",
      srcToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      destToken: "0x4200000000000000000000000000000000000006",
      toChain: 8453,
      slippage: 1,
    },
  ],
  account: userAccount,

  // Advanced timing configuration for optimal quote collection
  timingStrategy: {
    minWaitTimeMs: 1500, // Wait at least 1.5 seconds for provider responses
    maxWaitTimeMs: 4000, // Don't wait more than 4 seconds total
    subsequentDelayMs: 300, // 300ms between provider batches
    preferredResultCount: 5, // Try to collect 5 different quotes
    relaxMinSuccessOnDelay: true, // Return partial results once maxWaitTimeMs is hit
  },

  // Skip estimation for faster response in high-frequency scenarios
  disableEstimation: true,
};
```

### TypeScript Type Definition

```typescript theme={null}
type TimingStrategy = Partial<{
  minWaitTimeMs: number; // Minimum wait time before returning results
  maxWaitTimeMs: number; // Maximum wait time for quote optimization
  subsequentDelayMs: number; // Delay between subsequent quote requests
  preferredResultCount: number; // Target number of quote results to collect
  relaxMinSuccessOnDelay: boolean; // Relax the min-success requirement once maxWaitTimeMs is hit
}>;
```

## Understanding the Response

The response contains detailed information about available routes:

```typescript theme={null}
type TradeQuotesResponse = {
  [pair: string]: {
    status?: string;
    message?: string;
    recommendedSource: string; // Preferred provider for this pair
    bestReturnSource: string; // Best return provider for this pair
    fastestSource?: string; // Fastest route (bridge quotes)
    questSource?: string;
    quoteRates?: TradeQuotesByProviderId;
    tokensWithoutPrice: Record<number, string[]>;
  };
};
```

### Key Response Fields

* **`pair`** - Unique identifier for the trade pair (e.g., `42161_0xaf88..._8453_0x4200...`). Can be generated using `getTokensPairKey`.
* **`recommendedSource`** - The provider ID of the recommended route; use this when building the trade request.
* **`bestReturnSource`** - Best return provider for this pair;
* **`quoteRates`** - Object containing detailed quotes per provider (keyed by provider ID).
* **`tokensWithoutPrice`** - Tokens that don't have price data available.

## Working with Quote Results

```typescript theme={null}
const quotes = await dZap.getTradeQuotes(quotesRequest);

const pairKey = Object.keys(quotes)[0];
const pairData = quotes[pairKey];
const source = pairData.recommendedSource;
const recommendedQuote = pairData.quoteRates?.[source];

if (recommendedQuote) {
  console.log("Best route details:");
  console.log("Source amount:", recommendedQuote.srcAmount);
  console.log("Destination amount:", recommendedQuote.destAmount);
  console.log("Provider:", recommendedQuote.providerDetails.name);
  console.log("Estimated duration:", recommendedQuote.duration);
  console.log("Price impact:", recommendedQuote.priceImpactPercent);
}
```

## Next Steps

Once you have received quotes, you can proceed to:

1. [Execute the trade](/sdk/trade/execute-trade) (build `TradeBuildTxnRequestData` from the quote, then call `trade()`)
2. [Track the status](/sdk/trade/status-tracking) of your trade

<Note>
  Before executing trades, tokens typically require approval to allow the DZap
  contracts to spend them on your behalf. Learn more about gas-optimized
  approval mechanisms in the [Approval Mechanisms](/sdk/approval-mechanisms)
  section.
</Note>