{
  "name": "l402.services",
  "description": "Pay-per-query lookup APIs. Lightning-gated via L402. No accounts, no API keys.",
  "protocol": "L402",
  "l402_enabled": true,
  "services": {
    "geoip": {
      "url": "/geoip/{ip}",
      "method": "GET",
      "auth": "L402",
      "cost_sats": 1,
      "token_window_seconds": 600,
      "description": "IP geolocation — country, city, ASN, coordinates, timezone. 1 sat unlocks unlimited lookups for the token window.",
      "consumption": {
        "type": "api_response",
        "action": "Parse the JSON response directly. Each field is a property of the IP address."
      }
    },
    "predictions": {
      "url": "/predictions/info",
      "method": "GET",
      "auth": "none (info is free, signals are L402)",
      "description": "Prediction market intelligence from Polymarket — probability shifts, high-confidence outcomes, volume spikes, and AI-powered oracle analysis.",
      "tiers": [
        {
          "endpoints": [
            "/predictions/signals",
            "/predictions/markets",
            "/predictions/market/{id}"
          ],
          "cost_sats": 10,
          "token_window_seconds": 600,
          "model": "time-window",
          "description": "Raw signals and market data. One payment unlocks all data endpoints for the token window."
        },
        {
          "endpoints": [
            "/predictions/oracle"
          ],
          "cost_sats": 250,
          "token_window_seconds": 60,
          "model": "per-request",
          "description": "Live AI analysis of prediction markets with written intelligence briefing."
        }
      ],
      "endpoints": [
        {
          "url": "/predictions/info",
          "auth": "none",
          "description": "Service overview + endpoint list"
        },
        {
          "url": "/predictions/signals?shift_min=&confidence_min=&volume_min=&hours=&limit=",
          "auth": "L402",
          "cost_sats": 10,
          "description": "Current signals: probability shifts, high confidence, volume spikes"
        },
        {
          "url": "/predictions/market/{conditionId}",
          "auth": "L402",
          "cost_sats": 10,
          "description": "Historical probability snapshots for one market"
        },
        {
          "url": "/predictions/markets",
          "auth": "L402",
          "cost_sats": 10,
          "description": "All tracked markets with latest probability"
        },
        {
          "url": "/predictions/oracle",
          "auth": "L402",
          "cost_sats": 250,
          "model": "per-request",
          "description": "AI-powered market analysis and intelligence briefing"
        }
      ],
      "consumption": {
        "type": "api_response",
        "action": "Parse the JSON response. Data endpoints share a token window. Oracle is per-request."
      }
    },
    "lightning_graph": {
      "url": "/ln/info",
      "method": "GET",
      "auth": "none (info is free, queries are L402)",
      "description": "Lightning Network graph data — node info, channels, search, routing, channel partner suggestions. GET /ln/info for full endpoint list.",
      "tiers": [
        {
          "endpoints": [
            "/ln/node/{pubkey}",
            "/ln/node/{pubkey}/channels",
            "/ln/search"
          ],
          "cost_sats": 10,
          "token_window_seconds": 600,
          "model": "time-window",
          "description": "Basic node lookups and search."
        },
        {
          "endpoints": [
            "/ln/health/{pubkey}",
            "/ln/reachable/{pubkey}",
            "/ln/decode"
          ],
          "cost_sats": 15,
          "token_window_seconds": 300,
          "model": "time-window",
          "description": "Node analysis — health scores, reachability checks, invoice decode with enrichment."
        },
        {
          "endpoints": [
            "/ln/route",
            "/ln/suggest",
            "/ln/changes"
          ],
          "cost_sats": 25,
          "token_window_seconds": 300,
          "model": "time-window",
          "description": "Graph computation — pathfinding, partner recommendations, daily diffs."
        }
      ],
      "endpoints": [
        {
          "url": "/ln/info",
          "auth": "none",
          "description": "Network overview + endpoint list"
        },
        {
          "url": "/ln/suggest/first-channel?budget={sats}",
          "auth": "none",
          "description": "First channel recommendations for new nodes (free)"
        },
        {
          "url": "/ln/node/{pubkey}",
          "auth": "L402",
          "cost_sats": 10,
          "description": "Node info with channel stats"
        },
        {
          "url": "/ln/node/{pubkey}/channels",
          "auth": "L402",
          "cost_sats": 10,
          "description": "Channel list with fee policies"
        },
        {
          "url": "/ln/search?q={query}",
          "auth": "L402",
          "cost_sats": 10,
          "description": "Search nodes by alias or pubkey"
        },
        {
          "url": "/ln/health/{pubkey}",
          "auth": "L402",
          "cost_sats": 15,
          "description": "Node health/reliability score"
        },
        {
          "url": "/ln/reachable/{pubkey}",
          "auth": "L402",
          "cost_sats": 15,
          "description": "L402 services reachable from a node"
        },
        {
          "url": "/ln/decode?invoice={bolt11}",
          "auth": "L402",
          "cost_sats": 15,
          "description": "Invoice decode with graph enrichment"
        },
        {
          "url": "/ln/changes?date={YYYY-MM-DD}&days={N}",
          "auth": "L402",
          "cost_sats": 25,
          "description": "Daily graph diffs — channels opened/closed, fee changes, node churn"
        },
        {
          "url": "/ln/route?from={pubkey}&to={pubkey}&amount={sats}",
          "auth": "L402",
          "cost_sats": 25,
          "description": "Find cheapest route between nodes"
        },
        {
          "url": "/ln/suggest?budget={sats}",
          "auth": "L402",
          "cost_sats": 25,
          "description": "Channel partner recommendations"
        }
      ],
      "consumption": {
        "type": "api_response",
        "action": "Parse the JSON response. Tokens are scoped by tier — basic lookups share one token, compute endpoints share another."
      }
    }
  },
  "stats": {
    "url": "/stats",
    "method": "GET",
    "auth": "none",
    "description": "Basic service stats and database version."
  },
  "l402_flow": [
    "1. GET /geoip/8.8.8.8",
    "2. Receive 402 with WWW-Authenticate: L402 macaroon=\"...\", invoice=\"lnbc...\"",
    "3. Pay the Lightning invoice. Your wallet returns a preimage (64-char hex).",
    "4. Re-request with header: Authorization: L402 <macaroon>:<preimage>",
    "5. Receive geolocation data. Token is valid for 600 seconds — all subsequent lookups are free."
  ],
  "db_version": "2026-02",
  "db_source": "DB-IP Lite",
  "attribution": "IP Geolocation by DB-IP (https://db-ip.com)",
  "human_readable": "https://l402.directory"
}