{
  "name": "Nanotoll API",
  "description": "Single public REST API for nanotoll.dev: account registration and key issuance, free trial keys, credit balance and usage, payment history, live pricing/limits discovery, server-side receipt verification, and the compress endpoint. One API key, one balance, billed in USDC on Base L2.",
  "version": "0.1.0",
  "url": "https://api.nanotoll.dev",
  "homepage": "https://api.nanotoll.dev",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransition": false
  },
  "authentication": {
    "type": "bearer",
    "description": "API key passed as `Authorization: Bearer *** Obtain a key via POST https://api.nanotoll.dev/api/v1/register (or a free trial key via POST /api/v1/trial). One key, one balance; billed calls require sufficient USDC credit (Base L2) and return HTTP 402 otherwise."
  },
  "endpoints": [
    {
      "name": "register",
      "method": "POST",
      "path": "/api/v1/register",
      "auth": "none",
      "description": "Self-register an account. Returns an API key and a USDC funding address. No body required. Rate-limited per IP."
    },
    {
      "name": "trial",
      "method": "POST",
      "path": "/api/v1/trial",
      "auth": "none",
      "description": "Request a free trial key. Emails a verification code. One trial per email address and per IP."
    },
    {
      "name": "trial_verify",
      "method": "POST",
      "path": "/api/v1/trial/verify",
      "auth": "none",
      "description": "Complete the trial: submit the email and the verification code, receive a trial API key."
    },
    {
      "name": "balance",
      "method": "GET",
      "path": "/api/v1/balance",
      "auth": "bearer",
      "description": "Current credit balance and funding address. Not billed."
    },
    {
      "name": "account",
      "method": "GET",
      "path": "/api/v1/account",
      "auth": "bearer",
      "description": "Full account state for this key: tier (trial/paid/internal), key type, credit balance, expiry, usage totals (requests, chars, amount charged, refunds), trial inflight limit. Not billed."
    },
    {
      "name": "payments",
      "method": "GET",
      "path": "/api/v1/payments",
      "auth": "bearer",
      "description": "Recent onchain payment history. Not billed."
    },
    {
      "name": "limits",
      "method": "GET",
      "path": "/v1/limits",
      "auth": "none",
      "description": "Live compression limits and credit terms, no key needed: max input chars and per-call price per squeeze mode (deterministic free, extractive $0.0008, verified $0.0015), request timeout, the minimum USDC deposit that will be credited, and the free trial grant (amount and expiry in days). Served by the compression service under the same host."
    },
    {
      "name": "receipt_verify",
      "method": "POST",
      "path": "/v1/receipts/verify",
      "auth": "none",
      "description": "Server-side receipt notary. Accepts a signed receipt (plus optionally the raw input and compressed output) and returns a verdict: Ed25519 signature check against the published key, recomputed sha256 hashes, subsequence claim and compression ratio. Open, stateless, no model."
    },
    {
      "name": "compress",
      "method": "POST",
      "path": "/v1/compress",
      "auth": "bearer",
      "description": "Compress text and return the compressed document plus a signed receipt (what was kept, what was dropped, hashes, signature). Requires an API key and is billed per call against the prepaid balance. Flat per-call price by squeeze mode."
    }
  ],
  "mcp": {
    "url": "https://mcp.nanotoll.dev/mcp",
    "transport": "streamable-http",
    "authentication": "bearer",
    "note": "The MCP server uses the same API key and the same prepaid balance as the REST endpoints. Pass the key as an Authorization bearer in the MCP client config; calls are billed to that key's account.",
    "tools": [
      {
        "name": "compress",
        "billed": true,
        "description": "Compress prose and return the compressed text plus a signed receipt (what was kept, what was dropped, hashes, signature). Billed per call by squeeze mode."
      },
      {
        "name": "check_balance",
        "billed": false,
        "description": "Read the account this key bills against: credit balance, USDC funding address, key tier and expiry, usage totals. Takes no arguments and is not billed."
      }
    ]
  },
  "documentation": "https://api.nanotoll.dev/llms.txt",
  "openapi": "https://api.nanotoll.dev/openapi.json",
  "billing": {
    "currency": "USDC",
    "network": "Base (EVM L2)",
    "model": "prepaid credit per account and API key",
    "insufficient_credit": "HTTP 402 on a billed call with no credit left",
    "pricing": "Flat per-call price by squeeze mode: deterministic free, extractive $0.0008, verified $0.0015. Live values always at GET /v1/limits.",
    "top_up": "Send USDC on Base to the funding_address returned by POST /api/v1/register; deposits are credited automatically on confirmation.",
    "free_trial": "One trial key per email and per IP: POST /api/v1/trial then POST /api/v1/trial/verify. $0.50 credit, 30-day expiry."
  },
  "errors": {
    "400": "malformed request",
    "401": "missing or invalid API key",
    "402": "insufficient credit",
    "404": "unknown path",
    "405": "wrong method",
    "413": "payload too large",
    "422": "valid but unusable input (e.g. nothing left to compress)",
    "429": "rate limited"
  }
}