Quote

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.

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 page’s steps.Before you startYou’ll need: Shield Wallet connected to Shield Swap, with a confidential balance of the asset you want to sell. See Fund your 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

Open Trade.
Select the market name at the top left to open Switch pair, then select a market. Each entry shows the pool’s fee.
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.
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

Open Swap.
In From, select the asset to sell. In To, select the asset to receive. The arrow button between them swaps the two.
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

Select the gear next to Slippage.
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.

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

TypeScript
Python
CLI

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:

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:

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.

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.

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:

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:

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.

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.

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. The SDKs can quote an unfunded account. The CLI checks your holdings while preparing the trade, so fund your account 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.

TypeScript
Python
CLI

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

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.

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

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.

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.

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.

Next Steps

Submit a swap

Once you’re ready to trade, follow Swap to submit the quote and claim the output.

Run packaged examples

The TypeScript examples and Python examples take you through account setup, funding, and a complete swap. Follow the Quickstart commands to run them. Both examples submit and claim a 1.5 USDCx swap on testnet.

Start

Trade

Provide liquidity

Integration guides

How quotes work

In the app

Quote on the Trade page

Quote on the Swap page

Change the slippage setting

Read the quote

Discover pools

Look up token details

Check pool availability

Look up token details

Check pool availability

Request a quote

Next Steps

Submit a swap

Run packaged examples

​How quotes work

​In the app

​Quote on the Trade page

​Quote on the Swap page

​Change the slippage setting

​Read the quote

​Discover pools

​Look up token details

​Check pool availability

​Look up token details

​Check pool availability

​Request a quote

​Next Steps

​Submit a swap

​Run packaged examples

How quotes work

In the app

Quote on the Trade page

Quote on the Swap page

Change the slippage setting

Read the quote

Discover pools

Look up token details

Check pool availability

Look up token details

Check pool availability

Request a quote

Next Steps

Submit a swap

Run packaged examples