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

# Best Build

> Fetch quotes from every provider and build a ready-to-sign transaction for the best route, in a single call.

Combines [`/v1/quotes`](/api/trade/quote) and [`/v1/buildTx`](/api/trade/build-tx) into one request: it collects quotes from every eligible provider for each pair in `data`, picks the best route per pair, and returns transaction calldata ready to sign - along with every provider's quote so you can show alternatives without a second call.

Whether a request is treated as a same-chain swap or a cross-chain bridge is inferred automatically: if `fromChain` equals `data[0].toChain`, it's a swap; otherwise it's a bridge. `overrideMultiTx` only applies to bridge requests; `maximizeMinToAmount` and `nonceOffset` only apply to swap requests.

### Body

<ParamField body="fromChain" type="integer" required>Source chain ID for every item in `data`.</ParamField>

<ParamField body="account" type="string" required>Wallet address sending the transaction.</ParamField>

<ParamField body="refundee" type="string" required>Address to receive refunds.</ParamField>

<ParamField body="data" type="object[]" required>
  Array of trade legs to quote and build.

  <Expandable title="data item">
    <ParamField body="amount" type="string" required>Amount to send, in the source token's smallest unit.</ParamField>

    <ParamField body="srcToken" type="string" required>Source token contract address.</ParamField>

    <ParamField body="srcDecimals" type="integer">Source token decimals (skips a lookup if provided).</ParamField>

    <ParamField body="destToken" type="string" required>Destination token contract address.</ParamField>

    <ParamField body="destDecimals" type="integer">Destination token decimals (skips a lookup if provided).</ParamField>

    <ParamField body="toChain" type="integer" required>Destination chain ID.</ParamField>

    <ParamField body="slippage" type="number" required>Slippage tolerance, in percent.</ParamField>

    <ParamField body="recipient" type="string" required>Address to receive the destination tokens for this leg.</ParamField>

    <ParamField body="selectedSource" type="string">Restrict/prefer quoting to a specific provider ID.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="gasless" type="boolean">Request gasless-eligible quotes/build. Default `false`.</ParamField>

<ParamField body="private" type="boolean">Request private/MEV-protected quotes/build. Default `false`.</ParamField>

<ParamField body="disableEstimation" type="boolean">Skip gas estimation for a faster build.</ParamField>

<ParamField body="disablePricing" type="boolean">Skip USD pricing lookups for a faster response.</ParamField>

<ParamField body="simulate" type="boolean">Simulate each candidate route on-chain before selecting the winner. Slower, but filters out routes that would revert.</ParamField>

<ParamField body="maximizeMinToAmount" type="boolean">Swap only. Runs extra on-chain checks to find the highest safe `minToAmount` for the selected route.</ParamField>

<ParamField body="nonceOffset" type="integer">Swap only. Offset applied to the sender's nonce when building the transaction.</ParamField>

<ParamField body="overrideMultiTx" type="boolean">Bridge only. Overrides the default multi-transaction batching behavior.</ParamField>

<ParamField body="bridges" type="object">Allow/deny list of bridge providers: `{ allow?: string[]; deny?: string[] }`.</ParamField>

<ParamField body="dexes" type="object">Allow/deny list of DEX providers: `{ allow?: string[]; deny?: string[] }`.</ParamField>

