# BitTuitive

> 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.

Base URL: https://api.bittuitive.ai

## Paid endpoints (L402, priced per request)

- `GET https://api.bittuitive.ai/api/v1/data/btc_price` — 10 sats. Bitcoin price only (USD/EUR). Lightweight, fast.
- `GET https://api.bittuitive.ai/api/v1/data/btc_oracle` — 50 sats. Full BTC Oracle: Price, Hash Rate, Mempool, Difficulty, Fees, Block Height.
- `GET https://api.bittuitive.ai/api/v1/data/btc_pro` — 100 sats. Pro Tier: All Oracle data + Lightning Network + Mining Revenue.
- `GET https://api.bittuitive.ai/api/v1/data/btc_signals` — 200 sats. Signals tier: Fear & Greed, BTC/gold ratio, % from ATH, momentum score, volatility regime, 24 h transaction count. BTC dominance, NVT and active addresses return null (no source with a commercial licence).
- `GET https://api.bittuitive.ai/api/v1/data/stock_fundamentals?symbol=NVDA` — 25 sats. SEC EDGAR company facts for one ticker (?symbol=NVDA): revenue, net income, EPS, shares outstanding, cash and debt as reported, plus the ticker-to-CIK map. Any ticker in the SEC company_tickers.json file is accepted. Cached 12-24 hours. Source: U.S. Securities and Exchange Commission (EDGAR).
- `GET https://api.bittuitive.ai/api/v1/data/stock_filings?symbol=NVDA` — 10 sats. Latest SEC EDGAR filings (10-K, 10-Q, 8-K, with amendments and document links) for one ticker (?symbol=NVDA). Any ticker in the SEC company_tickers.json file is accepted. Cached 15-60 minutes. Source: U.S. Securities and Exchange Commission (EDGAR).

Every paid endpoint has a free pre-flight check: `GET https://api.bittuitive.ai/api/v1/status/{endpoint}` (availability, freshness, coverage, price).
Responses are JSON: `{"status":"success","endpoint":...,"data":{...},"metadata":{...}}`. Field lists: https://api.bittuitive.ai/.well-known/l402.json

## How to pay (L402): pay per call

1. Request a paid endpoint without credentials; the server answers HTTP 402.
2. 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).
3. 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.
4. 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).
5. 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.
6. To pay with NWC (Alby SDK): `const { preimage } = await nwc.sendPayment(invoice)` then retry with Authorization: L402 <macaroon>:<preimage>.

Example (curl):
```
curl -sS -i https://api.bittuitive.ai/api/v1/data/btc_price
# 402 + WWW-Authenticate: L402 macaroon="AgE...", invoice="lnbc..."
# pay the invoice with any Lightning wallet, copy the preimage (64 hex chars), then:
curl -sS -H "Authorization: L402 <macaroon>:<preimage_hex>" https://api.bittuitive.ai/api/v1/data/btc_price
```

Or one step with Lightning Labs lnget (pays from your LND or NWC wallet and retries automatically):
```
lnget https://api.bittuitive.ai/api/v1/data/btc_price
```

NWC / Alby SDK:
```
import { webln } from '@getalby/sdk';
const nwc = new webln.NostrWebLNProvider({ nostrWalletConnectUrl });
await nwc.enable();
const { preimage } = await nwc.sendPayment(invoice);
// retry with Authorization: L402 <macaroon>:<preimage>
```

