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

# 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

# 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]
  }'

# 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]
  }'

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+x402",
    "x402_network": "eip155:8453",
    "x402_asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "x402_pay_to": "0xYourWalletAddress",
    "pricing_usd": "0.50",
    "category_ids": [1, 2]
  }'

# Link to existing service on same domain (L402 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

# 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

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