Generate a recommendation
generate_recommendationTrigger YOUR Gambit agent to run a fresh trade recommendation (requires the api:recommend scope on your key — 403 without it). This is a real agent run: it consumes one manual-recommendation quota run for the month (and, unless the answer comes from Gambit's view, spends LLM tokens), and can take up to ~2 minutes — do not call it speculatively. If the call times out, the run may still have completed server-side: check list_recommendations before retrying. watch_instrument PINS the run to that one instrument, so the answer is about YOUR instrument or it says why it could not be, never a different asset. When Gambit answers are enabled for this deployment (they ship off; while off, every watch_instrument takes the selector path below), for a ticker Gambit covers, the answer is Gambit's view of it (the shared view get_gambit returns, under user_facing_recommendation.gambit: subject_id, version, view, plan) plus a sized plan from the user's own limits: with a real lean (|shown_lean| at least 1) on a Hyperliquid listing it is a recommend (decision_source gambit_view, setup_family gambit_view) whose direction follows the lean, entry is the current mark, stop comes from realized volatility around it, invalidation_rule is the view's first dated wrong-if condition, and sizing / trade_ticket come from the user's trade policy; with no edge it is a watch (decision_source gambit_no_edge) whose reason is the no-edge map; a Databento-only id (ref:eq:TICKER) of a ticker with no Hyperliquid listing is answered with the view as a watch, with no ticket and no ledger row (a ref:eq id of a ticker that has a Hyperliquid listing still fails with 422: ask about that listing); with no view yet it is a watch (decision_source gambit_building) and the ticker is queued, so ask again after its next update; when the view is out of date, or its plan cannot be priced or its listing confirmed on this run, it is a watch with pin_status unavailable (retryable). No model runs for a Gambit answer. For any other instrument (and for every instrument while Gambit answers are off), candidate generation and the advisory selector's attention are narrowed to it, the pinned asset is reserved a slot in the comparison set the selector reasons over, and a result about any other instrument is REFUSED rather than returned. An unknown or inactive instrument id, or a non-Hyperliquid id (except the Gambit case above), fails fast with 422. watch_status reports how the pin resolved: pin_status held (the desk evaluated your instrument — state recommend or a reasoned watch on it), not_expressible (evaluated, but it has no expression the desk can back right now, such as a Gambit view with no Hyperliquid listing to trade), unavailable (it never reached the selector; or Gambit has no current view of it, or could not price or confirm it on this run), or substitution_refused (the run produced a different instrument and it was withheld). The last two also set state blocked, put a structured blocked_reason on watch_status, and mark no_recommendation_reason retryable — a retry or a different instrument is the move, not treating the watch as a verdict. Set all_universe to scan the full tradeable universe instead. The response leads with the answer — user_facing_recommendation, whose state is recommend or watch (a reasoned no-trade; no_recommendation_reason then says whether it is retryable, i.e. an operational failure rather than a judgement). A recommend is expression_kind single_instrument (instrument_id + direction, plus sizing/trade_ticket when the desk could size it) or pair_trade (long/short legs, no top-level instrument). recommendation_id is the LEDGER id when the run produced a single-instrument recommend, and respond_to_recommendation takes it; read ledger.status to know how it lists: pending — it appears in list_recommendations(status=pending) (when the same recommendation was already pending it is THAT row's id, ledger.reason existing_pending_primary, and this run's own row is ledger.recorded_row_id); recorded — a DIFFERENT recommendation on the same instrument/direction is already pending, so this id is respondable but NOT in the pending list, and the pending one is ledger.existing_pending_recommendation_id. It is null (ledger.status not_persisted) when nothing was written — every watch, and a pair_trade for now — with the reason under ledger.reason. snapshot_id is the run's audit snapshot, not a recommendation id — do not pass it to respond_to_recommendation. Ledger rows from this tool are advisory: they accept respond_to_recommendation but never the web execute action. The advisory's sizing / trade_ticket (entry, stop, take-profit) is previewed for the user's connected MANUAL wallet and does not transfer to the API trading rail — propose_trade -> confirm_trade is a separate agent-wallet MARKET order that you size and the human approves on its own terms. The pipeline diagnostics are omitted by default — set include_diagnostics: true to also get the world model, freshness checks, and candidate sizing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| all_universe | No | ||
| watch_instrument | No | focus the run on one instrument (e.g. BTC or xyz:TSLA) | |
| include_diagnostics | No | include the full pipeline diagnostics (world model, freshness checks, candidate sizing) alongside the recommendation; default false |