<ParamField body="timingStrategy" type="object">
  Fine-tune quote collection timing.

  <Expandable title="timingStrategy">
    <ParamField body="minWaitTimeMs" type="integer">Minimum wait time before returning results.\`.</ParamField>

    <ParamField body="maxWaitTimeMs" type="integer">Maximum wait time for quote optimization.\`.</ParamField>

    <ParamField body="subsequentDelayMs" type="integer">Delay between subsequent provider batches..</ParamField>

    <ParamField body="preferredResultCount" type="integer">Target number of quotes to collect..</ParamField>

    <ParamField body="relaxMinSuccessOnDelay" type="boolean">Return partial results once `maxWaitTimeMs` is hit.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="hasPermit2ApprovalForAllTokens" type="boolean">Set `true` if Permit2 approval already exists for every token in `data`.</ParamField>

### Response - success

<ResponseField name="status" type="string">`"success"` when the build succeeds.</ResponseField>

<ResponseField name="txId" type="string">Unique build/transaction ID - use for status polling and broadcasting.</ResponseField>

<ResponseField name="chainId" type="integer">Chain where the transaction is to be executed.</ResponseField>

<ResponseField name="transaction" type="object">Chain-specific payload, ready to sign. Same shape as `transaction` in the [`/v1/buildTx`](/api/trade/build-tx) response - see that page for the per-chain-type field breakdown (evm, svm, btc, btcln, HyperLiquid).</ResponseField>

<ResponseField name="broadcastViaProvider" type="boolean">Whether the built transaction must be broadcast via the winning provider rather than submitted directly.</ResponseField>

<ResponseField name="quotes" type="object">
  Every provider that successfully quoted (and, if `simulate` was set, passed simulation) for each pair - not just the winner used to build `transaction`. Keyed by pair ID (`{fromChain}_{srcToken}_{toChain}_{destToken}`), then by provider ID. Within each pair, providers are ranked best-first by net return.

  <Expandable title="quotes[pairId][providerId]">
    <ResponseField name="providerDetails" type="object">
      <Expandable title="providerDetails">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="icon" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="destAmount" type="string" />

    <ResponseField name="minDestAmount" type="string" />

    <ResponseField name="priceImpact" type="string">May be `null` if a token's USD price is unavailable.</ResponseField>

    <ResponseField name="duration" type="string">Estimated seconds to completion.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="selectedProviders" type="object">Keyed by pair ID (same keys as `quotes`) - the provider ID whose quote was actually used to build `transaction` for that pair.</ResponseField>

### Response - error

<ResponseField name="status" type="string">`"error"`.</ResponseField>

<ResponseField name="txId" type="string">Build ID, if one was generated before the failure. Empty string otherwise.</ResponseField>

<ResponseField name="error" type="string">Failure reason.</ResponseField>

### Examples

<RequestExample>
  ```bash curl theme={null}
  curl -X POST https://api.dzap.io/v1/best-build \
    -H "Content-Type: application/json" \
    -d '{
      "fromChain": 42161,
      "account": "0x99BCEBf44433E901597D9fCb16E799a4847519f6",
      "refundee": "0x99BCEBf44433E901597D9fCb16E799a4847519f6",
      "data": [
        {
          "amount": "1000000",
          "srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
          "destToken": "0x4200000000000000000000000000000000000006",
          "toChain": 8453,
          "slippage": 1,
          "recipient": "0x99BCEBf44433E901597D9fCb16E799a4847519f6"
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "success",
    "txId": "0xabc123...",
    "chainId": 42161,
    "transaction": {
      "from": "0x99BCEBf44433E901597D9fCb16E799a4847519f6",
      "data": "0x...",
      "to": "0x1d46863e3592745008b5CbbAC12014F67329A9b8",
      "value": "0",
      "gasLimit": "350000"
    },
    "broadcastViaProvider": false,
    "quotes": {
      "42161_0xaf88d065e77c8cC2239327C5EDb3A432268e5831_8453_0x4200000000000000000000000000000000000006": {
        "across": {
          "providerDetails": { "id": "across", "name": "Across", "icon": "https://..." },
          "destAmount": "300000000000000",
          "minDestAmount": "298500000000000",
          "priceImpact": "-0.12",
          "duration": "90"
        },
        "stargate": {
          "providerDetails": { "id": "stargate", "name": "Stargate", "icon": "https://..." },
          "destAmount": "299500000000000",
          "minDestAmount": "298000000000000",
          "priceImpact": "-0.15",
          "duration": "60"
        }
      }
    },
    "selectedProviders": {
      "42161_0xaf88d065e77c8cC2239327C5EDb3A432268e5831_8453_0x4200000000000000000000000000000000000006": "across"
    }
  }
  ```
</ResponseExample>

<Note>
  Use the `txId` to poll `/v1/status` once the transaction has been signed and sent.
</Note>