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

# Quote

> Find pools and review a quote before submitting a swap.

<div className="shield-trade-switch not-prose" role="group" aria-label="Trading guide audience">
  <button type="button" id="trade-developers-option" data-trade-select="developers" aria-pressed="true" aria-controls="developers">Developers</button>
  <button type="button" id="trade-web-app-option" data-trade-select="web-app" aria-pressed="false" aria-controls="web-app">Web App</button>
</div>

This page helps you review the expected output of a trade before you submit it, in the Shield Swap app or with the TypeScript SDK, Python SDK, or CLI.

## How quotes work

A quote estimates your output for a chosen pair and input amount. Shield Swap finds a route through the available pools, which can include an intermediate asset when the trade needs more than one pool.

You can review the estimate without spending funds. A quote does not reserve liquidity, so the output can change before you submit the swap.

Every quote includes a slippage setting. Slippage is how much the price can move between your quote and your trade. In practice, it is the gap between the amount you expect to receive and the least you will accept. If slippage is set too low, the swap can fail when the price moves. If it is set too high, you can receive less than you expected. At 1% slippage, a quote for 100 USDCx can settle for as little as 99.

<div id="web-app" data-trade-view="web-app" role="region" aria-labelledby="trade-web-app-option" hidden>
  ## In the app

  The app quotes a trade as soon as you enter an amount. Nothing is sent until you confirm it on the [Swap](./swap) page's steps.

  **Before you start**

  You'll need: Shield Wallet connected to Shield Swap, with a confidential balance of the asset you want to sell. See [Fund your wallet](../start/fund-wallet).

  Shield Swap has two places to get a quote. **Trade** quotes one market at a time, each paired with USDCx, with a price chart and recent market activity. **Swap** quotes any two assets and routes through USDCx when no direct pool exists.

  ### Quote on the Trade page

  1. Open **Trade**.
  2. Select the market name at the top left to open **Switch pair**, then select a market. Each entry shows the pool's fee.
  3. Select **Buy** to receive the market's asset or **Sell** to sell it. **Private Balance** shows how much of the asset you pay with is available.
  4. Enter an amount in **You pay** or **You are selling**, or select **25%**, **50%**, **75%**, or **Max**.

  The panel shows the amount you are buying or receiving, the current exchange rate, **Price impact**, **Swap Fee** with the pool's fee percentage, and **You Receive At Least**, which is the quote after your slippage setting.

  ### Quote on the Swap page

  1. Open **Swap**.
  2. In **From**, select the asset to sell. In **To**, select the asset to receive. The arrow button between them swaps the two.
  3. Enter the amount to sell.

  The panel shows the amount you will receive. **Spot price** and **Market details** below it show the current market, with links to the **Trade** page and the **Pool** for that pair.

  ### Change the slippage setting

  1. Select the gear next to **Slippage**.
  2. Select **0.10%**, **0.50%**, or **1.00%**, or enter a value. The control shows the current default and the allowed range.

  **You Receive At Least** updates to match. At a low setting, the app warns that the swap can fail if the price moves beyond your limit before confirmation. The setting applies to both the **Trade** and **Swap** pages.

  ### Read the quote

  | Field | What it means |
  | - | - |
  | **Price impact** | How much your trade moves the pool's price. Larger trades in smaller pools move it more. |
  | **Swap Fee** | The pool's fee, taken from the asset you sell. A route through two pools shows the two fees combined. |
  | **You Receive At Least** | The least you will receive after slippage. If the market moves further than that before your swap is included, the swap is rejected before it spends your input. The asset stays in your wallet and nothing waits in **Pending Claims**. |
</div>

