toadlyBroodle/satring

 ___  __ _| |_ _ __(_)_ __   __ _
/ __|/ _` | __| '__| | '_ \ / _` |
\__ \ (_| | |_| |  | | | | | (_| |
|___/\__,_|\__|_|  |_|_| |_|\__, |
                             |___/  L402 + x402 + MPP

satring.com — curated paid API directory for AI agents. Find, rate, and connect to paid APIs via Lightning (L402), USDC on Base (x402), or Stripe/Tempo (MPP).

Satring helps AI agents and developers discover paid API services that accept payments via the L402 protocol (Bitcoin Lightning), the x402 protocol (USDC on Base), or the Machine Payments Protocol (Stripe/Tempo). Browse the curated directory, submit your service, and let agents find you.

Watch the demo ▶ Watch the 3-minute demo

Why

AI agents can now pay for APIs autonomously using Lightning, USDC, or Stripe. But there's no good way to discover what's available. Satring is the only curated, health-monitored directory with human ratings across all three payment protocols.

Features

• Stats landing page with live directory metrics: protocol breakdown, category coverage, health status, growth
• Browse, search, and filter paid APIs by category, status, and protocol
• Three-protocol support: L402 (Bitcoin Lightning), x402 (USDC on Base), and MPP (Stripe/Tempo)
• Protocol checkboxes on submit/edit forms for multi-protocol services (e.g. L402+MPP)
• Submit services with payment gate (anti-spam), payable via L402, MPP, or x402
• Ratings and reputation system (also payment-gated via any protocol)
• Edit your listing with secure edit tokens
• Recover lost edit tokens via domain verification (.well-known/satring-verify)
• Shared edit tokens across same-domain services; one token manages all your listings
• JSON API for programmatic access and agent queries
• Daily free API quota (10 results/IP/day) with unlimited access via paid bulk endpoint
• Premium endpoints (bulk export, analytics, reputation) gated via L402, MPP, or x402
• Per-service health analytics: uptime percentage, average latency, probe history
• Health probing with automatic protocol detection (L402, x402, MPP, or any combination)
• Service status tracking (live / confirmed / down / unverified)
• Anti-scraping protection with IP-based daily quotas and permanent bans

Quick Start

git clone https://github.com/toadlyBroodle/satring.git
cd satring
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # configure wallet keys, or leave defaults for test mode
uvicorn app.main:app --reload

Open http://localhost:8000

In test mode (AUTH_ROOT_KEY=test-mode), all payment gates are bypassed.

API

Full interactive docs at satring.com/docs.

Free endpoints

Free endpoints return up to 10 results per IP per day. For unlimited access, use the payment-gated /services/bulk endpoint.

# List services (paginated, filterable by category, status, and protocol)
curl "https://satring.com/api/v1/services?category=search&status=live&protocol=L402&page=1&page_size=20"

# Search (also filterable by status and protocol)
curl "https://satring.com/api/v1/search?q=satring&protocol=x402"

# Service details
curl https://satring.com/api/v1/services/my-service

# List ratings
curl https://satring.com/api/v1/services/my-service/ratings

# List categories (use IDs in category_ids when submitting)
curl https://satring.com/api/v1/categories

Payment-gated endpoints

These require payment via L402, MPP (Lightning), or x402 (USDC). Without auth headers, the server returns 402 with challenges for all configured protocols.

Each service requires 1 to 2 category_ids: 1=ai/ml, 2=data, 3=finance, 4=identity, 5=media, 6=social, 7=search, 8=storage, 9=tools.

Option A: L402 (Lightning)

# Submit a service via L402
curl -X POST https://satring.com/api/v1/services \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "url": "https://api.example.com",
    "pricing_sats": 10,
    "pricing_model": "per-request",
    "protocol": "L402",
    "category_ids": [1, 2]
  }'

Option B: MPP (Lightning via Payment auth scheme)

# Submit a service via MPP
curl -X POST https://satring.com/api/v1/services \
  -H "Authorization: Payment <base64url-encoded-credential>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "url": "https://api.example.com",
    "pricing_sats": 10,
    "pricing_model": "per-request",
    "protocol": "L402",
    "category_ids": [1, 2]
  }'

