Skip to Content
Symmio Trading-SDK — the SDK surface for builders on HyperEVM
CoreTP/SLOverview

TP/SL

Take-profit and stop-loss orders for open positions. Trigger prices are held off-chain by a conditional-order handler (“handler” from here on) — a solver-adjacent service. @symmio/trading-core speaks to the handler over signed HTTP for mutations and a defilytics-protocol WebSocket for state updates. The on-chain contract is only involved when a trigger actually fires and closes the position.

Each method, helper, and type below has its own page with the full signature, parameters, return shape, examples, and (for reads) query options.

The flow — POST + WebSocket

Every TP/SL mutation (new, edit, delete) follows the same two-step handshake:

  1. POST the signed EIP-712 message to the handler. A 200 response means the handler accepted the request — the order is now processing, not yet live.
  2. Wait for the WebSocket report frame with data.successful: true. That frame is the final approval — the state transitions to new (create / edit) or canceled (delete).

The SDK does not poll after a mutation. The WebSocket report is authoritative, and the framework layer (@symmio/trading-react) reconciles confirming → new / canceled off it. If you’re building a UI, subscribe via watchTpSlNotifications and reflect the state change when the matching frame lands.

Same handshake for new / edit / delete — POST accepts, WS confirms. Even a 200 without a WS report means the order is still processing, and the UI should render it as such.

Attaching TP/SL to a new position (instant open)

For a brand-new order that should ship with a TP and/or SL attached, the flow is:

  1. Call instantOpen (or instantOpenAuto). The solver responds with a tempQuoteId (negative integer) that identifies the pending trade before it anchors on-chain.
  2. Immediately POST setQuoteTpSl using that tempQuoteId as the quoteId argument. The handler creates the conditional order against the pre-chain identity.
  3. When the position anchors on-chain and gets its real positive quoteId, the handler transparently maps tempQuoteId ↔ quoteId. The TP/SL row survives the transition — you can read it back with either id.

The React layer wraps this in useInstantOpenWithTpSl, which orchestrates both POSTs and stitches the state into one mutation. Directly in core, it’s two sequential calls: instantOpenAuto → setQuoteTpSl with the returned tempQuoteId.

Concepts

Conditional order — one leg of a TP/SL, addressed by a handler-issued cohQuoteId (e.g. "coh4213"). A quote has at most one active TP and one active SL at a time.

Quote id vs temp quote id — a pre-chain instant-open exists at the handler under a hedger-issued tempQuoteId (negative integer). Once it anchors on-chain, the same order gains a positive quoteId. TP/SL orders are addressable by either id — the handler maps them, so reads and writes can use whichever id the caller has. getQuoteTpSl accepts a negative tempQuoteId so a pre-chain quote’s TP/SL can be read the moment the hedger accepts an instant open.

Notification frame — a report on the WebSocket, normalized into a TpSlNotification. Carries primaryIdentifier (on-chain id or 0), secondaryIdentifier (temp id or 0), conditionalOrderType (take_profit | stop_loss), state, successful, and — on some frames — details.trigger_price. This is the source of truth for state transitions; the SDK does not poll after mutations.

States — the handler emits a small state machine over the WebSocket (the wire values of RawTpSlNotificationState):

StateMeaning
pendingPOST accepted; awaiting handler processing.
newHandler confirmed the order is live (create path).
editHandler confirmed an edit to an existing order.
triggered / triggerThe price condition fired; the close is in flight.
cancel / canceled / cancelledDelete confirmed, or handler dropped the order.
closeTerminal — position closed via this order.

The React layer overlays a confirming synthetic state locally (part of TpSlInfoState) between the POST and the WS report so the UI can show “processing…” without extra plumbing.

Reads

getQuoteTpSl

Raw conditional-order rows for one quote from the handler.

getTpSlConfig

Handler-side rules a TP/SL request must satisfy (min distance, min spread).

getTpSlSigningSpec

EIP-712 typed-data domain + schema for POST (create / edit).

getTpSlDeleteSigningSpec

EIP-712 typed-data domain + schema for the DELETE endpoint.

Writes

setQuoteTpSl

Sign and POST a TP and/or SL order for a quote.

deleteQuoteTpSl

Cancel a live TP or SL by its handler-issued cohQuoteId.

WebSocket

watchTpSlNotifications

Subscribe to live conditional-order state transitions for a SubAccount.

parseTpSlFrame

Parse one raw defilytics frame into a TpSlNotification, or null.

Signing & validation

validateTpSl

Pure pre-submit check of a TP/SL pair against the handler’s rules.

generateTpSlSalt

Random uint256 salt (decimal string) for replay protection.

signTpSlRequest

Sign a message with the session-key wallet into the handler’s request body.

toSignableTpSlMessage

Pad null legs with ZERO_LEG so EIP-712 can hash the message.

buildTpSlDeleteMessage

Build a delete-conditional-order EIP-712 message body.

buildConditionalOrderMessage

Build a create/edit conditional-order EIP-712 message body.

buildConditionalOrderLeg

Build one leg (TP or SL) of a conditional-order message.

priceSlippageCalculation

Shift a trigger price by a slippage percent to derive a leg’s fill price.

Two constants ship alongside these helpers: DEFAULT_TPSL_SLIPPAGE_LOWCAPS (the default slippage percent — see priceSlippageCalculation) and ZERO_LEG (the empty-leg sentinel — see toSignableTpSlMessage).

Types

TpSlNotification

Normalized WebSocket report the SDK delivers to consumers.

RawTpSlNotification

The raw defilytics wire frame retained on TpSlNotification.raw.

QuoteTpSlRow

One conditional-order row as returned by getQuoteTpSl.

QuoteTpSl

Folded per-quote snapshot with both sides merged.

TpSlConfig

Handler /configs/ payload — the rules a request must satisfy.

TpSlSigningSpec

Handler /signing-spec payload — EIP-712 domain + schema.

SetTpSlSide

One side (TP or SL) of a setQuoteTpSl call.

TpSlValidation

Outcome of validateTpSl — ok plus per-side errors.

ValidateTpSlInputs

Inputs to validateTpSl.

TpSlConditionalOrderMessage

Create/edit conditional-order message body (pre-signature).

TpSlConditionalOrderLeg

One leg of a conditional-order message body.

TpSlDeleteMessage

Delete-order message body (pre-signature).

TpSlSignedRequest

Final POST/DELETE body — typed data + signature.

TpSlPriceType

Whether a trigger trips on the mark price or the last-close price.

TpSlInfoState

Lifecycle stage of a TP or SL order, including the synthetic confirming.

Query options

Each read ships a matching …QueryOptions factory and a …QueryKey builder for TanStack Query; each write ships a …MutationOptions factory. See each method’s page for the exact call. These are the primitives @symmio/trading-react’s hooks build on.

Last updated on
Instant ClosegetQuoteTpSl