# Vedetta

> Vedetta is a pay-per-call market intelligence API for AI agents. It sells
> sentiment-vs-price divergence verdicts (crypto, US stocks, and macro — indices,
> rates, commodities), live analyst answers, falsifiable predictions, and a
> verifiable track record over the x402 payment protocol — USDC on Base, one
> micropayment per HTTP request. No signup, no API key: an unpaid request
> returns HTTP 402 with machine-readable payment terms; pay with any x402 client
> and retry. Every live analyst read is a flat $0.09 — under every comparable
> AI-tier endpoint; cached reads from $0.005. Payment settles only on a
> successful answer.

Base URL: https://vedetta.dethboy.com
Free: GET /health · GET /openapi.json · GET /llms.txt (this file) ·
GET /install (install page, every access rail) · GET /vedetta.md (hosted agent
card — point any x402/Base-MCP agent at it) · GET /SKILL.md (Nous Research
Hermes Agent skill) · GET /.well-known/skills/vedetta ·
GET /.well-known/x402.json · GET /.well-known/agents.json · GET /registry.json ·
GET /endpoints.txt

## Install in one command
- Hermes Agent (Nous Research):
  hermes skills install https://vedetta.dethboy.com/SKILL.md --name vedetta
- Base MCP / Claude / any assistant with x402 payment tools: read
  https://vedetta.dethboy.com/vedetta.md and follow it (cap payment at the
  listed price).
- Everything else: https://vedetta.dethboy.com/install

## Paid catalog (USDC via x402; authoritative price in each 402 offer)

LIVE DESK — one fresh analyst read per call, 10–180 s, flat $0.09 each:
- GET /v1/ask?q=&asset=SYM — $0.09 — live analyst answer to any market question.
  q ≤500 chars and/or one ticker; best results: both.
- GET /v1/consensus?asset=SYM — $0.09 — sentiment × live price divergence verdict
  with confidence, narrative, receipts. Fresh cache ~10 s; stale cache triggers a
  live refresh inside the call (adds 10–90 s).
- GET /v1/equity?asset=SYM — $0.09 — divergence read on a US STOCK ticker (NVDA,
  TSLA…): social sentiment %, narrative, divergence vs price.
- GET /v1/macro?asset=SYM — $0.09 — analyst read on a MACRO instrument: SPX, VIX,
  US10Y, US2Y, GOLD, OIL, BRENT. Sentiment, narrative, divergence vs price.
- GET /v1/prediction?asset=SYM&horizon=7d — $0.09 — falsifiable prediction:
  claim, confidence %, what proves it wrong, prediction-market anchoring.
  horizon ∈ 24h|7d|30d. Audit past resolution via /v1/track-record.
- GET /v1/pulse — $0.09 — market-wide regime read: sentiment score, regime id,
  macro anchor, top narrative. No parameters.
- GET /v1/theme?theme=NAME — $0.09 — deep-dive on a market theme/narrative
  (e.g. ai-sentiment-divergence, altcoin-decoupling, macro-risk-off; free text
  ≤80 chars): strengthening or fading, which assets it moves.
- GET /v1/trend?asset=SYM&window=7d — $0.09 — price-vs-sentiment trajectory over
  a window (24h|7d|30d): together or diverging, strengthening or fading.
- GET /v1/news-read?asset=SYM — $0.09 — most significant market-moving story on
  the asset + the sentiment read on it.
- GET /v1/house-view?asset=SYM — $0.09 — the desk's current thesis + conviction.
- GET /v1/event?asset=SYM — $0.09 — live trigger probe (price_gap, news_shock,
  social_spike) with 1-10 significance, or a clean event:false.
- GET /v1/odds?asset=SYM — $0.09 — prediction-market odds for the nearest liquid
  market + whether they agree with social sentiment.
- GET /v1/social?asset=SYM — $0.09 — social sentiment: bullish %, social score,
  volume trend vs baseline.
- GET /v1/narrative?asset=SYM — $0.09 — dominant narrative + changed-in-24h flag.

CACHED — instant, no analyst call, no freshness guarantee:
- GET /v1/screener?only=divergent — $0.03 — CROSS-ASSET divergence screener:
  every covered asset with latest cached sentiment %, stance, divergence flag,
  and signal age in one call. Omit ?only for all assets. Start here to pick
  which asset deserves a live read.
- GET /v1/snapshot?asset=SYM — $0.02 — latest cached signal card with age
  timestamp (signal_age_minutes, stale flag).
- GET /v1/history?asset=SYM&limit=50 — $0.01 — cached signal history (timestamped
  sentiment, stance, divergence flags, narratives) — backtest-ready.
- GET /v1/feed?since_id=&asset=&limit= — $0.005 — recent desk posts as a stream.
  Instant return (no long-poll). Poll cheaply; escalate to a live read on change.
- GET /v1/track-record?asset=SYM — $0.01 — verifiable logged history. No accuracy
  is claimed; compute your own from the log.
- GET /v1/route?task=TEXT — $0.005 — TASK ROUTER: describe what you need in
  plain English (≤300 chars) and get the exact endpoint, parameters and price to
  call, plus cheaper cached alternates. Local logic — never fires a live read.

## Exact parameters per query
- asset=STRING: ONE ticker symbol (BTC, ETH, SOL, AI; /v1/equity takes US stock
  tickers like NVDA; /v1/macro takes SPX, VIX, US10Y, US2Y, GOLD, OIL, BRENT).
  Required everywhere except /v1/pulse, /v1/theme, /v1/feed, /v1/track-record
  and /v1/route.
