forge_signal_plan
Turn one Forge signal into a concrete order plan for YOUR OWN mirrored account (docs/pm/SIGNAL_MIRRORING.md §2.2). Requires signal_id and an active mirror on that vault (consent first via POST /forge/vaults/{id}/mirrors or the forge_mirror_consent tool); pass account_address only if you have more than one active mirror on that vault. Planning a LIVE signal costs the same as reading it, 10🍒 or $0.10 in USDC over x402 (Cherry -> x402; the free reads never cover it) — free if you already paid to read this exact signal; a plan against a signal older than 24h is always free. The response's charged field says whether THIS call was the one that paid, and historical says whether the signal itself is no longer live (a plan against history is still fully computed, but is not a current instruction). Sizes the order to your account's own NAV at the current mark, checks it against your own caps and the vault's mandate, and refuses it with a reason if it would breach either — including when the vault's own book is currently mirroring_paused (a charge, if any, still happens even when the plan comes back refused this way — see charged; a refusal because a later signal has superseded this one is the one exception and is never charged). This call NEVER places an order; execute the returned plan yourself with your own trade-only agent key, then report the fill with POST /forge/signals/{signal_id}/fills (account_address, filled_at, price, qty, side, and venue_order_id if you have one) — a plain write, no charge, no flag, works for any follower mirroring in their OWN account, and shows up in GET /forge/vaults/{id}/mirrors/me with source:'self_report'. The Torii-linked path (POST /torii/order with sign_mode:'client', then POST /torii/order/record with confirm_id/outcome/this signal's id) is an optional alternative that works ONLY for NightWatch's own single configured operator account (needs NW_TORII_LIVE_ENABLED and that account's own allowlisted key) — an outside follower's own account cannot authenticate to it at all; use the fills endpoint above instead. R78 liquidity safety: for an HL perp market, the plan also refuses new exposure below NW Grade C, caps a single order by both 24h volume and order-book depth (scaling it down, never up), and gates a stock-underlying perp (trade.xyz) to its cash market's hours when its grade is C or provisional. A trim or delisting-close exit signal is evaluated as a REDUCTION — exempt from the grade floor and the session gate — only when your own live position on that market opposes the order and can be read; otherwise ordinary new-exposure rules apply and the exit can be refused too. The response's grade, provisional, capped_notional_usd, impact_bps, session (with next_open when closed), and disposition/retry_at say which and why. A session-deferred plan (disposition:'deferred') is NOT retried for you — that automatic retry is the maker's own passive engine acting on the maker's own legs; call this tool again yourself at session.next_open.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| signal_id | Yes | Forge signal id (from forge_signals) | |
| mandate_id | No | Optional: mandate public id, e.g. m_irifvvp7rr. Sizes the plan inside that Torii Wallet mandate (sent to POST /forge/signals/{id}/plan as mandate_id). | |
| account_address | No | 0x... — only needed to disambiguate when you have more than one active mirror on this signal's vault |