{"openapi":"3.1.0","info":{"title":"Bitcoin Benji API — Mempool Intelligence + AI Utilities","description":"L402-gated APIs: real-time mempool data + AI inference (text, code, vision, embeddings, long-context). Pay per call via Lightning.","version":"2.4.0"},"paths":{"/":{"get":{"summary":"Index","description":"Serve landing page for browsers, JSON for API clients.","operationId":"index__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/api/discovery":{"get":{"summary":"Api Discovery","description":"Force JSON service discovery (even from browsers).","operationId":"api_discovery_api_discovery_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/pricing":{"get":{"summary":"Pricing","operationId":"pricing_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/revenue":{"get":{"summary":"Revenue Endpoint","operationId":"revenue_endpoint_revenue_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/analytics":{"get":{"summary":"Analytics Endpoint","description":"Public analytics dashboard — shows traffic patterns without PII.","operationId":"analytics_endpoint_analytics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/stats":{"get":{"summary":"Stats","operationId":"stats_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/blocks":{"get":{"summary":"Mempool Proxy Simple","operationId":"mempool_proxy_simple_blocks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/whales":{"get":{"summary":"Mempool Proxy Simple","operationId":"mempool_proxy_simple_whales_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/fees":{"get":{"summary":"Mempool Proxy Simple","operationId":"mempool_proxy_simple_fees_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mempool":{"get":{"summary":"Mempool State","operationId":"mempool_state_mempool_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mempool/history":{"get":{"summary":"Mempool History","operationId":"mempool_history_mempool_history_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mempool/predict":{"get":{"summary":"Mempool Predict Endpoint","operationId":"mempool_predict_endpoint_mempool_predict_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/bitcoin/tx-status":{"get":{"summary":"Bitcoin Tx Status","description":"Status of a transaction by txid. Query: ?txid=<hex64>","operationId":"bitcoin_tx_status_bitcoin_tx_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/bitcoin/fee-quote":{"get":{"summary":"Bitcoin Fee Quote","description":"Exact fee quote for a tx. Query: ?inputs=N&outputs=N&target_blocks=N&input_type=p2wpkh|p2pkh|p2sh|p2tr","operationId":"bitcoin_fee_quote_bitcoin_fee_quote_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/whales/stream":{"get":{"summary":"Whales Stream","description":"Server-Sent Events stream of whale alerts. Bearer-only — per-call L402\ndoesn't fit a long-lived connection. Charges 1 sat/minute against the\nbearer key's balance, terminating cleanly when balance runs out.","operationId":"whales_stream_whales_stream_get","parameters":[{"name":"min_btc","in":"query","required":false,"schema":{"type":"number","default":0.0,"title":"Min Btc"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/whales/alerts/subscribe":{"post":{"summary":"Whales Subscribe","description":"Bearer-only. Body {url, min_btc?, label?}. Charges WEBHOOK_SETUP_SATS\nonce + WEBHOOK_PER_DELIVERY_SATS on each fired event (debited later by\nthe gateway's webhook-billing loop, not implemented inline).","operationId":"whales_subscribe_whales_alerts_subscribe_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/whales/alerts/list":{"get":{"summary":"Whales List","description":"Bearer-only. Lists this key's webhook subscriptions.","operationId":"whales_list_whales_alerts_list_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/whales/alerts/{sub_id}":{"delete":{"summary":"Whales Cancel","operationId":"whales_cancel_whales_alerts__sub_id__delete","parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"string","title":"Sub Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keys":{"post":{"summary":"Buy Api Key","description":"Step 1: client posts {sats: int}. We mint a Lightning invoice and\na candidate API key, return 402 with the invoice + a `claim_url` to\npoll. Step 2: client pays, then GETs /api/keys/claim/{payment_hash}\nto redeem the raw key (shown once).","operationId":"buy_api_key_api_keys_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/keys/claim/{payment_hash}":{"get":{"summary":"Claim Api Key","description":"Poll endpoint after paying the bundle invoice. Returns the raw API\nkey once when the invoice settles, then forgets the raw value forever.","operationId":"claim_api_key_api_keys_claim__payment_hash__get","parameters":[{"name":"payment_hash","in":"path","required":true,"schema":{"type":"string","title":"Payment Hash"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keys/balance":{"get":{"summary":"Key Balance","description":"Bearer-authenticated. Returns current balance + spend stats.","operationId":"key_balance_api_keys_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/keys/topup":{"post":{"summary":"Topup Api Key","description":"Bearer-authenticated. Body {sats: int}. Returns invoice + claim URL.\nOnce paid, balance is added to the existing key (no new key issued).","operationId":"topup_api_key_api_keys_topup_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/keys/topup/claim/{payment_hash}":{"get":{"summary":"Claim Topup","description":"Poll after paying a top-up invoice. Credits the original key when\nthe invoice settles.","operationId":"claim_topup_api_keys_topup_claim__payment_hash__get","parameters":[{"name":"payment_hash","in":"path","required":true,"schema":{"type":"string","title":"Payment Hash"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/reconcile":{"post":{"summary":"Reconcile Revenue","description":"Compare LND settled invoices against recorded payments and backfill the gap.","operationId":"reconcile_revenue_reconcile_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/lnd-summary":{"get":{"summary":"Lnd Summary","description":"Live LND invoice summary — settled totals by endpoint. No reconciliation side effects.","operationId":"lnd_summary_lnd_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/x402.json":{"get":{"summary":"Well Known X402","description":"x402-compatible discovery manifest. We speak L402 (Lightning),\nnot USDC, but expose the manifest so x402 indexers/agents register us.","operationId":"well_known_x402__well_known_x402_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/x402":{"get":{"summary":"Well Known X402","description":"x402-compatible discovery manifest. We speak L402 (Lightning),\nnot USDC, but expose the manifest so x402 indexers/agents register us.","operationId":"well_known_x402__well_known_x402_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/{filename}":{"get":{"summary":"Well Known","operationId":"well_known__well_known__filename__get","parameters":[{"name":"filename","in":"path","required":true,"schema":{"type":"string","title":"Filename"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/{path}":{"post":{"summary":"Catch All","operationId":"catch_all__path__post","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string","title":"Path"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Catch All","operationId":"catch_all__path__post","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string","title":"Path"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ai/summarize":{"post":{"summary":"Summarize text (short/medium/long). POST {text, max_length?}","description":"Summarize text (short/medium/long). POST {text, max_length?} — 20 sats or 20000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/sentiment":{"post":{"summary":"Sentiment analysis with confidence score. POST {text}","description":"Sentiment analysis with confidence score. POST {text} — 10 sats or 10000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/translate":{"post":{"summary":"Translate between 100+ languages. POST {text, target, source?}","description":"Translate between 100+ languages. POST {text, target, source?} — 20 sats or 20000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/grammar":{"post":{"summary":"Fix grammar, spelling, punctuation. POST {text}","description":"Fix grammar, spelling, punctuation. POST {text} — 15 sats or 15000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/code-review":{"post":{"summary":"Code review for bugs, security, performance. POST {code, language?}","description":"Code review for bugs, security, performance. POST {code, language?} — 50 sats or 50000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/extract":{"post":{"summary":"Extract structured data (entities/contacts/dates/custom). POST {text, schema?, custom_fields?}","description":"Extract structured data (entities/contacts/dates/custom). POST {text, schema?, custom_fields?} — 25 sats or 25000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/scrape":{"post":{"summary":"Scrape & extract clean text from any URL. POST {url}","description":"Scrape & extract clean text from any URL. POST {url} — 15 sats or 15000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/agent":{"post":{"summary":"General AI agent — any text task. POST {task, context?}","description":"General AI agent — any text task. POST {task, context?} — 30 sats or 30000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/classify":{"post":{"summary":"Classify text into your categories. POST {text, categories[]}","description":"Classify text into your categories. POST {text, categories[]} — 10 sats or 10000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/rewrite":{"post":{"summary":"Rewrite text in different styles. POST {text, style}","description":"Rewrite text in different styles. POST {text, style} — 15 sats or 15000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/explain":{"post":{"summary":"Explain any topic at your level. POST {topic, level?}","description":"Explain any topic at your level. POST {topic, level?} — 25 sats or 25000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/embed":{"post":{"summary":"768-dim embedding vectors (RAG-ready). POST {text} or {texts: [...]}","description":"768-dim embedding vectors (RAG-ready). POST {text} or {texts: [...]} — 2 sats or 2000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/vision":{"post":{"summary":"Vision QA over an image URL. POST {image_url, question?}","description":"Vision QA over an image URL. POST {image_url, question?} — 40 sats or 40000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/ocr":{"post":{"summary":"Extract all visible text from an image URL. POST {image_url}","description":"Extract all visible text from an image URL. POST {image_url} — 25 sats or 25000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/code-generate":{"post":{"summary":"Generate code from a spec. POST {prompt, language?, context?}","description":"Generate code from a spec. POST {prompt, language?, context?} — 40 sats or 40000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/longform":{"post":{"summary":"Summarize huge documents (~50K words) in one flat-fee call. POST {text or url, focus?, max_length?}","description":"Summarize huge documents (~50K words) in one flat-fee call. POST {text or url, focus?, max_length?} — 75 sats or 75000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/transcribe-table":{"post":{"summary":"Convert a table image into JSON rows. POST {image_url}","description":"Convert a table image into JSON rows. POST {image_url} — 35 sats or 35000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}},"/ai/research":{"post":{"summary":"Multi-step web research + cited synthesis. POST {question, max_sources?}","description":"Multi-step web research + cited synthesis. POST {question, max_sources?} — 100 sats or 100000 atomic USDC (x402, Base) per call.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}}}}},"required":false},"responses":{"402":{"description":"Payment required (L402 + x402 dual rail)"},"200":{"description":"Result JSON"}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}