Cancelling Orders

To cancel an open order yourself, use POST /orders/{orderId}/cancel. Like placing an order, cancelling one requires a wallet signature in addition to your API key — but where an order signs the payload returned by the quote, a cancel signs a short plaintext message you construct yourself. The cancel signature is offchain and gasless; no transaction is sent. To change a resting order’s limit price without cancelling it, see Updating Orders.

Automatic cancellation for insufficient funder balance

The execution system also cancels resting orders automatically when the funder wallet no longer holds enough of the input token to keep the order live. This does not require a cancel request or a new wallet signature, and it can happen before a limit price or trigger is reached. The order becomes ORDER_STATUS_CANCELLED with closeReason REASON_INSUFFICIENT_FUNDER_BALANCE. Use the order’s status and closeReason to handle the cancellation.

What integrators should do

Monitor the Orders WebSocket or poll GET /orders/{orderId} and remove cancelled orders from your open-orders UI. An accepted order can be cancelled without a client cancel request.
Tell users that moving or spending the input token can cancel their resting orders. Keep enough input tokens in the funder wallet for the intended remaining execution.
Treat cancellation as terminal. Replenishing the wallet does not reopen the order. If the user wants to trade again, obtain a fresh quote and signature and place a replacement order for the intended remaining amount. Do not automatically recreate cancelled orders.
Preserve any fills that already settled. Automatic cancellation stops only the remaining execution.

The cancel message

Construct this exact UTF-8 string, substituting the orderId returned when the order was placed:

Definitive Flash v1 — Cancel Order
Order: <orderId>

In code, that is one string with a single newline:

const cancelMessage = `Definitive Flash v1 — Cancel Order\nOrder: ${orderId}`;

The message bytes are identical on EVM and Solana; only the signing primitive differs. The server validates the message byte-for-byte, so:

The separator after v1 is an em dash (—, U+2014), not a hyphen.
The line break is a single \n.
<orderId> is the order’s UUID exactly as returned by POST /order.

Send the exact string you signed back as cancelMessage in the request body. The message is plaintext by design: a wallet’s message-signing prompt shows the user precisely which order they are cancelling.

Signing the message

Sign with the funder wallet — the same wallet that signed the order. A signature from any other key is rejected.

Chain	Scheme	`userSignature` format
EVM	EIP-191 `personal_sign` over the message bytes	65 bytes, `0x`-prefixed hex
Solana	Ed25519 over the message bytes	64 bytes, base58

On EVM, the signature is verified onchain against the funder address using ERC-1271 with ERC-6492 support. EOAs, deployed smart accounts, and counterfactual (not-yet-deployed) smart accounts all work — sign with whatever personal_sign flow the wallet provides.

Example

EVM

import { privateKeyToAccount } from "viem/accounts";

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 orderId = "..."; // from POST /order
const cancelMessage = `Definitive Flash v1 — Cancel Order\nOrder: ${orderId}`;
const userSignature = await account.signMessage({ message: cancelMessage }); // EIP-191 personal_sign

const res = await fetch(`${BASE_URL}/orders/${orderId}/cancel`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-definitive-api-key": API_KEY },
  body: JSON.stringify({ cancelMessage, userSignature }),
}).then((r) => r.json());

console.log(res); // { ok: true }

SVM (Solana)

import { Keypair } 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 funder = Keypair.fromSecretKey(bs58.decode(process.env.SOLANA_SECRET_KEY!));

const orderId = "..."; // from POST /order
const cancelMessage = `Definitive Flash v1 — Cancel Order\nOrder: ${orderId}`;
const signature = nacl.sign.detached(new TextEncoder().encode(cancelMessage), funder.secretKey);
const userSignature = bs58.encode(signature); // 64-byte Ed25519 signature

const res = await fetch(`${BASE_URL}/orders/${orderId}/cancel`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-definitive-api-key": API_KEY },
  body: JSON.stringify({ cancelMessage, userSignature }),
}).then((r) => r.json());

console.log(res); // { ok: true }

What a cancel does

