Skip to main content
A trailing stop follows the market instead of resting at a fixed trigger price. It tracks a watermark of the target asset’s USD price, the highest price seen for a sell or the lowest for a buy, and fires when the price retraces from that watermark by 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 sits trailPercent 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

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)

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 the order 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.
Trailing buy: spend 100 USDC on WETH once WETH has dipped to $3,000 and then bounces 5% off its low. On a buy, qty is denominated in the contra asset (USDC).

Reading the trail

Order reads return the trail as submitted plus its state under trailingStop, 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. expireTime is 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 closed REASON_ORDER_EXPIRED.
  • No updates. PATCH /orders/{orderId} returns 422 for both trailing types. To change trailPercent or activationPrice, 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, a trailing-stop-limit is a resting limit order and can still be cancelled by the same orderId.
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.