Documentation.

Quick start

1. Sign in to the demo and create an API key.
2. Send a question to the research endpoint below.
3. Read the answer alongside its sources, timestamps and cost.

Demo keys expire after 12 hours and work with the research, tool and MCP endpoints on this site. Keep keys server-side. The /v1 data API needs a separate deployment, billing account and key.

Ask a market question. Raven uses the same public research readers and answer guidance as the app: market dossiers, indexed perpetuals, signals, liquidity, wallets, collected news, SEC filings, macro events and saved research. Web, browser, code and configured paid research fill gaps.

curl 'SITE_ORIGIN/api/demo/research' \
  -H 'Authorization: Bearer YOUR_DEMO_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Compare BTC and ETH funding and open interest over the last hour. Include timestamps and coverage gaps."}'

// Run on your server. Keep the key out of browser bundles.
const response = await fetch('SITE_ORIGIN/api/demo/research', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAVEN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({prompt: 'Compare BTC and ETH funding on Hyperliquid.'}),
});
const result = await response.json();
if (!response.ok || result.error) throw new Error(result.error || 'Request failed');
console.log(result.answer, result.sources, result.costUsd);

prompt: 1–1,500 characters. Each call starts a new question; conversation history is not carried between requests.

answer

The response text.

sources / segments

Retrieved evidence and the phrases it supports.

cards

Structured evidence cards with metrics, rows, series, timestamps and stale/partial flags. Render these separately from answer text; never drop their coverage notes.

elapsedMs / costUsd

Runtime and estimated cost. A null cost means unavailable.

toolFailures

Research gaps or tool errors reported during the run.

Tools & MCP

Bring your own agent through stateless Streamable HTTP MCP. Use your demo key as a Bearer token at /api/demo/mcp. The MCP tool raven_research returns the same Raven response as Compare, including sources, cards and estimated cost.

{
  "mcpServers": {
    "raven": {
      "url": "SITE_ORIGIN/api/demo/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DEMO_KEY"
      }
    }
  }
}

Prefer structured evidence for your own model? GET /api/demo/tools lists the current tool names, arguments and schemas. Direct tool calls read data without generating an answer.

curl 'SITE_ORIGIN/api/demo/tools/call' \
  -H 'Authorization: Bearer YOUR_DEMO_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"market_context","arguments":{"coin":"BTC","minutes":60}}'

The MCP configuration above is a generic example; your client may use a different configuration format. Set transport to Streamable HTTP and supply the Bearer header.

Markets

market_registry, market_context, market_tape, market_signals, market_liquidity, market_research

Research feeds

sec_filings, telegram_news, tracked_wallets, research_events, research_history, daily_briefing, research_status

Evidence cards

render_research_card: flow, context, comparison, wallets, depth, liquidity, news, filings and wallet_activity.

Schemas describe supported readers, not guaranteed data coverage. Missing mounts or source history return explicit gaps. Personal watches, private X feeds, memories, user files and signed-in computer sessions require the app’s user/space authorization and are not exposed by shared demo keys. MCP results include both JSON text and structuredContent; isError identifies tool failures. MCP clients render cards according to their own interface.

App parity

Shared research implementation does not mean identical answers or a cloned app session.

Public data tools

The app, hosted Raven API and MCP use the same dispatcher, tool schemas and readers. Feed mounts, timestamps and retained coverage still determine what a deployment can answer.

Answer generation

The app has persistent conversation context. The hosted API and Compare run a separate single-question loop with shared research guidance. Model, context, tool limits and live source updates can change the answer.

Cards & navigation

The same server-generated card data is returned. Compare renders metrics, tables and series; other MCP clients control their rendering. Native app popups and signed-in navigation are not replicated.

Web & paid research

Hosted raven_research can use configured browser, web, code and paid research. Direct data tools do not automatically invoke a model or purchase external data.

Private features

Personal watches, inboxes, private feeds, memories, files and authenticated computers remain app-only. Shared API keys do not inherit a user or space.

A successful request proves that request, not complete historical coverage or answer equivalence. Inspect source errors, stale flags, requested windows and missing intervals.

Query structured data directly. Start with /v1/capabilities for enabled endpoints and pricing, then /v1/perps/markets for coverage.

curl 'https://YOUR_API_HOST/v1/market-context?coin=BTC&minutes=60' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: btc-context-001'

Replace YOUR_API_HOST with your data API deployment host.

coin is an exact market: BTC or xyz:NVDA. Context tools accept minutes from 1 to 10080; the legacy billed context route accepts 1 to 360; the default is 30.

These routes read Raven’s stored market data. Check timestamps, stale flags and coverage. Retained trades are taker executions; wallet rankings are not positions or PnL.

On your configured data API host, retrieve /openapi.json for route schemas. No public billed data host is configured on this site.

Historical candles

GET /v1/perps/history/candles returns shared one-minute history when enabled in capabilities.

coin

Exact venue-qualified market.

start / end

UTC-hour-aligned Unix milliseconds. End is exclusive; maximum 24 hours per request.

coverage

Inspect missing minutes. Requests must precede the configured provider settlement lag.

Raven reuses stored history and fetches missing blocks when configured. API request pricing still applies.

Billing & retries

Send Authorization: Bearer YOUR_API_KEY and an Idempotency-Key with billed data requests.

• Retry the same request with the same key to recover its saved result.
• Use a new idempotency key for a fresh reading.
• Source failures release reserved credits. If saving the billed result fails, the reservation stays pending for reconciliation; retry with the same key.

GET /v1/billing/balance returns available credits in USD microunits: 1,000,000 = $1.

Troubleshooting

401

Missing, revoked or expired key. Generate a new demo key; billing keys and demo keys are not interchangeable.

400 / 413

Check JSON, content type, argument schema and request size. Research questions must be under 1,500 characters.

402 / 409

On the prepaid API: insufficient credit, conflicting retry key or a request still pending. Inspect the error code before retrying.

MCP isError

HTTP success can still contain a tool failure. Check the JSON-RPC error, then result.isError and structuredContent.

Partial or stale

A returned record is not proof of current or complete coverage. Preserve observation times, requested windows and missing intervals. Missing values are not zero.

Lost connection

Hosted demo research has no idempotent replay guarantee. Check whether the original request completed before starting another potentially paid run.