API Reference (Scalar) What only Genka has Pricing
API — same data, two transports
Every route is reachable two ways: REST over plain HTTP, and MCP as native typed tools for Claude Code and other agents. Same auth (X-API-Key), same billing, same response shape. Pick the one that fits your loop — you can mix in the same project.
| You | Pick | Why |
|---|---|---|
| Writing a Python / TS script | REST | One curl per call, predictable JSON envelopes, idempotent |
| Inside Claude Code or Cursor | MCP | Tools are discovered + typed; the agent picks them automatically |
| Building an automation | REST | cron + curl, no client SDK needed |
| Doing exploratory research in chat | MCP | Composes tools across a conversation without re-typing curls |
| Wiring to a notebook | Either | REST via requests, or run an MCP-aware agent and let it dispatch |
REST
REST endpoints →
Every route under /latest/*, with parameters, schemas,
and a try-it-out runner. Stripe-shaped envelope on every 2xx
({ data, meta } with meta.usage). RFC 7807
problem+json on 4xx with code + hint.
curl https://genka.dev/latest/mf/screener?sort=-sharpe_absolute&period=3y&limit=5 \ -H "X-API-Key: $GENKA_API_KEY"
MCP
MCP server →
Official @modelcontextprotocol/sdk 1.29 + @hono/mcp 0.2 Streamable HTTP transport at /mcp. Spec compliance for 2025-06-18 is upstream's job. 23 tools across funds, listed companies, prices, concalls, sectors. Each tool is a thin loopback into the same REST routes — auth, billing, and audit run through one pipeline.
claude mcp add --transport http genka https://genka.dev/mcp \ --header "x-api-key: $GENKA_API_KEY" --scope user
What's the same
| Concept | REST | MCP |
|---|---|---|
| Auth | X-API-Key header | x-api-key header on the MCP transport |
| Tier & cost | Same tierForPath table; X-Genka-Credits-Used on response | Same; tools call back into the REST handler so billing fires once |
| Versioning | genka-Version header pin to a published version | Inherits from the inner REST call |
| Scoped keys | read / write / all + path allowlist | Inner loopback runs keyAllows() exactly once |
| Audit log | Every request logged in api_key_audit | Inner call logs; outer /mcp is non-billable |
| Errors | RFC 7807 problem+json with hint | JSON-RPC error or result.isError with the same hint string |
What's different
| Concept | REST | MCP |
|---|---|---|
| Discovery | GET /latest/capabilities | tools/list + capabilities tool |
| Argument validation | Zod via chanfana — 400 with field-level errors | SDK validates against tool's Zod schema, returns -32602 in result.content[0].text |
| Response shape | { data, meta } envelope | { content: [{type:text, text}], structuredContent: {data, meta}, isError } |
| Streaming | Plain HTTP, no streaming today | SSE supported on GET /mcp — we run stateless, so it's a no-op channel |
| Sessions | None | Stateless — no Mcp-Session-Id. Each request is independent |
When to mix
Common pattern: agent uses MCP in Claude Code to explore (search → mf_get → mf_holdings), then writes a Python script that uses REST for the production cron. Same routes, same data, no rewriting. The Examples page shows both styles — the curls translate one-for-one to MCP tools/call bodies.