Trade Modal

The Trade Modal is the global order placement dialog that opens from chat cards, asset detail, watchlist, and notifications.

Find it at: it has no URL of its own. It opens as a global dialog on top of whatever page you're on whenever something triggers it.

---

1. What it is

The Trade Modal is the single shared order form Alphio uses across all three trade rails. It is backed by a global store (useTradeModalStore) that holds the active ticker, symbol type, and locale, and any page can open it without navigation.

A few consequences follow from that design:

• You can open it from anywhere — chat, watchlist, detail pages, notifications — without losing the page you were on.
• It picks up the asset class from symbolType (Stock / ETF / Crypto / Metals / Forex / Hyperliquid) and renders the matching form (equity / perp / prediction).
• Closing it does not navigate away or unmount the page underneath.

---

2. Entry points

The Trade Modal opens from four kinds of surfaces:

• Chat cards. When Alphio AI returns a stock / crypto / ETF / event card in chat, the card's Trade or Buy / Sell action calls openTradeModal(ticker, symbolType, locale).
• Asset detail pages. Every supported asset detail page (/stock/:symbol, /crypto/:symbol, /etf/:symbol, /stock-hk/:symbol, /forex/:symbol, /metals/:symbol, Hyperliquid perp page, Polymarket event page) has a Buy / Sell or Trade button that opens the modal pre-filled with that symbol.
• Watchlist rows. Each watchlist row exposes a trade action; clicking it opens the modal with the row's ticker.
• Notifications. A notification that includes an action button (signal alert, copy-trade fire, etc.) can launch the modal directly from the notification.

The entry point determines which fields are pre-filled, but all of them route through the same modal.

---

3. Fields

The fields shown inside the Trade Modal depend on the rail derived from symbolType:

Field	Stock / ETF	Hyperliquid perp	Prediction event
Asset	Symbol (pre-filled from caller)	Perp ticker (pre-filled)	Event + outcome (YES / NO)
Side	Buy / Sell	Long / Short	YES / NO
Amount	Quantity or dollar amount	Position size (USDC)	Number of shares
Leverage	n/a	Leverage selector	n/a
Price type	Market / Limit / Stop / Stop-Limit	Market / Limit	Market / Limit (CLOB)
Time-in-force	Day / GTC	n/a (perp)	n/a (event resolves)

The modal validates inputs locally before any network call. Per-rail behaviour beyond this table is documented on each rail's deep-dive page (Stock Trading, Hyperliquid Perpetuals, Prediction Markets).

---

4. Confirmation flow

The Trade Modal always goes through a check → preview → submit → confirmation sequence so an order never leaves your client without being seen.

1. Check. The modal validates inputs locally and, where the rail supports it, sends a pre-flight check (e.g. SnapTrade check-equity-order-impact for stocks).
2. Preview. The modal shows estimated price, fees, and resulting balance / position impact for you to confirm.
3. Submit. On confirm, the modal calls the rail's place-order endpoint with the validated payload.
4. Confirmation. The modal shows the order status (Pending / Filled / Rejected) and the order appears in the corresponding rail's history.

On a successful submit the modal closes automatically and the order surfaces in the rail-specific order list.

---

5. Cancellation

Closing the Trade Modal without submitting clears the store (closeTradeModal) and discards the form. Nothing is sent to any backend, and the page underneath is untouched.

If you've already submitted an order, you cancel it from the rail's order list — not from the modal:

• Stock orders: from the 24-hour orders list on the broker account page (see Stock Trading).
• Hyperliquid perp orders: from the perp positions view.
• Prediction orders: from the Polymarket event detail.

---

6. Limitations

A few things the Trade Modal deliberately does not do:

• No URL. The modal has no route of its own — you cannot link to "the Trade Modal" directly. Link to the asset detail page or chat card that opens it instead.
• One asset at a time. The modal handles a single ticker. Bulk / multi-leg orders are not supported.
• No amend. To change an existing order's price or quantity, cancel it from the rail's order list and place a new one through the modal.
• Rail prerequisites still apply. The modal opens regardless of connection state, but submitting a stock order requires a connected broker, a perp order requires a bound Hyperliquid wallet, and a prediction order requires USDC on Polymarket. Missing prerequisites are surfaced as errors during the Check step.

warning

The modal renders the form based on symbolType passed in by the caller. If a caller opens it with a missing or wrong symbolType, the form may default to the equity layout. This is normally transparent to users but worth noting if you integrate a new entry point.