The MPP flow: hit the endpoint without auth to get a 402 with WWW-Authenticate: Payment containing a BOLT11 invoice, pay via Lightning, then retry with Authorization: Payment <credential> containing the preimage. See the MPP spec for full details.

Option C: x402 (USDC on Base)

# Submit a service via x402
curl -X POST https://satring.com/api/v1/services \
  -H "PAYMENT-SIGNATURE: <base64-encoded-payment-json>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "url": "https://api.example.com",
    "pricing_usd": "0.50",
    "pricing_model": "per-request",
    "protocol": "x402",
    "x402_network": "eip155:8453",
    "x402_asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "x402_pay_to": "0xYourWalletAddress",
    "category_ids": [1, 2]
  }'

Multi-protocol listings

A single service can support multiple payment rails. Use + to combine protocols (e.g. L402+x402, L402+MPP, x402+MPP, L402+x402+MPP) and include the required fields for each:

# L402 + MPP multi-protocol service
curl -X POST https://satring.com/api/v1/services \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dual API",
    "url": "https://api.example.com",
    "pricing_sats": 10,
    "pricing_model": "per-request",
    "protocol": "L402+MPP",
    "mpp_method": "tempo",
    "mpp_currency": "usd",
    "category_ids": [1, 2]
  }'

Multi-protocol services appear in search results when filtering by any of their constituent protocols.

MPP-only listing

# Pay with any supported protocol (L402, MPP, or x402)
curl -X POST https://satring.com/api/v1/services \
  -H "Authorization: Payment <base64url-credential>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MPP API",
    "url": "https://mpp.api.example.com",
    "protocol": "MPP",
    "mpp_method": "tempo",
    "mpp_realm": "api.example.com",
    "mpp_currency": "usd",
    "category_ids": [1]
  }'

MPP fields: mpp_method (required: "tempo", "stripe", "lightning", "custom"), mpp_realm (optional), mpp_currency (optional).

Other gated operations

# Link to existing service on same domain (L402, MPP, or x402 auth)
curl -X POST https://satring.com/api/v1/services \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Other API",
    "url": "https://api.example.com/v2",
    "existing_edit_token": "your-token-from-first-service"
  }'

# Edit a service
curl -X PATCH https://satring.com/api/v1/services/my-api \
  -H "X-Edit-Token: your-edit-token" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

# Bulk export (use -i to see payment challenges in headers)
curl -i https://satring.com/api/v1/services/bulk

# Directory analytics (totals, health overview, pricing stats by protocol, growth, leaderboards, route usage)
curl -i https://satring.com/api/v1/analytics

# Per-service health analytics (uptime %, avg latency, probe history)
curl -i https://satring.com/api/v1/services/my-service/analytics

# Service reputation (rating distribution, monthly trends, peer comparison, review activity)
curl -i https://satring.com/api/v1/services/my-service/reputation

Token recovery

If you lose your edit token, or want to edit a pre-seeded endpoint, prove domain ownership to get a new one:

# 1. Generate a challenge
curl -X POST https://satring.com/api/v1/services/my-service/recover/generate

# 2. Place the challenge code at your-domain.com/.well-known/satring-verify

# 3. Verify — new token is applied to ALL services on the same domain
curl -X POST https://satring.com/api/v1/services/my-service/recover/verify

Rate limiting

Free API endpoints are rate limited at 6 requests/minute (burst of 5) with a daily quota of 10 results per IP. Payment-gated endpoints have a higher limit of 60 requests/minute (burst of 10). Rate-limited responses include a Retry-After header indicating how many seconds to wait.

