trailPercent. The trigger only ever moves in your favour: a pullback never loosens it.
Trailing orders take a trailingStop block instead of triggers. The signing and submit plumbing is identical to a stop-loss; only the request fields differ. For the concepts behind the shared parameters, see Placing Orders.
qty follows the usual rule: contra units on a buy, target units on a sell. Trailing orders are same-chain only.
The trailingStop block
Neither trailing type takes a limit price:
limitNotionalPrice and limitCrossPrice are rejected, and so is triggers. The limit of a trailing-stop-limit is the effective trigger price Flash derives from the watermark when the trail fires. expireTime is optional, as on other trigger types: set it for good-til-time, omit it for good-til-cancelled.
How the trail moves
Once armed, every price Flash observes does two things, in order: it ratchets the watermark (up for a sell, down for a buy) and it is compared against the effective trigger computed from that updated watermark. A freshly armed trail can never fire on the price that armed it, because the trigger sitstrailPercent away from it. This also means a trailing order never closes REASON_ORDER_TRIGGERED_ON_ENTRY.
Sell with trailPercent: "0.05" and no activation price:
Buy with
trailPercent: "0.05" and activationPrice: "100":
The reference price is the same USD price of the target asset that
notionalPrice triggers evaluate against. There is no pair-rate (crossPrice) form of a trailing stop.
Execution when it fires
trailing-stop places a market order. Like a stop-loss it is designed to prioritize exiting once the trail is breached, so when you omit maxPriceImpact it executes under the same deliberately wide 50% default, on both sells and buys. Set maxPriceImpact in the quote for a tighter bound when price matters more than exiting; an explicit value is authoritative when the trail fires. If the available route exceeds the bound, the swap does not execute and no funds move. See Stop-loss execution and price protection for the trade-off.
trailing-stop-limit places a limit order at the effective trigger price at the moment of firing: a sell fills at or above it, a buy at or below it. It never fills worse than the trail, but it can rest unfilled if the market keeps moving away. Once it has fired it is an ordinary resting limit order and can be cancelled by its orderId.
End-to-end example: trailing stop
Prerequisites. EVM examples use
viem; Solana examples use @solana/web3.js, tweetnacl, and bs58. All requests go to https://flash.definitive.fi/v1 with your key in the x-definitive-api-key header. The public integrator key dpka_513a2bd7_57a2_46d2_927b_2a3857fe271b is safe for development. The onchain steps also need an RPC endpoint and the funder wallet’s key, supplied here through environment variables.EVM
EVM
Sell 0.05 WETH for USDC on Base once WETH has reached $4,000 and then falls 5% from its high. On a sell,
qty is denominated in the target asset (WETH). If the spent token needs an allowance, the quote returns evm.approveTx (or evm.permitTypedData on the Permit2 path); handle whichever it returns, then sign the order payload and submit.SVM (Solana)
SVM (Solana)
Sell 5 WSOL for USDC if WSOL falls 5% from its high, arming at the current price. On a sell,
qty is denominated in the target asset (WSOL). Before the first trade of a token the swap needs the funder’s token accounts (svm.ataSetupIxs) and a delegation (svm.delegateIx or a sponsor-paid svm.sponsoredDelegateTx). Run the onchain steps in order, then sign the order message offchain and submit.Trailing stop-limit and trailing buys
The flow above works unchanged for the other shapes. Swap theorder block for one of these; everything else (approval or delegation, signing, submit) stays the same.
Trailing stop-limit: sell 0.05 WETH when it falls 3% from its high, as a limit order at the trail.
qty is denominated in the contra asset (USDC).
Reading the trail
Order reads return the trail as submitted plus its state undertrailingStop, with trigger null. GET /orders/{orderId} for the EVM example above, a little after the trail armed:
Flash fires on the watermark it holds in memory and persists that watermark on a throttle: at most once every 5 seconds per order, and only once a minute while the trigger has moved less than 1% since the last save. The values you read are therefore the last saved watermark, and the live trigger can sit slightly ahead of them. Firing is never delayed by persistence.
The Orders WebSocket carries the same
trailingStop block on every frame for the order, so a stream shows the trigger ratcheting as the market moves.
Lifecycle
- Expiry.
expireTimeis optional. Omit it for good-til-cancelled; set an ISO-8601 timestamp for good-til-time. An unarmed or armed-but-unfired trail that reaches its expiry is closedREASON_ORDER_EXPIRED. - No updates.
PATCH /orders/{orderId}returns422for both trailing types. To changetrailPercentoractivationPrice, cancel and place a new order. The new order arms from the price at that moment, not from the old watermark. - Cancelling. Cancel at any point before the fire with
POST /orders/{orderId}/cancel. After the fire, atrailing-stop-limitis a resting limit order and can still be cancelled by the sameorderId.
To track the order after submit, poll
GET /orders or stream live updates over the Orders WebSocket.Trigger Orders
Fixed-price stop, stop-loss, and take-profit orders.
Placing Orders
The full parameter reference for every order type.