A successful cancel takes effect immediately: the order is removed from the execution queue and Flash will not attempt any further fills. The order’s status becomes ORDER_STATUS_CANCELLED with closeReason REASON_USER_REQUESTED, and an update fires on the Orders WebSocket — drop it from any open-orders list. Partial fills are kept. Cancelling a partially filled order (for example, a TWAP mid-run) stops the remaining execution; slices that already settled onchain are final. An attached bracket pair is cancelled separately. Cancelling an entry order does not cancel its attached bracket pair: once the entry has filled at all, the pair stays live protecting what the entry received, and you cancel it by its own orderId. Cancelling the entry before any fill means the pair never activates, and cancelling the pair leaves the entry working, unprotected. See Bracket Orders. The token approval is untouched. Cancelling removes the order, not the onchain approval or delegate, which stays in place for future orders. To remove Flash’s spending authority entirely, revoke the approval onchain — see Cancellation. Cancels are idempotent. Cancelling an already-cancelled order returns 200, not an error, so retrying a cancel after a timeout is safe.

Cancelling several orders at once

POST /orders/cancel cancels up to 25 orders with one signature. The request carries the list of orderIds, a batch cancel message, and one userSignature from the funder wallet. Its rate limit is a separate batchCancel bucket of 1 request per second per API key — see Rate Limits.

The batch cancel message

Definitive Flash v1 — Cancel Orders
Orders:
<orderId>
<orderId>

One lowercase UUID per line, in the same order as orderIds, and no trailing newline. Duplicate ids are rejected rather than de-duplicated, so the signed list and the request list are always byte-identical.

const cancelMessage = `Definitive Flash v1 — Cancel Orders\nOrders:\n${orderIds.join("\n")}`;

Sign it exactly as you would a single cancel message (EIP-191 personal_sign on EVM, Ed25519 on Solana) and echo it back as cancelMessage. One wallet signs the whole batch: ids the signer does not fund come back NOT_FOUND and the rest proceed. A userSignature that is not valid hex or base58 is rejected with 400 INVALID_SIGNATURE before any order is looked up; a well-formed signature that fails to verify is reported per order as NOT_FOUND.

Per-order results

The response is always 200. Each requested id gets a result, in request order:

{
  "results": [
    { "orderId": "…", "ok": true },
    { "orderId": "…", "ok": false, "errorCode": "ALREADY_FILLED" }
  ]
}

ok: true means the order was cancelled or was already cancelled. When ok is false, errorCode stands in for the status a single cancel would have returned:

`errorCode`	Meaning	What to do
`NOT_FOUND`	No such order, not a root Flash order, or the signer is not its funder	Drop it
`ALREADY_FILLED`	The order filled before the cancel landed	Drop it; the order executed
`REJECTED`	The order was already rejected	Drop it
`PENDING_CANCEL`	A cancel is already in flight for this order	Treat as cancelled; confirm with `GET /orders/{orderId}`
`SETTLING`	The order’s status is not known yet	Re-check shortly
`INTERNAL_ERROR`	Transient failure	Retry that id

Treat any other errorCode value as terminal for that order and do not retry it. Each order is cancelled on its own, and its result tells you what happened to it. Otherwise every order behaves exactly as it would with a single cancel. See What a cancel does.

Which orders can be cancelled

Orders in ORDER_STATUS_PENDING, ORDER_STATUS_ACCEPTED, or ORDER_STATUS_PARTIALLY_FILLED can be cancelled. Orders in a terminal status (ORDER_STATUS_FILLED, ORDER_STATUS_REJECTED, ORDER_STATUS_TERMINATED) return 422 — except already-cancelled orders, which return 200 as above. See Order statuses. A cancel can race a fill. If the order fills before the cancel lands, the cancel returns 422 with order already filled — treat that as the order having executed, not as a failure to retry.

Getting Started

How Flash Works

Flash Integration

Specifications

Automatic cancellation for insufficient funder balance

What integrators should do

The cancel message

Signing the message

Example

What a cancel does

Cancelling several orders at once

The batch cancel message

Per-order results

Which orders can be cancelled

​Automatic cancellation for insufficient funder balance

​What integrators should do

​The cancel message

​Signing the message

​Example

​What a cancel does

​Cancelling several orders at once

​The batch cancel message

​Per-order results

​Which orders can be cancelled

Automatic cancellation for insufficient funder balance

What integrators should do

The cancel message

Signing the message

Example

What a cancel does

Cancelling several orders at once

The batch cancel message

Per-order results

Which orders can be cancelled