Definitions
Target asset is the asset being traded, set bytargetAsset (plus targetChain). In a WETH/USDC market, WETH is the target asset. When you buy, you are buying the target. When you sell, you are selling the target.
Contra asset is the pricing and payment asset, set by contraAsset (plus contraChain). In a WETH/USDC market, USDC is the contra asset. It is the asset you spend when buying and the asset you receive when selling.
For same-chain orders, targetChain and contraChain are the same value. Crosschain market orders use different values for the two chains. Assets are always referenced by address, not symbol.
Native asset behavior is chain-specific. If you spend a native gas asset, request a quote through that chain’s native-asset flow, send the returned
wrap action, then submit with the wrapped-native asset from the quote. See EVM native assets and Solana native SOL.Finding asset addresses
Because both legs are addresses, useGET /search to turn a symbol, a name, or a pasted address into the values an order needs. Results are ranked, most relevant first.
cURL
address and chain go straight into targetAsset / targetChain or contraAsset / contraChain, alongside decimals, price, liquidity, and a riskFlagged caution signal. Pass chain to pin results to one chain, or omit it to search every supported chain, in which case a query like usdc returns the Base, Solana, and Ethereum listings as separate results. See Search assets.
How qty works
The meaning of qty depends on the side of the trade. It is always the amount of the asset being spent:
Buy
qty is always denominated in the contra asset. Sell qty is always denominated in the target asset.
Pricing basis
Every price you set on an order — a limit price or a trigger price — is expressed in one of two bases. You choose per price. Notional is the USD value of the target asset. If WETH is trading at $4,000 per WETH, the notional price is"4000". Set it with limitNotionalPrice on a limit, or notionalPrice on a trigger.
Cross is the pair rate: how many contraAsset units one targetAsset unit is worth (target / contra). It is the price of the target asset denominated in the contra asset, never inverted. With WETH as the target and USDC as the contra, a cross price of "4000" means 4,000 USDC per WETH; with cbBTC as the contra it would be cbBTC per WETH. The frame is the same on buy and sell. Set it with limitCrossPrice on a limit, or crossPrice on a trigger.
The two bases are mutually exclusive on the same price — send exactly one. Either way the price is the price of one target-asset unit, never the contra asset’s price. Quote responses report each leg’s notional and the estimated fee in USD regardless of which basis you priced in.
Slippage and price protection
Flash applies three distinct protections at different stages of an order’s lifecycle:- Trader slippage (
maxSlippage) — Configurable in the Flash quote for standard market orders. It limits how far the final amount received may fall below the quoted amount. This tolerance can usually be relatively tight because it measures only the difference between the quoted onchain output and the actual execution output. It applies when an expected amount out is available at quote time. If you omitmaxSlippage, Flash computes a recommendation from factors such as the order’s notional size, whether it is crosschain, and the assets being traded. The quote response returns the value asrecommendedSlippage, and Flash applies it automatically unless you provide an explicit override. - Maximum price impact (
maxPriceImpact) — Configurable in the Flash quote for advanced orders and QuickTrade. It limits how far the effective execution price may differ from the reference market price. This tolerance generally needs to be wider because the reference price does not account for pool fees, transfer taxes, swap fees, liquidity depth, and similar execution costs. For these orders, the simulated amount out is not fixed at quote time, so Flash calculates price impact using the reference price available at execution time. - Onchain slippage — An internal tolerance that the Flash solver sets against a fresh simulation immediately before transaction submission. Flash determines it dynamically from factors such as chain block times, pair volatility, and MEV activity. The settlement contract or program enforces this bound.
Crosschain market orders
Crosschain market orders are live. SettargetChain and contraChain to different supported chains and include recipientAddress, the address that receives funds on the destination chain, in both the quote and order requests.
On a buy, funds move from contraChain to targetChain. On a sell, they move from targetChain to contraChain. The quote returns signing and funding actions for that source chain. If it returns a non-null bridgeQuoteId, pass the value back when you submit the order.
Crosschain execution supports market orders only. QuickTrade is not supported. See Crosschain Orders for the request flow and example.
QuickTrade market orders
QuickTrade is a low-latency execution mode for market orders, built for sniping newly launched tokens. SetquickTrade: true on a market order to trade fresh quoting for speed. It is exclusive to market swaps.
See QuickTrade for how it works, when to use it, the trade-offs, and constraints. Reach out to the Definitive team to find out whether QuickTrade is a good fit for your use case.
Limit pricing
Use a limit order when getting your specified entry or exit price matters more than getting into the trade — the order won’t fill unless the market meets that price. That means if slippage is too high, limit orders may not execute because the fill price inclusive of slippage does not meet your specified entry / exit price.limit orders require a limit price in exactly one basis: limitNotionalPrice (USD price of the target asset) or limitCrossPrice (pair rate, target / contra). Sending both is rejected. Either one prices the traded asset, targetAsset — the contra asset is the unit of account, never the thing being priced.
Buy limit executes at or below the limit price. You are saying: buy the target asset only if the price is this good or better.
Sell limit executes at or above the limit price. You are saying: sell the target asset only if the price is this good or better.
A limit price is also optional on twap, stop, stop-loss, and take-profit, in either basis. Only market rejects a limit price outright.
Once a limit order is resting, its price can be changed without cancelling and re-placing — see Updating Orders. The same applies to the limit price on a resting stop-limit or take-profit-limit order.
Trigger orders
stop, stop-loss, and take-profit orders all fire on a price condition instead of a fixed limit. Each entry in triggers carries exactly one of notionalPrice (USD price of the target asset) or crossPrice (pair rate, target / contra) — sending both, or neither, is rejected — plus a triggerType: lower fires when the market drops to or below the price, upper fires when it rises to or above. Each takes exactly one trigger. A limit price is optional on all three, in either basis — see Limit pricing.
Stop
Usestop when getting into the trade matters more than the entry price. It’s a market buy order that fires once price crosses your specified trigger level.
triggerType: lower— fires once price crosses down through the trigger level. Enter on a pullback without babysitting the market for a bottom.triggerType: upper— fires once price crosses up through the trigger level. Enter on a breakout once the move is confirmed, rather than guessing the breakout price with a limit order.
orderType: "stop", one triggers entry with notionalPrice or crossPrice plus triggerType. Add a limit price (limitNotionalPrice / limitCrossPrice) to cap execution price once triggered; omit it to fire as a market order. Optional expireTime for GTT.
Stop Loss
Usestop-loss to protect a position you already hold. It’s a market sell order that fires once price crosses your specified trigger level, capping the downside if the market turns against you.
Fires once price crosses down through the trigger level (triggerType: "lower").
Set orderType: "stop-loss", one triggers entry with triggerType: "lower". Add a limit price to bound the exit; omit it to sell at market once triggered. Optional expireTime for GTT.
Take Profit
Usetake-profit to lock in gains on a position you already hold. It’s a market sell order that fires once price crosses your specified trigger level, closing the position once the market reaches your target.
Fires once price crosses up through the trigger level (triggerType: "upper").
Set orderType: "take-profit", one triggers entry with triggerType: "upper". Add a limit price to bound the exit; omit it to sell at market once triggered. Optional expireTime for GTT.
Bracket orders
Amarket, limit, or twap order can carry an attached bracket order: a take-profit / stop-loss pair placed together with the entry order in one quote, sign, and submit flow. Add attachedBracket to the quote request with a trigger price for each leg; the quote returns a second signing payload for the pair, and the pair activates on the entry’s first fill, protecting the asset the entry receives. Attached brackets are available on same-chain EVM orders and require funderAddress. See Bracket Orders for the request fields, lifecycle, and an end-to-end example.
Order expiry
FlashOrder.deadline is enforced onchain, but you do not set the signed deadline directly — Flash derives it from your quote request. Control expiry through the quote-request parameters below so the API order expiration and the onchain signature deadline stay aligned; prefer these over editing the deadline inside the signed payload.
Examples
All examples buy or sell WETH (0x4200000000000000000000000000000000000006) against USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base.
Market buy: spend 100 USDC to buy WETH, with 5% slippage protection
The qty is "100", meaning spend 100 USDC (contra asset).
qty is "0.05", meaning sell 0.05 WETH (target asset).
qty is "100", meaning spend up to 100 USDC. The order executes only when WETH is available at $1,000 per WETH or lower.
qty is "0.05", meaning sell 0.05 WETH (target asset). The order executes only when WETH reaches $4,000 per WETH or higher.
Quick reference
EVM Overview
How quoting, routing, and signing work on EVM.
Non-Custodial by Design
How Flash keeps funds in the user’s wallet for every order type.