<div id="developers" data-trade-view="developers" role="region" aria-labelledby="trade-developers-option">
  ## Discover pools

  Pool discovery helps you find markets for the asset you want to trade. A listed pool may have no active liquidity or have trading disabled; requesting a quote checks whether a route is available for your amount.

  **Prerequisites:** Your authenticated mainnet clients from [Setup](./configure): `client` for TypeScript, `dex` for Python, or a configured CLI profile. You do not need a funded account to discover pools.

  These examples find pools containing USDCx:

  <Tabs>
    <Tab title="TypeScript">
      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      const token = await client.tokenData("USDCx")
      const page = await client.api.getPools({ limit: 50, offset: 0 })
      const pools = page.data.filter(
        pool => pool.token0 === token.id || pool.token1 === token.id,
      )
      ```

      `pools` contains the matching entries, each with a pool `key` and the token IDs `token0` and `token1`.

      This request inspects up to 50 pools, starting at offset 0. Check `page.pagination` and increase `offset` to read subsequent pages if you need a complete list.

      #### Look up token details

      Token metadata lets you display a symbol and format amounts with the correct decimal precision. This example looks up both tokens in the first matching pool:

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      const selectedPool = pools[0]
      if (!selectedPool) throw new Error("No matching pools in this page")

      const token0 = await client.tokenData(selectedPool.token0)
      const token1 = await client.tokenData(selectedPool.token1)
      ```

      Each result includes `symbol` and `decimals`, such as `token0.symbol` and `token0.decimals`.

      #### Check pool availability

      A pool needs active liquidity and permission to trade. Continue with `selectedPool` from the token lookup to check both on chain:

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      const poolKey = selectedPool.key
      const slot = await client.getSlot({ poolKey })
      const controls = await client.getTradeControls({ poolKey })
      const hasLiquidity = (slot?.liquidity ?? 0n) > 0n
      const canTrade = hasLiquidity && controls.tradeable
      ```

      `hasLiquidity` checks liquidity at the current price. `controls.tradeable` checks whether the pool is enabled and whether global, token, or pair pauses block trading. `canTrade` is `true` only when both checks pass.
    </Tab>

    <Tab title="Python">
      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      token = dex.api.get_token("USDCx")
      pools = [
          pool for pool in dex.api.get_pools()
          if token.address in (pool.token0, pool.token1)
      ]
      ```

      `pools` contains the matching entries. Each entry has a `key` and the token IDs `token0` and `token1`.

      `get_pools()` reads the API's default page. If you need a complete list, use the [paginated pool endpoint](../api-reference/pools/list-pools).

      #### Look up token details

      Token metadata lets you display a symbol and format amounts with the correct decimal precision. This example looks up both tokens in the first matching pool:

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      if not pools:
          raise ValueError("No matching pools in this page")
      selected_pool = pools[0]

      tokens_by_id = {item.address: item for item in dex.api.get_tokens()}
      token0 = tokens_by_id[selected_pool.token0]
      token1 = tokens_by_id[selected_pool.token1]
      ```

      Each result includes `symbol` and `decimals`, such as `token0.symbol` and `token0.decimals`. `get_token()` accepts a symbol; the catalog above lets you look up the token IDs stored in a pool.

      #### Check pool availability

      Continue with `selected_pool` from the token lookup. The Python SDK reads pool configuration and active liquidity on chain; its API client provides the global, token, and pair pause states:

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      pool_key = selected_pool.key
      pool = dex.get_pool(pool_key)
      slot = dex.get_slot(pool_key)
      global_controls = dex.api.get_compliance()
      token0_controls = dex.api.get_token_compliance(pool.token0)
      token1_controls = dex.api.get_token_compliance(pool.token1)
      pair_controls = dex.api.get_pair_compliance(pool.token0, pool.token1)

      has_liquidity = slot.liquidity > 0
      trading_enabled = pool.enabled and not (
          global_controls.global_paused
          or token0_controls.paused
          or token1_controls.paused
          or pair_controls.paused
      )
      can_trade = has_liquidity and trading_enabled
      ```

      `has_liquidity` checks liquidity at the current price. `trading_enabled` checks the pool's enabled flag and pause states; `can_trade` is `True` only when both conditions pass. An unknown or uninitialized pool raises an error when read.
    </Tab>

    <Tab title="CLI">
      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      shield-swap pools --network mainnet --token USDCx --limit 50 --json
      ```

      The JSON response lists matching pools with their token IDs, active liquidity, and `tradeable` status. A `false` status includes a `reason` explaining why the pool cannot trade.

      `--token` accepts a symbol or token ID. The command inspects up to `--limit` pools before filtering, so increase this limit if you do not find the pair you need.
    </Tab>
  </Tabs>

  These checks help you exclude unavailable pools. API data can lag behind the chain, and liquidity or trading controls can change before your swap executes.

  ## Request a quote

  You choose the asset to sell, the asset to receive, and the input amount. The SDK finds the route for you, so you do not need to select a pool from the discovery results.

  **Prerequisites:** Your authenticated mainnet `client`, `dex`, or CLI profile from [Setup](./configure). The SDKs can quote an unfunded account. The CLI checks your holdings while preparing the trade, so [fund your account](./fund-and-bridge) before using its example.

  These examples quote **1 USDCx for ETH on mainnet**. The slippage setting is 50 basis points (0.5%), which determines the minimum output you'll accept if the price changes before execution.

  <Tabs>
    <Tab title="TypeScript">
      | Parameter | Type and units | Required or default |
      | - | - | - |
      | `from` | `string`: input token symbol or ID. | Required. |
      | `to` | `string`: output token symbol or ID. | Required. |
      | `amountIn` | Decimal `string` in token units, or `bigint` in base units. | Required. |
      | `slippageBps` | Whole `number` in basis points. | Optional; defaults to `50`. |

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import { formatUnits } from "@provablehq/shield-swap-sdk"

      const quote = await client.quote({
        from: "USDCx",
        to: "ETH",
        amountIn: "1",
        slippageBps: 50,
      })

      const expectedOutput = formatUnits(quote.expectedOut, quote.to.decimals)
      const minimumOutput = formatUnits(quote.minOut, quote.to.decimals)
      ```

      `expectedOutput` and `minimumOutput` are decimal strings in ETH units. Use them to compare the estimate with the least you're willing to receive. The quote retains the amounts as base-unit `bigint` values and lists its route in `quote.hops`.

      `quote.expiresAt` gives the expiry time in Unix milliseconds. Request a new quote if it expires before you submit the swap.
    </Tab>

    <Tab title="Python">
      | Parameter | Type and units | Required or default |
      | - | - | - |
      | `token_in` | `str`: input token symbol or ID. | Required. |
      | `token_out` | `str`: output token symbol or ID. | Required. |
      | `amount_in` | Decimal `str` or `Decimal` in token units. | Required. |
      | `slippage_bps` | `int` in basis points. | Optional; defaults to `50`. |

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      quote = dex.quote(
          token_in="USDCx",
          token_out="ETH",
          amount_in="1",
          slippage_bps=50,
      )
      ```

      `quote.estimated_amount_out` and `quote.minimum_amount_out` are decimal strings in ETH units. Compare both amounts with what you're willing to receive; `quote.hops` lists the pools along the route.

      Python quotes do not expire automatically. If you wait before submitting, request a fresh quote to review the current estimate.
    </Tab>

    <Tab title="CLI">
      | Option | Type and units | Required or default |
      | - | - | - |
      | `--from` | Input token symbol or ID. | Required. |
      | `--to` | Output token symbol or ID. | Required. |
      | `--amount` | Decimal amount in token units. | Required unless using `--amount-raw` in base units. |
      | `--slippage` | Integer in basis points. | Optional; defaults to `50`. |
      | `--network` | `mainnet` or `testnet`. | Optional; defaults to `testnet`. Set `mainnet` here. |
      | `--json` | Boolean flag for JSON output. | Optional; off by default. |

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      shield-swap swap --from USDCx --to ETH --amount 1 --slippage 50 --network mainnet --json
      ```

      Without `--execute`, this command returns a preview with `submitted: false`. Its `quote` contains `expectedOut`, `minOut`, and `hops`. Amounts are integer strings in base units; `quote.to.decimals` gives the output token's decimal places.

      The CLI does not save the preview for execution. When you're ready to submit a swap, the next invocation requests a fresh quote.
    </Tab>
  </Tabs>

  ## Next Steps

  ### Submit a swap

  Once you're ready to trade, follow [Swap](./swap) to submit the quote and claim the output.

  ### Run packaged examples

  The [TypeScript examples](https://github.com/ProvableHQ/veil/tree/main/packages/shield-swap/examples/first-swap) and [Python examples](https://github.com/ProvableHQ/python-sdk/tree/master/shield-swap-sdk/examples/first-swap) take you through account setup, funding, and a complete swap. Follow the [Quickstart commands](./quickstart#run-packaged-examples) to run them. Both examples submit and claim a **1.5 USDCx swap on testnet**.
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.