Trigger Orders

Trigger orders fire on a price condition rather than a fixed limit. Each entry in triggers carries exactly one of notionalPrice (the USD price of the target asset) or crossPrice (the pair rate, target / contra), plus a triggerType: lower fires when the market drops to or below the price, upper fires when it rises to or above. For the concepts behind the parameters, see Placing Orders. This page covers three single-trigger types: stop, stop-loss, and take-profit. The signing and submit plumbing is identical to a market order; only the request fields differ, and each type has a fixed side and, for two of them, a fixed triggerType. Each is a single leg. To put both a take-profit and a stop-loss on a token you already hold as one linked order, place a standalone bracket instead; to attach the pair to a new market, limit, or twap order, use attachedBracket. Both are covered in Bracket Orders.

Order type	`side`	`triggerType`	Fires when
`stop-loss`	`sell`	`lower`	Price falls to or below the trigger
`take-profit`	`sell`	`upper`	Price rises to or above the trigger
`stop`	`buy`	`upper` (typical)	Price rises to or above the trigger (breakout entry)

Each of these takes exactly one trigger. qty follows the usual rule: contra units on a buy, target units on a sell. The examples below use notionalPrice; substitute crossPrice to fire on the pair rate instead of the dollar price — { "crossPrice": "3000", "triggerType": "lower" } fires when WETH falls to 3,000 USDC per WETH. Exactly one of the two is required on every trigger.

Stop-loss execution and price protection

A stop-loss without a limit price is designed to prioritize exiting once the trigger is breached. In fast cascades, rug pulls, or fragmented low-liquidity markets, a tight execution bound can repeatedly reject the available route and leave you holding the asset as its price continues to fall. Triggered market orders therefore use a deliberately wide default maximum price impact of 50%. Set maxPriceImpact in the quote when you need a different trade-off. An explicit value remains authoritative when the trigger executes, for both notionalPrice and crossPrice triggers; Flash does not replace it with the 50% default. If the available route exceeds that bound, the swap does not execute and no funds move. Use maxPriceImpact to choose between two execution priorities:

Exit priority — Keep a wider maximum price impact. The order fires as soon as the reference price crosses the trigger and accepts more price impact when liquidity is thin.
Price priority — Set a tighter maximum price impact. After the trigger fires, Flash executes only when the simulated route satisfies your bound. The order may not fill if liquidity disappears or the market moves too quickly.

These are execution priorities, not separate API mode values. Configure the trade-off with maxPriceImpact. This setting controls execution after the trigger condition is met; it does not change the trigger price itself. Add a limit price instead when the order must never execute beyond a specific absolute price. The trade-off is that the resulting limit order can remain unfilled.

End-to-end example: stop-loss

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 if WETH falls to $3,000 or below. 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.

import { createWalletClient, createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const BASE_URL = "https://flash.definitive.fi/v1";
const API_KEY = "dpka_513a2bd7_57a2_46d2_927b_2a3857fe271b";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http(process.env.EVM_RPC_URL) });
const publicClient = createPublicClient({ chain: base, transport: http(process.env.EVM_RPC_URL) });

const post = (path: string, body: unknown) =>
  fetch(`${BASE_URL}${path}`, {
    method: "POST",
    headers: { "content-type": "application/json", "x-definitive-api-key": API_KEY },
    body: JSON.stringify(body),
  }).then((r) => r.json());

const order = {
  targetChain: "base",
  contraChain: "base",
  targetAsset: "0x4200000000000000000000000000000000000006", // WETH
  contraAsset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
  side: "sell",
  qty: "0.05",
  orderType: "stop-loss",
  triggers: [{ notionalPrice: "3000", triggerType: "lower" }],
  maxPriceImpact: "0.1", // reject execution above 10% price impact
};

const quote = await post("/quote", { ...order, funderAddress: account.address });

if (quote.evm.approveTx) {
  const hash = await wallet.sendTransaction({
    to: quote.evm.approveTx.to,
    data: quote.evm.approveTx.data,
    value: 0n,
  });
  await publicClient.waitForTransactionReceipt({ hash });
}

let permitFields = {};
if (quote.evm.permitTypedData) {
  const evmPermitSignature = await account.signTypedData(JSON.parse(quote.evm.permitTypedData));
  permitFields = { evmPermitTypedData: quote.evm.permitTypedData, evmPermitSignature };
}

const { domain, types, primaryType, message } = JSON.parse(quote.evm.orderTypedData);
const userSignature = await account.signTypedData({ domain, types, primaryType, message });

const { orderId } = await post("/order", {
  ...order,
  funderAddress: account.address,
  quoteId: quote.quoteId,
  userSignature,
  evmOrderTypedData: quote.evm.orderTypedData,
  ...permitFields,
});

console.log("orderId", orderId);

SVM (Solana)

Sell 5 WSOL for USDC if WSOL falls to $120 or below. 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.

import {
  Connection,
  Keypair,
  PublicKey,
  TransactionInstruction,
  TransactionMessage,
  VersionedTransaction,
} from "@solana/web3.js";
import nacl from "tweetnacl";
import bs58 from "bs58";

