Privy signs; Hyperliquid is canonical truth; protection is an invariant, not a hope

Account state is always queried with the master-wallet address. The execution wallet is a signing mechanism for the master account, not a separate trading account, and must never be passed to account-query endpoints.

t3-trades-poc

All providers reach Hyperliquid through the same HyperliquidGateway interface. No provider-specific exchange client is permitted: Codex, Claude, and OpenCode converge on identical market reads, account reads, and submission paths.

interface HyperliquidGateway {
  resolveMarket(symbol: string): Promise<ResolvedMarket>;
  getMarketSnapshot(market: string): Promise<MarketSnapshot>;
  getMarketHistory(input: MarketHistoryRequest): Promise<MarketHistory>;
  getAccountSnapshot(address: `0x${string}`): Promise<AccountSnapshot>;
  getOpenOrders(address: `0x${string}`): Promise<CanonicalOrder[]>;
  getOrderStatus(
    address: `0x${string}`,
    oidOrCloid: string,
  ): Promise<OrderStatus>;
  submit(action: NormalizedTradingAction): Promise<ExchangeSubmissionResult>;
}

For the ETH-only proof of concept the ETH asset index is resolved at runtime from perp metadata, not copied into source. A metadata change on testnet must not silently break signing.

All actions signed by the execution wallet pass through one serialized nonce lane. The coordinator:

Because the lane is serialized, two harness-requested actions can never race for the same nonce, and a T3 restart can rehydrate the last issued value before submitting again.

Any position increase must include stop information before submission. The invariant is confirmed from exchange state, not inferred from a grouped response or a local record.

Hyperliquid's order action accepts multiple orders and a grouping value of na, normalTpsl, or positionTpsl. A grouped submission is useful for expressing TP/SL relationships, but the HTTP response or the presence of a group is not proof that every requested order is live.

1. Validate. The harness requests a preview containing entry and stop information. T3 validates authority, precision, BBO freshness, loss reservations, and stop direction.
2. Persist before signing. T3 persists the execution record and risk reservation before signing.
3. Submit the grouped action. T3 may submit the IOC parent and linked TP/SL children in one normalTpsl order action after that exact request shape passes testnet validation.
4. Inspect every per-order status. T3 does not assume batch atomicity. Each returned status is recorded.
5. Query canonical state. T3 immediately queries canonical fills, position state, and open orders using the master-account address.
6. Reconcile protection. If the canonical position is non-zero and confirmed protected size is smaller than the position, T3 immediately places or replaces exchange-native reduce-only stop protection for the actual canonical position. The validated implementation may use positionTpsl behavior or an explicitly sized reduce-only trigger order.
7. Confirm protection. T3 confirms trigger direction, reduce-only status, market, and protected size from exchange state.
8. Mark protected. Only then is the execution marked protected.
9. Escalate on timeout. If full protection cannot be confirmed within the bounded reconciliation window, T3 cancels position-increasing orders and begins the deterministic emergency-close procedure.
10. Never shortcut. A 200 response, a present group, or a locally recorded child never substitutes for canonical confirmation.

A resting parent may use linked normalTpsl children, but T3 must subscribe to parent fills and order updates. On any partial fill:

1. Read the canonical position.
2. Determine whether the filled size has live reduce-only stop coverage.
3. Place separate protection for any uncovered filled size.
4. Before manually canceling the remaining parent quantity, ensure the existing partial position has independent confirmed protection.
5. Reconcile again after cancellation because parent-linked children may be canceled with the parent.

After any scale-in fill:

1. Read the canonical net ETH position.
2. Calculate the required protected size and stop direction.
3. Place or replace protection for the canonical position.
4. Confirm the replacement before canceling the last known valid stop whenever the exchange path permits overlapping reduce-only protection safely.
5. Never assume that a previously placed fixed-size trigger automatically resized.

The emergency close is invoked when full protection cannot be confirmed within the bounded reconciliation window. It runs without the harness.

1. Mark the mission blocked and block all position increases.
2. Cancel mission-owned non-reduce-only entry and scale-in orders.
3. Read fresh canonical position and BBO state.
4. Submit a reduce-only marketable IOC order for the current position size.
5. Reconcile fills and the remaining position.
6. Retry with a fresh BBO and remaining size for at most three bounded attempts.
7. If a position remains, preserve or re-establish any valid protection that can be placed, keep the mission blocked, and notify the user with the exact remaining size and failure reason.

Before the protection path is considered complete, record testnet results for:

The exact client library and request shape selected during implementation must still be validated on Hyperliquid testnet. Documentation establishes the intended API behavior; testnet evidence establishes that the T3 integration implements it correctly.