v1

CryptoCheck Security Intelligence API

Developer-first on-chain risk analysis. Authenticate with Authorization: Bearer <api_key> or a Pro/Institutional browser session (dashboard).

Authentication

Authorization: Bearer cc_live_…
X-API-Key: cc_live_…

API keys are created via the developer console / keys endpoint. Free tier keys are limited to 10 requests/day; Pro 1,000/day; Enterprise high cap.

Request signing (optional)

For X-CryptoCheck-Signature, your API key is the root credential, but the server never uses the raw key string as the HMAC key. Both sides derive the same signing key and then compute the request MAC.

1. Signing salt — same UTF-8 string as the server env API_SIGNING_SALT (required in production).
2. Derived key — SHA256( api_key + signing_salt ) (string concatenation, UTF-8 in / SHA-256 out → 32-byte key). The raw API key is not passed to HMAC directly.
3. Message — timestamp + "\n" + raw_request_body (exact bytes you send; use the same timestamp as X-CryptoCheck-Timestamp).
4. Signature — HMAC-SHA256( derived_key, message_utf8 ); send hex or base64 in X-CryptoCheck-Signature.

Development only: if API_SIGNING_SALT is not set, the server uses fallback cryptocheck_dev_api_signing_salt_v1 — use that salt when signing against a local dev server.

POST /api/v1/scan

Full institutional payload (default) or compact platform JSON for integrations.

Platform mode: set "responseMode": "platform" or header Accept: application/vnd.cryptocheck.platform+json.

{
  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "chain": "solana",
  "liquidityUsd": 8500000,
  "topHolderPct": 12,
  "responseMode": "platform"
}

Legacy field mint is still supported. Same response shape as before when responseMode is omitted (UI-compatible).

POST /api/v1/scan/sandbox

Deterministic sandbox analysis — same engine path without serialized on-chain swap simulation. Optional body { "tokenAddress": "…" } to override mint.

POST /api/v1/scan/batch

Bulk platform scans. Max batch: Free 5, Pro 20, Enterprise 100. Consumes daily quota equal to item count. Optional clientRef (≤80 chars) or header X-CryptoCheck-Client-Ref is echoed as client_ref and logged for org/desk traceability. Console UI: /dashboard/batch (Pro+ session).

{
  "chain": "solana",
  "clientRef": "desk-nyc-42",
  "items": [
    { "tokenAddress": "EPjF…", "chain": "solana" }
  ]
}

Priority (Enterprise)

Send X-CryptoCheck-Priority: high — logged for future priority queues.

Public status & SLA

Human page /status and JSON GET /api/status/public (no auth). Shows dependency health, SLA target copy, and optional 30-day rolling probe availability when Upstash Redis is configured and the uptime cron runs.

Webhooks (Enterprise)

Register HTTPS targets from the authenticated dashboard (/dashboard/webhooks). The server POSTs JSON with X-CryptoCheck-Event, X-CryptoCheck-Timestamp, and X-CryptoCheck-Signature: sha256=<hex> (HMAC-SHA256 of the raw body). Events include scan.completed, risk.changed (watchlist cron), optional legacy high_safety_token, and reserved whale.moved.

See docs/api.md for retry behaviour, dashboard CRUD routes under /api/dashboard/webhooks, and the test endpoint.

Error format

{ "error": "string", "code": 400, "reason": "INVALID_INPUT" }

HTTP status codes