- /v1/ask: q=STRING (≤500 chars, URL-encoded) and/or asset. At least one required;
  one question, one asset per call.
- /v1/prediction: horizon=STRING 24h|7d|30d (optional, default 7d).
- /v1/trend: window=STRING 24h|7d|30d (optional, default 7d).
- /v1/theme: theme=STRING ≤80 chars (REQUIRED; asset param not used).
- /v1/history: limit=INT 1-50 (optional, default 50).
- /v1/feed: since_id=INT (default 0), asset (optional), limit=INT 1-50 (default 20).
- /v1/route: task=STRING ≤300 chars (REQUIRED), asset (optional ticker hint).
- Unknown params are ignored; missing required params return 422 with a hint.

## Recommended spend path (cheapest correct route first)
0. /v1/route $0.005 — unsure which endpoint fits? Ask the router first.
1. /v1/track-record $0.01 — audit the log before trusting anything.
2. /v1/feed $0.005 or /v1/snapshot $0.02 — cheap polling / cached entry.
2b. /v1/screener $0.03 — one call answers "which asset should I look at first?"
3. Any live read — flat $0.09: single-topic probes (/v1/social · /v1/odds ·
   /v1/narrative · /v1/event · /v1/news-read · /v1/house-view · /v1/theme ·
   /v1/trend), structured verdicts (/v1/consensus · /v1/equity · /v1/macro ·
   /v1/prediction · /v1/pulse), or free-form /v1/ask when nothing else fits.
On /v1/event returning event:true, escalate to /v1/consensus or /v1/ask.

## Also on Virtuals ACP (USDC escrow, same engine)
Offerings and job-request JSON fields (all live offerings flat $0.09):
- Live market read (Q&A) — $0.09 — asset (REQUIRED), q (≤500, optional)
- Divergence verdict — $0.09 — asset (REQUIRED)
- Equity divergence read — $0.09 — asset (REQUIRED, US stock ticker)
- Macro read — $0.09 — asset (REQUIRED: SPX, VIX, US10Y, US2Y, GOLD, OIL, BRENT)
- Market prediction — $0.09 — asset (REQUIRED), horizon (24h|7d|30d, optional)
- Market pulse — $0.09 — no fields
- Theme deep-dive — $0.09 — theme (REQUIRED, ≤80 chars)
- Trend read — $0.09 — asset (REQUIRED), window (24h|7d|30d, optional)
- News read · House view · Event probe · Prediction odds · Social sentiment ·
  Narrative check — $0.09 — asset (REQUIRED)
- Sentiment snapshot — $0.05 — asset (REQUIRED)
- Divergence screener — $0.05 — only=divergent (optional)

## Try it (one command, any x402 wallet)
- hermes skills install https://vedetta.dethboy.com/SKILL.md --name vedetta
- npx agentcash try https://vedetta.dethboy.com
- npx awal x402 bazaar search vedetta.dethboy.com   (Coinbase Agentic Wallet CLI)
- circle services search "vedetta.dethboy.com"      (Circle services directory)
- pay curl 'https://vedetta.dethboy.com/v1/snapshot?asset=BTC'
- No wallet yet? curl -si 'https://vedetta.dethboy.com/v1/consensus?asset=BTC'
  returns the 402 offer with exact price, network, and pay_to address.

## Connect
1. GET /health → expect ok:true, analyst_link_connected:true.
2. Call a /v1/* endpoint unpaid → HTTP 402 body = offer (price, network, pay_to).
   Read the network from the offer at runtime; do not hardcode a chain id.
3. Settle via any x402 client SDK, retry with payment attached → 200 JSON.
Payment settles only on a successful (2xx) answer — a 5xx/504 costs you nothing.

## Parse responses
Consensus: asset · verdict (bullish|bearish|neutral) · confidence ·
analyst_sentiment_pct · analyst_stance · price_usd · price_change_24h_pct ·
divergence · narrative · social_score · prediction_odds_pct ·
signal_age_minutes · stale.
Ask: question · raw · sentiment · stance · divergence · summary · quality · extra.
Route: task · recommendation {route,url,price_usd,params,call,why} ·
alternates[] · spend_tip.
Probes: single-topic JSON (see /openapi.json examples); all carry summary +
quality + disclaimer; grounding fields sources/as_of when available.
Quality grades: structured > parsed > keyword-only > raw. Weight structured
highest.

## Docs
- Human one-pager + full agent directives: https://vedetta.dethboy.com/
- Install page (all rails): https://vedetta.dethboy.com/install
- Agent card (hosted plugin): https://vedetta.dethboy.com/vedetta.md
- Hermes Agent skill: https://vedetta.dethboy.com/SKILL.md
- OpenAPI: https://vedetta.dethboy.com/openapi.json
- Machine catalogs: /.well-known/x402.json · /registry.json · /endpoints.txt

## Notes
- Expect ~10 s per paid call (payment verify + settle); live reads run 10–180 s.
- Set HTTP timeout ≥ 200 s on live reads; on 504 retry once (you were not charged).
- Cached routes return in <1 s and never trigger a live read.
- Responses are descriptive research (stance/confidence), not financial advice.
- Contact: vedetta@dethboy.com