Standard L402 (https://github.com/lightninglabs/L402): the macaroon is a real V2 macaroon whose identifier commits to the invoice's payment hash and to what was bought; off-the-shelf L402 clients (Lightning Labs lnget / aperture client, L402 SDKs) work as-is.
Pay-per-call credentials are single use: one payment = one successful data response, within 10 minutes of the 402 (data changes over time). A used, expired, wrong-endpoint or wrong-preimage credential gets HTTP 402 with a fresh challenge and an `error` of `credential_already_used`, `expired`, `wrong_endpoint` or `invalid_credential` (same status as Lightning Labs aperture, so lnget re-pays automatically). If the upstream data fetch fails (502) the credential is not consumed; retry with it.

## Subscriptions (many calls, one payment)

- `basic`: 5,000 sats for 30 days, 100 calls/day, covers btc_price, btc_oracle. Buy: `GET https://api.bittuitive.ai/api/v1/subscribe/basic`
- `pro`: 25,000 sats for 30 days, 250 calls/day, covers btc_price, btc_oracle, btc_pro, btc_signals, stock_fundamentals, stock_filings. Buy: `GET https://api.bittuitive.ai/api/v1/subscribe/pro`

1. `GET https://api.bittuitive.ai/api/v1/subscribe/{plan}` returns 402 with an L402 challenge for the plan price.
2. Pay it once; send `Authorization: L402 <macaroon>:<preimage_hex>` to any covered endpoint until the plan expires (its `days` after payment).
3. Daily quota resets at 00:00 UTC. Over quota: HTTP 429 + `Retry-After`. Expired: 402 with a `renew` link. Endpoint not in plan: 403.
4. Free usage check: `GET https://api.bittuitive.ai/api/v1/subscription/status` with the same Authorization header (plan, expiry, calls used/remaining today).
Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-Subscription-Expires`.
5. Capacity is limited: each plan has a maximum number of active subscriptions. When full, the subscribe route returns HTTP 503 `sold_out` (with `Retry-After`) and issues no invoice. Asking again from the same client returns the same open invoice.

Limits: requests that create an invoice (402 challenges, subscribe offers) are limited to 60/min per IP (HTTP 429 `rate_limited` + `Retry-After`). Data is served from a cache refreshed at most every 60 s (btc_price, btc_oracle) or 300 s (btc_pro, btc_signals).


## Stocks (SEC EDGAR fundamentals and filings, L402)

`stock_fundamentals` (25 sats) and `stock_filings` (10 sats) take `?symbol=` for any US ticker that maps to a CIK in the SEC `company_tickers.json` file (an unknown or missing symbol returns HTTP 400 before any invoice). Featured tickers (most-discussed US names plus index ETFs and bitcoin-adjacent names, updated 2026-11-15): 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.
Source: U.S. Securities and Exchange Commission (EDGAR). BitTuitive is not affiliated with or endorsed by the SEC; do not treat this as an official SEC product. Company facts are cached 12-24 hours; filings 15-60 minutes. Every response includes the attribution line. Free checks: `GET https://api.bittuitive.ai/api/v1/status/stock_fundamentals`, `GET https://api.bittuitive.ai/api/v1/status/stock_filings`.
The router will only fetch a stock price from a vetted L402 API whose source is disclosed and redistributable; if none pass, `GET https://api.bittuitive.ai/api/v1/route?data_type=stocks` returns `no_licensed_price_source`.

First-party FMP quote/movers/pro stay off until licensed.

## Router: one Lightning payment, any verified data API

One Lightning payment, any verified data API, routed to the highest-rated source with automatic fallback. BitTuitive can call other paid APIs for you. Pay ONE BitTuitive L402 invoice; BitTuitive pays the upstream API's own L402 invoice, calls it and returns its data plus routing metadata (`routing.upstream` = endpoint, host, data type, score; `routing.fee_sats`). Only scoreboard-verified L402 APIs route: recent score >= 80, last probe returned a valid L402 challenge with a known price, GET, upstream price <= 200 sats.
- Price = upstream price + fee, fee = max(25% of the upstream price, 5 sats). The 402 body shows `price_breakdown`.
- `GET https://api.bittuitive.ai/api/v1/route/endpoints` (free): what can be routed now, by data type, with all-in prices, rank and `expected_latency`.
- Ranking: rank = 0.8 x scoreboard score + 0.2 x latency score (probe p50 latency). Generic URL fetchers, scrapers and LLM / chat-completion endpoints never route.
- Timing: a paid call answers within ~75 s. If it is still running you get HTTP 202 (`status: running`, `Retry-After`): repeat the SAME request with the SAME Authorization to collect the result, no new payment. Send `Prefer: respond-async` to get the 202 immediately and poll. Calls that run out of time end in the credit flow below.
- `GET https://api.bittuitive.ai/api/v1/route/<endpoint_id>[?upstream params]` — call one specific API (ids from the list above or the scoreboard). Extra query parameters are forwarded to the upstream.
- `GET https://api.bittuitive.ai/api/v1/route?data_type=weather&q=air+quality[&upstream params]` — BitTuitive picks the best-scoring match and falls back to the next-best of the same data type if it fails.
- Flow: request -> 402 (`WWW-Authenticate: L402 macaroon=..., invoice=...`) -> pay -> resend the SAME URL with `Authorization: L402 <macaroon>:<preimage_hex>` within 10 minutes. Repeating a paid request returns the stored result (no double charge).
- Failures: each upstream is retried once, then the next-best endpoint (best-pick mode). If all fail you get HTTP 502 with a `credit` token worth what you paid, valid 24 h: send `Authorization: Credit <token>` on any route request up to that price.
- Pre-flight errors cost nothing: 404 `not_routable`, 400 `bad_parameters`, 503 `route_budget_exhausted` (BitTuitive's daily upstream budget, resets 00:00 UTC).
- MCP: `route_endpoints` (free) and `route_call` (paid).

## Free: API Scoreboard

Independent, probe-based quality scores (0-100) for paid agent APIs (L402 and x402), from BitTuitive's own unpaid probes, grouped by data type: `bitcoin`, `crypto`, `stocks`, `weather`, `traffic` (incl. maps/transit), `other`.
- [Scoreboard (HTML)](https://api.bittuitive.ai/scoreboard), one tab per data type: `/scoreboard?type=weather`
- [Categories](https://api.bittuitive.ai/api/v1/scoreboard/categories): counts and the top 3 endpoints per data type (`?top=10` for more)
- [Scoreboard JSON](https://api.bittuitive.ai/api/v1/scoreboard): `?data_type=weather&min_score=70`, `?data_type=bitcoin&protocol=L402&q=fees`, `?sort=latency`
- [Methodology](https://api.bittuitive.ai/api/v1/scoreboard/methodology)

## MCP (Model Context Protocol)

Add `https://api.bittuitive.ai/mcp` as a remote MCP server (Streamable HTTP; no auth, no install). Tools: `best_endpoint`,
`scoreboard_search`, `scoreboard_categories`, `scoreboard_endpoint`, `bittuitive_pricing`, `route_endpoints` (all free) and `route_call`,
`get_btc_price`, `get_btc_oracle`, `get_btc_pro`, `get_btc_signals`, `get_stock_fundamentals`, `get_stock_filings` (paid). A paid tool called without
`l402_credential` returns isError=true with a Lightning invoice + macaroon and how-to-pay steps (curl, lnget, NWC/Alby);
pay it with your own wallet and call again with `l402_credential="<macaroon>:<preimage_hex>"`. The server never spends
from your wallet: you pay the invoice yourself. GET https://api.bittuitive.ai/mcp returns a short JSON how-to (or an SSE info event if you
send Accept: text/event-stream); POST JSON-RPC to that URL to use the tools.

## Data sources & attribution

BitTuitive's own feeds use public sources whose terms allow commercial use: gold-api.com (primary live BTC price, gold), mempool.space (BTC price fallback and history, Bitcoin network data), Blockstream Esplora (block data), and alternative.me (Fear & Greed: "Data from alternative.me"). CoinGecko and Blockchain.com are switched off (their free terms do not clearly allow resale), so btc_signals returns null for BTC dominance, NVT and active addresses. BTC prices report their source in `metadata.price_source` (gold-api.com, then mempool.space, then the last good value marked `stale: true` with its age). Every paid response carries an `attribution` block with the credit lines to show next to the data. Full list and terms: https://api.bittuitive.ai/attributions (https://api.bittuitive.ai/attributions.json). Routed calls name their upstream in `routing.upstream`; that data stays subject to its provider's terms.

## Contact

Contact: Use https://contact.bittuitive.ai/ for acquisitions, partnerships, or API provider inquiries. Human contact: hello@bittuitive.ai (or the contact form).

## Machine-readable

- [OpenAPI spec](https://api.bittuitive.ai/openapi.json) · [Interactive docs](https://api.bittuitive.ai/docs)
- [Service manifest](https://api.bittuitive.ai/.well-known/l402.json) · [L402 capability manifest](https://api.bittuitive.ai/.well-known/l402-services)
- [Endpoint list](https://api.bittuitive.ai/api/v1/endpoints) · [Subscription plans](https://api.bittuitive.ai/api/v1/subscriptions)
- [A2A agent card](https://api.bittuitive.ai/.well-known/agent-card.json) (discovery only; the API is REST + L402, not an A2A message endpoint)
- MCP server (remote, Streamable HTTP, no install): `https://api.bittuitive.ai/mcp` (GET = how-to; POST = JSON-RPC) · [server card](https://api.bittuitive.ai/mcp/server-card) · [AI catalog](https://api.bittuitive.ai/.well-known/ai-catalog.json)
- [Liveness](https://api.bittuitive.ai/health) · [Security contact](https://api.bittuitive.ai/.well-known/security.txt)
- [Demand insights](https://api.bittuitive.ai/api/v1/insights/demand) · [Upstream health](https://api.bittuitive.ai/api/v1/health/upstreams)
- x402: not supported yet, L402 only ([notice](https://api.bittuitive.ai/.well-known/x402))