Dantes Exchange

WHEN: Use when you already have a capability id and need schema, price, and when-to-use before paying. NOT for: Do not use to execute the scan. Returns: The full manifest — input and output schema, support envelope, limitations — plus the price and access class on THIS endpoint, and the routing block.

WHEN: Use when you need the dated forward-return pack for a listed skill (n, window, as-of). NOT for: Do not use as a live scan and do not treat evidence as today’s hits. Returns: Semantic evidence (does it do what it says) kept strictly separate from historical economic evidence (what was measured about the population it describes) — never combined into a score. Universe-relative and vs-benchmark figures appear only where they were actually measured; a capability with no economic measurement returns NOT_MEASURED rather than a borrowed figure.

WHEN: Use when your user asks what Dantes rates a NAMED stock, why, or for the analyst’s written report — "what does Dantes say about WING", "is NVDA a Strong Buy", "read me the Dantes report on PRLB". Up to 20 names; the written report is inlined for up to 3 names at a time. NOT for: Do not use it to rate a market or a screen’s survivors wholesale — Dantes grades only names that reached a desk through a setup, so most names are blank; a blank is UNRATED, never Hold. It is not Street consensus (that is analyst-actions) and it is not investment advice. Returns: { ok, rows: [{ symbol, grade, as_of, rated_at, written_as, confidence, setup, capability, report_page, essay | essay_note | why_blank }] } — grade is one of Strong Buy, Buy, Speculative, Hold, Trim, Sell or null; "Buy or better" means the first two only.

WHEN: Use when your user asks about THEIR Dantes Desk, watchlist or locked setups — "what is on my desk", "which of my desk names are Strong Buy", "what did my setups land tonight", "what am I watching". Returns the seat your token is bound to; pass include_archive:true for cards no longer live. NOT for: Not a market screen and not another person’s desk — a token sees only its own seat; without a bound seat it answers no_seat, and then you say so rather than guessing. A card is a dated scan result, never a recommendation; do not present a Desk card as advice to buy. Returns: { ok, desk: { name, cards_live, cards_archived, cards[] ({ symbol, company_name, setup, as_of, live, dantes_grade, grade_as_of, fields[], levels[], note, landed_by, report_page }) , archive? }, watchlist[], setups[] ({ kind, name, armed, grade_filter }) } or { ok: false, reason: no_seat | no_desk }.

WHEN: Use when your user asks whether Dantes grades work — "do Strong Buys beat SPY", "how have Dantes Buy grades done", "is the grade monotone". Returns the forward log of grades Dantes issued live, measured beside SPY over identical windows. NOT for: Not a backtest and not evidence until its own completed-63 Buy-or-better count reaches the threshold it states — quote the as-of date and the n with every number. Not a grade for a name (that is get_dantes_rating). Needs a token; the anonymous endpoint answers token_required. Returns: { ok, as_of, units, scopes: { dantes | storystocks | combined: { label, plain_line, completed_63 { rows, buy_or_better, ended_early, needed_buy_or_better }, by_grade[] ({ grade, rows, horizons { 5|21|63|126|252: { measured, pending, mean_excess, mean_excess_95, median_excess, hit_rate_vs_spy, … } } }), books_vs_spy { strong_buy, buy_or_better: { book, spy: { total_return, cagr, sharpe, sortino, max_drawdown, mar } } }, monotonicity_63 } } } or { ok: false, reason: token_required | no_report | report_unreadable }. Total return, dividends included; say which scope a number is from.

WHEN: Use when you have chosen a listed skill, the user wants names that match it now, and you are ready to pay. NOT for: Do not use for quotes, news, or a chart pattern nowhere on this endpoint (head-and-shoulders — say we don’t have that). Do not refuse a NAMED indicator before get_capability ta-primitives has been read, and do not rebuild a held recipe from memory: the composing rules in the routing guide apply to every call here. Returns: { ok, result } or { ok: false, error }. A priced capability answers an unpaid call with an x402 PaymentRequired naming the exact amount, asset, network and recipient; nothing executes and nothing is charged until a payment verifies. A scan that ran and returned zero names is a completed billable run, not an error.

WHEN: Use when you need what universes / as-of books a skill can run on. NOT for: Do not use to fetch prices or news. Returns: The published datasets with their as-of dates and the universes they enumerate; with a `universe` argument, the member ticker list itself. Raw dataset files are never returned.

WHEN: Use when you concluded, after search_capabilities and get_capability, that Dantes cannot do part of what your user asked — name the missing data column, indicator, history or composition in buildable terms, and what Dantes CAN do of the ask. NOT for: Do not use for a capability that exists and refused your input shape (read its schema and retry), and do not tell your user the gap will be built or when — it is recorded for the operators, never promised. Returns: { ok, recorded } — the missing pieces as written to the operators’ gaps board, free, or { ok: false } with the reason.

WHEN: Use when the user named a setup in trader language and you need to know which Dantes skill matches. NOT for: Do not use to run a scan or to invent a skill we do not list. Returns: Matching capability ids, each with its price, what it takes to run it, and its own when / not_for / returns — plus `not_encoded`, the setups this endpoint does not have.