{"openapi":"3.1.0","info":{"title":"BitTuitive API","description":"BitTuitive: One Lightning payment, any verified data API, routed to the highest-rated source with automatic fallback. Reliable data for AI agents, paid per call over Lightning (L402): the router buys any scoreboard-verified L402 data API for you (crypto, stocks, weather, traffic and more) with one payment, ranked by quality score and latency; plus BitTuitive's own data feeds (Bitcoin: price, on-chain, fees, Lightning, mining and market signals) and a free quality scoreboard of paid agent APIs. Pay per call (one payment = one fresh response) or buy a 30-day subscription. No API keys, no accounts, no KYC. Free status checks before paying. US stock fundamentals and filings from SEC EDGAR (stock_fundamentals 25 sats, stock_filings 10 sats; cite the SEC, no endorsement). Stock prices are routed only through vetted L402 APIs with a disclosed redistributable source; first-party FMP quotes stay off until licensed.\n\nPayment: L402. Request a paid endpoint without credentials; the server answers HTTP 402. Read the WWW-Authenticate header: L402 macaroon=\"<base64 macaroon>\", invoice=\"<bolt11>\" (a legacy LSAT challenge follows it; macaroon and invoice are also in the JSON body, invoice in X-Invoice). Pay the BOLT11 invoice with any Lightning wallet (it expires after 8 minutes); keep the 32-byte preimage (64 hex chars). Alby, Phoenix and Zeus show the preimage after it settles. Retry the same request with header Authorization: L402 <base64 macaroon>:<preimage_hex> (LSAT prefix also accepted) within 10 minutes of the 402. Each payment buys exactly one successful data response; the next call needs a new payment (or a subscription). Or pay and retry in one step with Lightning Labs lnget: `lnget https://api.bittuitive.ai/api/v1/data/btc_price`. The aperture L402 client works the same way. To pay with NWC (Alby SDK): `const { preimage } = await nwc.sendPayment(invoice)` then retry with Authorization: L402 <macaroon>:<preimage>.\n\nAgent summary: https://api.bittuitive.ai/llms.txt · Manifest: https://api.bittuitive.ai/.well-known/l402.json\n\n402 responses include curl, lnget and NWC/Alby retry examples.","version":"0.2.5"},"paths":{"/api/v1/scoreboard":{"get":{"tags":["scoreboard (free)"],"summary":"Scoreboard Json","description":"Free: ranked quality scores for paid agent APIs (L402 / x402), from Bittuitive's own probes.\nFilter by data_type (bitcoin, crypto, stocks, weather, traffic, other).","operationId":"scoreboard_json_api_v1_scoreboard_get","parameters":[{"name":"protocol","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"L402 or x402","title":"Protocol"},"description":"L402 or x402"},{"name":"data_type","in":"query","required":false,"schema":{"type":"string","enum":["all","bitcoin","crypto","stocks","weather","traffic","other"],"title":"Data Type"},"description":"data type: bitcoin, crypto, stocks, weather, traffic, other (see /api/v1/scoreboard/categories)"},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"category prefix, e.g. bitcoin","title":"Category"},"description":"category prefix, e.g. bitcoin"},{"name":"segment","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"bitcoin-data or other","title":"Segment"},"description":"bitcoin-data or other"},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"title":"Min Score"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Q"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"score|latency|uptime|name|price_sats|price_usd|probes","default":"score","title":"Sort"},"description":"score|latency|uptime|name|price_sats|price_usd|probes"},{"name":"order","in":"query","required":false,"schema":{"type":"string","pattern":"^(asc|desc)$","default":"desc","title":"Order"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"include_unscored","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Unscored"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scoreboard/methodology":{"get":{"tags":["scoreboard (free)"],"summary":"Scoreboard Methodology","description":"Free: how scores are computed.","operationId":"scoreboard_methodology_api_v1_scoreboard_methodology_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/scoreboard/categories":{"get":{"tags":["scoreboard (free)"],"summary":"Scoreboard Categories","description":"Free: data-type categories with counts (discovered / probed / scored) and the top-ranked endpoints in each.","operationId":"scoreboard_categories_api_v1_scoreboard_categories_get","parameters":[{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":0,"description":"top endpoints per category","default":3,"title":"Top"},"description":"top endpoints per category"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scoreboard/{service_id}":{"get":{"tags":["scoreboard (free)"],"summary":"Scoreboard Detail","description":"Free: one service's score, components and recent probe history.","operationId":"scoreboard_detail_api_v1_scoreboard__service_id__get","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","title":"Service Id"}},{"name":"history","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":48,"title":"History"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/scoreboard":{"get":{"tags":["scoreboard (free)"],"summary":"Scoreboard Page","description":"Free: human-readable scoreboard, grouped by data type (?type=bitcoin|crypto|stocks|weather|traffic|other).","operationId":"scoreboard_page_scoreboard_get","parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Type"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/.well-known/l402.json":{"get":{"tags":["discovery (free)"],"summary":"L402 Manifest","description":"Free: machine-readable BitTuitive service manifest.","operationId":"l402_manifest__well_known_l402_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/l402-services":{"get":{"tags":["discovery (free)"],"summary":"L402 Services","description":"Free: L402 capability manifest in the ngx_l402 / 402index discovery format.","operationId":"l402_services__well_known_l402_services_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/llms.txt":{"get":{"tags":["discovery (free)"],"summary":"Llms Txt","description":"Free: concise markdown summary for LLM agents.","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/robots.txt":{"get":{"tags":["discovery (free)"],"summary":"Robots Txt","description":"Free: crawler policy (everything allowed).","operationId":"robots_txt_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/security.txt":{"get":{"tags":["discovery (free)"],"summary":"Security Txt","description":"Free: RFC 9116 security contact.","operationId":"security_txt__well_known_security_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/sitemap.xml":{"get":{"tags":["discovery (free)"],"summary":"Sitemap Xml","description":"Free: sitemap.","operationId":"sitemap_xml_sitemap_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/agent-card.json":{"get":{"tags":["discovery (free)"],"summary":"Agent Card","description":"Free: A2A agent card (discovery metadata; the API itself is REST + L402).","operationId":"agent_card__well_known_agent_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/x402":{"get":{"tags":["discovery (free)"],"summary":"X402 Notice","description":"Free: x402 discovery stub. BitTuitive is L402-only for now; points to the L402 manifest.","operationId":"x402_notice__well_known_x402_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/satring-verify":{"get":{"summary":"Satring Verify","operationId":"satring_verify__well_known_satring_verify_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Root","operationId":"root__get","parameters":[{"name":"accept","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accept"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/endpoints":{"get":{"summary":"List Endpoints","operationId":"list_endpoints_api_v1_endpoints_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/status/{endpoint_name}":{"get":{"summary":"Get Endpoint Status","operationId":"get_endpoint_status_api_v1_status__endpoint_name__get","parameters":[{"name":"endpoint_name","in":"path","required":true,"schema":{"type":"string","enum":["btc_price","btc_oracle","btc_pro","btc_signals","stock_fundamentals","stock_filings"],"title":"Endpoint Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Free pre-flight check (no payment)."}},"/api/v1/data/{endpoint_name}":{"get":{"summary":"Get paid data (L402)","operationId":"get_data_api_v1_data__endpoint_name__get","parameters":[{"name":"endpoint_name","in":"path","required":true,"schema":{"type":"string","enum":["btc_price","btc_oracle","btc_pro","btc_signals","stock_fundamentals","stock_filings"],"title":"Endpoint Name"},"description":"btc_price = 10 sats, btc_oracle = 50 sats, btc_pro = 100 sats, btc_signals = 200 sats, stock_fundamentals = 25 sats, stock_filings = 10 sats"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-agent-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Id"}},{"name":"symbol","in":"query","required":false,"description":"Required for stock_fundamentals, stock_filings: a US ticker. EDGAR accepts any symbol in the SEC company_tickers.json map (featured: SPY, QQQ, NVDA, TSLA, AAPL, MSFT, AMZN, META, GOOGL, AMD, AVGO, MU, PLTR, NBIS, CRWV, RKLB, INTC, ASTS, HIMS, TSM, SOFI, ORCL, HOOD, NFLX, SMCI, COIN, MSTR, IBIT, MARA, GME).","schema":{"type":"string"}}],"responses":{"200":{"description":"Data for the requested tier","content":{"application/json":{"example":{"status":"success","endpoint":"string","data":{"price_usd":"number","price_eur":"number|null","change_24h_percent":"number|null","cross_check":{"sources_compared":"integer","max_deviation_percent":"number|null","consistent":"boolean|null"},"stale":"boolean","timestamp":"string (ISO 8601)"},"metadata":{"category":"string","source":"string","timestamp":"string","agent_id":"string|null","cost_sats":"integer","cache":{"served_from_cache":"boolean","served_as_stale":"boolean","stale_age_seconds":"number"},"sources":["string (upstream data sources used)"]},"attribution":{"text":"string|null (credit line required by the sources)","sources":[{"name":"string","url":"string","notice":"string","required":"boolean"}],"page":"https://api.bittuitive.ai/attributions"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (L402 challenge). Body includes price, what you get, curl and lnget examples, the Authorization: L402 <macaroon>:<preimage_hex> retry header, subscription info and /llms.txt. Pay the invoice and retry with Authorization. Also returned, with a fresh challenge, when a presented credential is invalid (wrong preimage, wrong endpoint, bad macaroon).","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Two values: `L402 macaroon=\"<base64 macaroon>\", invoice=\"<bolt11>\"` then the legacy `LSAT ...` equivalent"},"X-Invoice":{"schema":{"type":"string"},"description":"BOLT11 invoice"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"403":{"description":"Subscription credential valid, but its plan does not cover this endpoint (error=plan_does_not_cover)"},"409":{"description":"The same single-use credential is being redeemed by a concurrent request (Retry-After: 2)"},"429":{"description":"Subscription daily quota used up (error=quota_exceeded; Retry-After = seconds to 00:00 UTC), or too many invoice challenges from this IP (error=rate_limited).","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}}},"404":{"description":"Unknown endpoint"},"400":{"description":"stock tiers: missing or unsupported symbol (EDGAR: not in the SEC ticker map; no invoice issued)"},"503":{"description":"stock tiers: upstream data allowance used up and cache too old (error=upstream_budget_exhausted, Retry-After); no invoice issued"},"502":{"description":"All upstream data sources failed"}},"description":"Paid via L402. Pay per call: btc_price = 10 sats, btc_oracle = 50 sats, btc_pro = 100 sats, btc_signals = 200 sats, stock_fundamentals = 25 sats, stock_filings = 10 sats; each payment buys ONE successful response, redeemable within 10 min of the 402. Or use a subscription credential from /api/v1/subscribe/{plan}. Without a valid credential the server returns 402 with an L402 challenge (price, what you get, curl and lnget examples, retry header, subscriptions, /llms.txt). Free pre-flight: /api/v1/status/{endpoint_name}.","security":[{"L402":[]}],"x-l402-pricing":{"btc_price":{"amount":10,"currency":"sats"},"btc_oracle":{"amount":50,"currency":"sats"},"btc_pro":{"amount":100,"currency":"sats"},"btc_signals":{"amount":200,"currency":"sats"},"stock_fundamentals":{"amount":25,"currency":"sats"},"stock_filings":{"amount":10,"currency":"sats"}}}},"/api/v1/cache/stats":{"get":{"summary":"Get Cache Stats","operationId":"get_cache_stats_api_v1_cache_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/discover":{"post":{"summary":"Discover Endpoint","operationId":"discover_endpoint_api_v1_discover_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required (L402 challenge). Body includes price, what you get, curl and lnget examples, the Authorization: L402 <macaroon>:<preimage_hex> retry header, subscription info and /llms.txt. Pay the invoice and retry with Authorization. Also returned, with a fresh challenge, when a presented credential is invalid (wrong preimage, wrong endpoint, bad macaroon).","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Two values: `L402 macaroon=\"<base64 macaroon>\", invoice=\"<bolt11>\"` then the legacy `LSAT ...` equivalent"},"X-Invoice":{"schema":{"type":"string"},"description":"BOLT11 invoice"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"description":"Preview: endpoint discovery. Paid via L402 (500 sats).","security":[{"L402":[]}]}},"/api/v1/subscriptions":{"get":{"summary":"List Subscriptions","description":"Free: subscription plans (one Lightning payment = N days of access with a daily call quota).","operationId":"list_subscriptions_api_v1_subscriptions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/subscribe/{plan}":{"get":{"summary":"Buy a subscription (L402)","description":"Returns 402 with an L402 challenge for the plan. Pay once; the credential then works on the plan's endpoints. Plans: basic = 5000 sats / 30 days / 100 calls/day (btc_price, btc_oracle), pro = 25000 sats / 30 days / 250 calls/day (btc_price, btc_oracle, btc_pro, btc_signals, stock_fundamentals, stock_filings). With that plan's paid credential this returns its status (200).","operationId":"subscribe_api_v1_subscribe__plan__get","parameters":[{"name":"plan","in":"path","required":true,"schema":{"type":"string","enum":["basic","pro"],"title":"Plan"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (L402 challenge). Body includes price, what you get, curl and lnget examples, the Authorization: L402 <macaroon>:<preimage_hex> retry header, subscription info and /llms.txt. Pay the invoice and retry with Authorization. Also returned, with a fresh challenge, when a presented credential is invalid (wrong preimage, wrong endpoint, bad macaroon).","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Two values: `L402 macaroon=\"<base64 macaroon>\", invoice=\"<bolt11>\"` then the legacy `LSAT ...` equivalent"},"X-Invoice":{"schema":{"type":"string"},"description":"BOLT11 invoice"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"Unknown plan"},"429":{"description":"Too many invoice requests from this IP (error=rate_limited)"},"503":{"description":"Plan sold out (error=sold_out): max active subscriptions reached; no invoice issued. Retry-After set."}},"security":[{"L402":[]}],"x-l402-pricing":{"basic":{"amount":5000,"currency":"sats"},"pro":{"amount":25000,"currency":"sats"}}}},"/api/v1/subscription/status":{"get":{"summary":"Subscription Status","description":"Free: what the presented L402 credential is worth right now (plan, expiry, calls used/remaining today).","operationId":"subscription_status_api_v1_subscription_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid credential"}},"security":[{"L402":[]}]}},"/api/v1/health":{"get":{"summary":"Health","description":"Free liveness probe. This process is up; no upstream or Lightning check.","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health","description":"Free liveness probe. This process is up; no upstream or Lightning check.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/health/upstreams":{"get":{"summary":"Upstreams Health","description":"Free: how much of each free upstream data source's published limit BitTuitive is using (aggregates only).","operationId":"upstreams_health_api_v1_health_upstreams_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/insights/demand":{"get":{"summary":"Demand Insights","description":"Free: what agents ask BitTuitive for (7/30-day aggregates) and how the paid-API market is growing.","operationId":"demand_insights_api_v1_insights_demand_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/stats/paid":{"get":{"summary":"Paid Stats","description":"Free: paid-usage totals (test payments excluded).","operationId":"paid_stats_api_v1_stats_paid_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/insights/requests":{"get":{"summary":"Demand Requests","description":"Free: aggregated agent data-demand requests, ranked by data type. Counts only; no contacts.","operationId":"demand_requests_api_v1_insights_requests_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/request-data":{"post":{"summary":"Request Data","description":"Free: record a data-demand signal. Does not auto-add a source.","operationId":"request_data_api_v1_request_data_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/route/endpoints":{"get":{"summary":"Route Endpoints","description":"Free: every endpoint the router can call right now, with the all-in price.","operationId":"route_endpoints_api_v1_route_endpoints_get","parameters":[{"name":"data_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Data Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/route/status":{"get":{"summary":"Route Status","description":"Free: router switch, caps and today's upstream budget use (aggregates only).","operationId":"route_status_api_v1_route_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/route":{"get":{"summary":"Router: best verified L402 API for data_type/q, with fallback","operationId":"route_best_api_v1_route_get","parameters":[{"name":"data_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Data Type"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (L402 challenge). Body includes price, what you get, curl and lnget examples, the Authorization: L402 <macaroon>:<preimage_hex> retry header, subscription info and /llms.txt. Pay the invoice and retry with Authorization. Also returned, with a fresh challenge, when a presented credential is invalid (wrong preimage, wrong endpoint, bad macaroon).","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Two values: `L402 macaroon=\"<base64 macaroon>\", invoice=\"<bolt11>\"` then the legacy `LSAT ...` equivalent"},"X-Invoice":{"schema":{"type":"string"},"description":"BOLT11 invoice"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"400":{"description":"bad_parameters / missing_input / unknown_data_type (no invoice issued)"},"404":{"description":"not_routable / no_routable_endpoint / no_licensed_price_source (no invoice issued)"},"202":{"description":"running: the paid call is still running; repeat the same request with the same Authorization (Retry-After)"},"409":{"description":"route_in_progress (legacy; 202 is used now)"},"502":{"description":"upstream_failed: every attempt failed; body has a credit token (24 h) worth the payment"},"503":{"description":"route_budget_exhausted (Retry-After) or router_unavailable; no invoice issued"}},"description":"One Lightning payment, any verified data API, routed to the highest-rated source with automatic fallback. Paid via L402: upstream price + max(25%, 5 sats). BitTuitive pays the upstream's L402 invoice, calls it and returns {data, routing}. Other query parameters are forwarded to the upstream. Resend the same URL with the credential after paying. Answers within ~75 s or 202 (poll the same URL with the same credential); 'Prefer: respond-async' returns the 202 at once.","security":[{"L402":[]}]}},"/api/v1/route/{endpoint_id}":{"get":{"summary":"Router: call one verified L402 API through BitTuitive","operationId":"route_one_api_v1_route__endpoint_id__get","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (L402 challenge). Body includes price, what you get, curl and lnget examples, the Authorization: L402 <macaroon>:<preimage_hex> retry header, subscription info and /llms.txt. Pay the invoice and retry with Authorization. Also returned, with a fresh challenge, when a presented credential is invalid (wrong preimage, wrong endpoint, bad macaroon).","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Two values: `L402 macaroon=\"<base64 macaroon>\", invoice=\"<bolt11>\"` then the legacy `LSAT ...` equivalent"},"X-Invoice":{"schema":{"type":"string"},"description":"BOLT11 invoice"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"400":{"description":"bad_parameters / missing_input / unknown_data_type (no invoice issued)"},"404":{"description":"not_routable / no_routable_endpoint / no_licensed_price_source (no invoice issued)"},"202":{"description":"running: the paid call is still running; repeat the same request with the same Authorization (Retry-After)"},"409":{"description":"route_in_progress (legacy; 202 is used now)"},"502":{"description":"upstream_failed: every attempt failed; body has a credit token (24 h) worth the payment"},"503":{"description":"route_budget_exhausted (Retry-After) or router_unavailable; no invoice issued"}},"description":"One Lightning payment, any verified data API, routed to the highest-rated source with automatic fallback. Paid via L402: upstream price + max(25%, 5 sats). BitTuitive pays the upstream's L402 invoice, calls it and returns {data, routing}. Other query parameters are forwarded to the upstream. Resend the same URL with the credential after paying. Answers within ~75 s or 202 (poll the same URL with the same credential); 'Prefer: respond-async' returns the 202 at once.","security":[{"L402":[]}]}},"/providers":{"get":{"summary":"Providers Form","description":"Free: form for API providers to apply to be listed on the router.","operationId":"providers_form_providers_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/providers/terms":{"get":{"summary":"Providers Terms","description":"Free: Provider Terms (DRAFT, pending legal review).","operationId":"providers_terms_providers_terms_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/v1/providers/register-token":{"get":{"summary":"Register Token","description":"Free: short-lived token required by POST /api/v1/providers/register (enforces a minimum fill time).","operationId":"register_token_api_v1_providers_register_token_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/providers/register":{"post":{"summary":"Register Provider","description":"Submit a provider registration. Stays pending until reviewed. Nothing is routed automatically.","operationId":"register_provider_api_v1_providers_register_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/providers":{"get":{"summary":"List Providers","description":"Free: approved registered providers only. No contact emails.","operationId":"list_providers_api_v1_providers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"PaymentRequired":{"type":"object","properties":{"error":{"type":"string","example":"payment_required"},"endpoint":{"type":"string"},"amount_sats":{"type":"integer"},"what_you_get":{"type":"string"},"macaroon":{"type":"string","description":"Base64 (standard) V2 macaroon bound to the invoice payment hash and this endpoint"},"payment_hash":{"type":"string","description":"Hex payment hash of the invoice (informational)"},"invoice":{"type":"string","description":"BOLT11 invoice"},"instructions":{"type":"object","description":"Step-by-step payment: curl, lnget, NWC/Alby, retry header, subscriptions, docs"},"docs":{"type":"string","example":"https://api.bittuitive.ai/llms.txt"},"subscriptions":{"type":"string"}}}},"securitySchemes":{"L402":{"type":"apiKey","in":"header","name":"Authorization","description":"L402 credential: `Authorization: L402 <base64 macaroon>:<preimage_hex>` (LSAT also accepted). The macaroon and invoice come from the 402 challenge `WWW-Authenticate: L402 macaroon=\"...\", invoice=\"...\"`. Spec: https://github.com/lightninglabs/L402"}}},"servers":[{"url":"https://api.bittuitive.ai"}]}