> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/hyperliquid/hyperliquid-bracket-orders.md).

# Bracket orders

## Preconditions

Keep execution disabled unless the independent testnet or mainnet gates in `local-production.md` are deliberately satisfied. Use only the configured signer account and an allowlisted live symbol. Confirm `/api/execution/status` reports fresh portfolio reconciliation, healthy metadata, execution-store schema 8, SQLite integrity `ok`, journal mode `wal`, the intended network and the exact builder scope.

## Review

1. Select an opening long or short. Reduce-only parents cannot create a bracket.
2. Enter the mandatory risk stop and optional take-profit trigger. Long stop must be below entry and TP above entry; short stop must be above entry and TP below entry.
3. Request review. Verify the modal shows `ATOMIC PARENT + TP + SL`, exact normalized parent price/size, TP trigger/limit, SL trigger/limit, network, leverage, notional and fill-only fees.
4. Confirm that each exit is described as fixed-size, reduce-only and limit-triggered. Cancel if the normalized prices or disclosed gap risk are unacceptable.

## Submit and reconcile

1. Confirm once. NIGHTSHIFT consumes the short-lived ticket and selects signer `/v4/orders` only when the complete TP tuple is present.
2. The signer must retain three distinct CLOID scopes before one official SDK `bulk_orders` call with `grouping="normalTpsl"`.
3. Treat the immediate response as an acknowledgement, not finality. Use the authenticated grouped bracket action, which reaches signer `POST /v1/brackets/{parent_cloid}/reconcile` and reads every retained leg together.
4. Accept sibling cancellation as confirmed only when the unfilled protective leg has exact venue status `siblingFilledCanceled`. A filled exit plus an open, pending, canceled, missing or malformed sibling is `attention-required`.
5. If submission is `unknown`, do not resubmit. Use `RECONCILE ALL BRACKET LEGS`; inspect the grouped coverage, parent, TP and SL rows, then inspect the live position if the group remains unavailable or actionable.
6. If the parent partially fills or either child rests after trigger, do not assume child resize or sibling cancellation. Inspect the live position and all retained CLOIDs before issuing a separately reviewed cancel or reduce-only order.

## Group-state response

* `PENDING` means no retained leg has assigned venue order evidence yet.
* `WORKING` means one or more legs are observed and no protective fill is proven.
* `CLOSED` is safe to display only when every retained leg is terminal and either the sole protective exit filled or one filled exit has exact `siblingFilledCanceled` on its sibling.
* `TERMINAL` means all retained legs are terminal without a protective exit fill; it does not by itself say the position is flat.
* `ATTENTION REQUIRED` means bounded-partial evidence, an exit fill with any non-terminal retained leg, an unconfirmed sibling, both exits filled, or a failed protective leg. Keep trading mutations paused until the position and each CLOID are inspected.

Every group remains limited to Hyperliquid's most recent 10,000 account fills. A bounded-partial group cannot be promoted to closed even if one exit fill appears in the retained window.

## Incident checks

* Missing TP fields, duplicate CLOIDs, wrong-side TP limit/trigger, builder mismatch and reduce-only parent must fail before venue I/O.
* Automation V3 must reject a TP-bearing ticket and must never downgrade it to parent-plus-SL.
* A conflicting retained intent or CLOID scope must fail closed.
* A parent scope combined with another intent, account, symbol, builder, retained time or duplicate leg must fail before venue evidence is accepted.
* Missing evidence for any retained leg, malformed group output and generated-contract disagreement must return unavailable/502, not a partial successful group.
* A protective fill without exact `siblingFilledCanceled` on the other child must remain `attention-required`; absence from open orders is not cancellation proof.
* Schema v5 scope rows must migrate to `stop-loss`; only `take-profit`, `stop-loss` or null leg identity was introduced at schema v6 and remains exact in current schema v8.
* A stale/non-current/non-WAL/integrity-failed signer store removes order and emergency authority.

Record only fixed outcome/reason codes and timestamps. Do not copy account addresses, private keys, confirmation tokens, CLOIDs or raw venue responses into incident tickets or logs.

## Verification commands

```powershell
pnpm contracts:check
pnpm --filter web test -- app/api/execution/server.test.ts app/api/execution/route.test.ts
pnpm test:py -- -q
pnpm test:signer
pnpm handoff:verify
pnpm local:restart
pnpm local:health
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/hyperliquid/hyperliquid-bracket-orders.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.