Health probes

The directory probes listed services periodically to detect protocol support and liveness. Probes detect L402 (WWW-Authenticate: L402/LSAT), x402 (PAYMENT-REQUIRED header), and MPP (WWW-Authenticate: Payment) protocols automatically. Probes attempt HEAD first, then fall back to GET if HEAD returns 405. Many nginx/reverse proxy configs reject HEAD by default, so if your service shows as "confirmed" rather than "live", this is normal and expected.

Configuration

Environment variables (see .env):

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./db/sr.db	Database connection string
PAYMENT_URL	—	Wallet instance URL
PAYMENT_KEY	—	Wallet invoice/read key
AUTH_ROOT_KEY	test-mode	Set to wallet key for production; test-mode bypasses payments
AUTH_SUBMIT_PRICE_SATS	1000	Cost to submit a service
AUTH_REVIEW_PRICE_SATS	10	Cost to submit a review
AUTH_BULK_PRICE_SATS	5000	Cost for bulk export
AUTH_ANALYTICS_PRICE_SATS	500	Cost for directory analytics
AUTH_SERVICE_ANALYTICS_PRICE_SATS	50	Cost for per-service health analytics
AUTH_REPUTATION_PRICE_SATS	100	Cost for reputation lookup
AUTH_PRICE_SATS	100	Default price for premium endpoints
X402_FACILITATOR_URL	https://facilitator.xpay.sh	x402 facilitator endpoint
X402_PAY_TO	—	USDC wallet address (empty = x402 disabled)
X402_NETWORK	eip155:8453	Chain ID (default: Base mainnet)
X402_ASSET	0x8335...2913	USDC contract address on Base
AUTH_SUBMIT_PRICE_USD	0.50	x402 cost to submit a service
AUTH_REVIEW_PRICE_USD	0.01	x402 cost to submit a review
AUTH_BULK_PRICE_USD	2.50	x402 cost for bulk export
AUTH_ANALYTICS_PRICE_USD	0.25	x402 cost for directory analytics
AUTH_SERVICE_ANALYTICS_PRICE_USD	0.025	x402 cost for per-service health analytics
AUTH_REPUTATION_PRICE_USD	0.05	x402 cost for reputation lookup

Scraper

The scraper discovers and indexes services from multiple sources:

# Scrape all 8 sources, probe endpoints, write to CSV for review
python db/scrape_sources.py

# Dry run (scrape + probe, print results, don't write CSV)
python db/scrape_sources.py --dry-run -v

# Re-probe existing DB services and update status
python db/scrape_sources.py --recheck

# Ingest reviewed CSV into the database
python db/scrape_sources.py --add-scraped

Sources: Lightning Faucet catalog, awesome-L402, Lightning Faucet Registry, domain crawler, GitHub search, x402.org ecosystem, awesome-x402, mpp.dev registry.

MCP Server

The satring-mcp package lets AI agents discover and compare services from the directory programmatically via the Model Context Protocol.

pipx install satring-mcp
# or
pip install satring-mcp

Then add to your Claude Desktop claude_desktop_config.json or Claude Code .claude/settings.json:

{
  "mcpServers": {
    "satring": {
      "command": "satring-mcp"
    }
  }
}

Tools: discover_services, list_services, get_service, get_ratings, list_categories, compare_services, find_best_service. See mcp/README.md for full docs.

PyPI

Tech Stack

• FastAPI + Jinja2 + HTMX: server-rendered with progressive enhancement
• SQLAlchemy (async) + SQLite: simple, no external DB needed
• L402 / Macaroons: Lightning-native authentication via pymacaroons
• x402 / USDC on Base: stablecoin payments via xpay.sh facilitator
• MPP: Machine Payments Protocol Lightning payments via the Payment HTTP auth scheme
• Tailwind CSS (browser CDN): terminal-themed green-on-black UI

Contributing

All contributions welcome!

License

MIT