Documentation & institutional diligence pack

Base URL & versioning

Authentication

Every /api/v1/* call requires a Bearer API key. Pass it either way:

# Authorization header (preferred)
curl -H "Authorization: Bearer <YOUR_API_KEY>" \
     https://hunterkiller.io/api/v1/health

# or the x-api-key header
curl -H "x-api-key: <YOUR_API_KEY>" \
     https://hunterkiller.io/api/v1/magnets?symbol=BTCUSDT

Keys are issued self-serve by any authenticated subscriber on a pay-as-you-go, pro, or institutional plan: POST /api/keys/mine (the plaintext secret is shown once; store it immediately). Manage your keys with GET /api/keys/mine and POST /api/keys/mine/{key_id}/revoke. An API key can never satisfy an owner or another tenant's session gate. It grants access to the market-wide analytics surface only.

Rate limits

Endpoints

Webhook endpoints require an institutional plan; the read endpoints work for any active key (institutional, pro, or PAYG-with-balance). Self-serve key management (/api/keys/mine) and PAYG balance/top-up (/api/payg/*) authenticate with your logged-in session, not an API key.

Example: calibrated magnets

# request
GET /api/v1/magnets?symbol=BTCUSDT
Authorization: Bearer <key>

# response (shape; PUBLIC fields only, no recipe/internals)
{
  "ok": true,
  "symbol": "BTCUSDT",
  "magnets": { /* calibrated per-magnet reach records */ },
  "basis": "walk-forward empirical reach-rate; descriptive, not a forecast",
  "generated_at": "2026-07-09T…Z"
}

Error codes

MCP: the same data, native to AI agents

Model Context Protocol is the open standard AI agents (Claude, ChatGPT, others) use to call external tools. We expose the same validated data layer as MCP tools — the same handlers, the same recipe-stripping egress, the same key machinery and metering as the REST API above. Every tool response carries the honesty envelope (basis, as-of, per-measurement sample n, "descriptive, not a forecast").

For AI agents: connect in one minute

Everything an agent needs is machine-readable. Discovery lives at GET /.well-known/mcp.json and the agent-native site map at /llms.txt. The endpoint is a stateless streamable-HTTP MCP server (JSON-RPC 2.0 in, JSON out):

{
  "mcpServers": {
    "hunterkiller": {
      "type": "http",
      "url": "https://hunterkiller.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

TradingView: the levels, as a Pine v5 indicator

TradingView offers no API to push drawings into a user's chart, so the integration is a generated Pine v5 script with the current unified zone map baked in: zones as boxes, measured walk-forward react-rate labels (rate + n= + measured/context-only tag, Pro), one timeframe-reactive script, and a native alertcondition() per zone family (fires when price enters a zone). Install guide + sample header: /pine.

Per-tenant isolation

Every request's tenant identity is derived from the authenticated session, never from a request body or query parameter, so a caller cannot assert another tenant's identity. Tenant-scoped database queries carry a tenant-id filter, and the isolation invariant is enforced by an automated static audit plus a dedicated multi-tenant test suite run before shipping changes to request handlers.

Authentication model

• Customer app: session-cookie auth; public marketing and proof surfaces are explicitly allow-listed as cookieless.
• Data API: per-key Bearer tokens (this page, §1). A Data API key resolves to the market-wide analytics surface only and cannot satisfy any owner or cross-tenant gate.
• Control plane & owner surfaces: owner-gated by exact path; the interactive API schema explorer is owner-gated (the public documentation is this page).

No secret egress · recipe-stripping at the boundary

The model's calibration recipe (the conditioning signal, bucket edges, and per-bucket histograms) is stripped by a single shared egress guard before any customer or API response leaves the box. The API documents and returns public result fields only. Credentials are never emitted, logged, or echoed to any customer surface. One restricted-redistribution venue's data is stripped from every API egress to honor its terms of service.

The honesty spine

Our differentiator is provable truth, not marketing. Every customer-facing number is:

• Walk-forward: scored only on data from after the prediction was made, never in-sample.
• Wilson-gated: published as the 95% lower confidence bound with its sample size, never as a flattering point estimate.
• n- and day-cluster-gated: thin or single-day samples are labelled, not headlined.
• Descriptive, not forecast: we publish measured history, including the symbols we switched off and the hypotheses we killed.

A static honesty gate runs before any customer-facing number ships; it rejects inflated baseline-artifact framing, any accuracy claim missing an n and a confidence bound, any not-yet-validated number reaching a customer surface, and any recipe/secret crossing an egress boundary.

Health & status

Sources. Inputs are public exchange market-data feeds: liquidation tapes, order-book/L2, open interest, funding, and trade prints from major venues (Bybit, Binance, OKX, Deribit, Kraken Futures), with a US venue (Coinbase) used as a price/tape reference. These are public market feeds; we ingest them, we do not originate them.

Derived analytics, not raw passthrough. What we publish and sell is our own derived analytics computed from those feeds: calibrated magnet density, walk-forward reach/precision, cross-venue structure aggregates, and liquidation-contagion relationships, never a raw per-venue reseller passthrough of a third party's proprietary product. One restricted-redistribution venue is excluded from the API entirely. This is our standing data-resale posture: we redistribute our transformations, not someone else's raw feed.

Retention. Raw capture corpora are retained on rolling windows with documented per-corpus size and age caps and automatic pruning; append-only research journals are retained long-term and mirrored to offsite backup. Published metrics are recomputed on schedule from these corpora and every figure is dated.

For an institutional evaluation, an API key, a committed SLA, or a security questionnaire, contact support@hunterkiller.io. Live track record: /proof. Frozen metric-definition changelog: /methodology. Pricing: /pricing.