const BASE_URL = "https://flash.definitive.fi/v1";
const API_KEY = "dpka_513a2bd7_57a2_46d2_927b_2a3857fe271b";

const connection = new Connection(process.env.SOLANA_RPC_URL!, "confirmed");
const funder = Keypair.fromSecretKey(bs58.decode(process.env.SOLANA_SECRET_KEY!));

const post = (path: string, body: unknown) =>
  fetch(`${BASE_URL}${path}`, {
    method: "POST",
    headers: { "content-type": "application/json", "x-definitive-api-key": API_KEY },
    body: JSON.stringify(body),
  }).then((r) => r.json());

const toIx = (ix: any) =>
  new TransactionInstruction({
    programId: new PublicKey(ix.programId),
    keys: ix.accounts.map((a: any) => ({
      pubkey: new PublicKey(a.pubkey),
      isSigner: a.isSigner,
      isWritable: a.isWritable,
    })),
    data: Buffer.from(bs58.decode(ix.data)),
  });

async function sendIxs(instructions: any[]) {
  const { blockhash } = await connection.getLatestBlockhash();
  const message = new TransactionMessage({
    payerKey: funder.publicKey,
    recentBlockhash: blockhash,
    instructions: instructions.map(toIx),
  }).compileToV0Message();
  const tx = new VersionedTransaction(message);
  tx.sign([funder]);
  const sig = await connection.sendRawTransaction(tx.serialize());
  await connection.confirmTransaction(sig, "confirmed");
}

const order = {
  targetChain: "solana",
  contraChain: "solana",
  targetAsset: "So11111111111111111111111111111111111111112", // WSOL
  contraAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
  side: "sell",
  qty: "5",
  orderType: "stop-loss",
  triggers: [{ notionalPrice: "120", triggerType: "lower" }],
  maxPriceImpact: "0.1", // reject execution above 10% price impact
};

const quote = await post("/quote", { ...order, funderAddress: funder.publicKey.toBase58() });

if (quote.svm.ataSetupIxs) await sendIxs(quote.svm.ataSetupIxs);

let delegateFields = {};
if (quote.svm.sponsoredDelegateTx) {
  const tx = VersionedTransaction.deserialize(Buffer.from(quote.svm.sponsoredDelegateTx, "base64"));
  tx.sign([funder]);
  delegateFields = { svmSponsoredDelegateTx: Buffer.from(tx.serialize()).toString("base64") };
} else if (quote.svm.delegateIx) {
  await sendIxs([quote.svm.delegateIx]);
}

const signature = nacl.sign.detached(new TextEncoder().encode(quote.svm.orderMessage), funder.secretKey);
const userSignature = bs58.encode(signature);

const { orderId } = await post("/order", {
  ...order,
  funderAddress: funder.publicKey.toBase58(),
  quoteId: quote.quoteId,
  userSignature,
  svmNonce: quote.svm.nonce,
  svmDeadline: quote.svm.deadline,
  ...delegateFields,
});

console.log("orderId", orderId);

Take-profit and stop

The flow above works unchanged for the other two trigger types. Swap the order block for one of these; everything else (approval or delegation, signing, submit) stays the same. Take-profit: sell 0.05 WETH when it rises to $5,000 or above.

{
  "targetChain": "base",
  "contraChain": "base",
  "targetAsset": "0x4200000000000000000000000000000000000006", // WETH
  "contraAsset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
  "side": "sell",
  "qty": "0.05",
  "orderType": "take-profit",
  "triggers": [{ "notionalPrice": "5000", "triggerType": "upper" }]
}

Stop (breakout buy): spend 100 USDC to buy WETH when it rises to $5,000 or above. On a buy, qty is denominated in the contra asset (USDC).

{
  "targetChain": "base",
  "contraChain": "base",
  "targetAsset": "0x4200000000000000000000000000000000000006", // WETH
  "contraAsset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
  "side": "buy",
  "qty": "100",
  "orderType": "stop",
  "triggers": [{ "notionalPrice": "5000", "triggerType": "upper" }]
}

Add a limit price — limitNotionalPrice or limitCrossPrice, but not both — to any of these for a limit variant (the order becomes a limit order once triggered), and expireTime (an ISO-8601 timestamp) for good-til-time behavior. Omit expireTime for good-til-cancelled. The limit price and the trigger price choose their basis independently. Once a trigger order is live, you can move its prices without cancelling — see Updating Orders. Every type on this page accepts a trigger-price update (“move my stop”), and the -limit variants also accept a new post-trigger execution limit — either or both in one update.

To track the order after submit, poll GET /orders or stream live updates over the Orders WebSocket.

Market Order

Execute immediately at the best price.

Placing Orders

The full parameter reference for every order type.

Agents

End-To-End Flows

Stop-loss execution and price protection

End-to-end example: stop-loss

Take-profit and stop

Market Order

Placing Orders

​Stop-loss execution and price protection

​End-to-end example: stop-loss

​Take-profit and stop

Market Order

Placing Orders

Stop-loss execution and price protection

End-to-end example: stop-loss

Take-profit and stop