# Sats4AI

> The permissionless communication supercharger for humans and AI agents. 40+ services — AI phone calls, voice synthesis in 602 languages, translation across 119, fax, SMS, transcription, audiobooks, image generation, music, document extraction, and more. Pay per request with Lightning Network. No signup, no API keys, no KYC.

## How to connect

MCP server endpoint: https://sats4ai.com/api/mcp

### Option 1: MCP client (recommended for agents)
Add to your MCP settings JSON:
{
  "mcpServers": {
    "sats4ai": {
      "url": "https://sats4ai.com/api/mcp"
    }
  }
}

Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.
The server handles tool discovery, schema, and invocation via JSON-RPC over HTTP.

### Option 2: L402 HTTP API (for direct HTTP callers)
GET  https://sats4ai.com/api/l402/{service} — returns schema + 402 with Lightning invoice
POST https://sats4ai.com/api/l402/{service} — pay invoice, include Authorization: L402 {macaroon}:{preimage}
No MCP needed. Any HTTP client works. Full docs: https://sats4ai.com/docs

### Option 3: npm package (for Node.js / stdio transport)
npm install sats4ai-mcp
npx sats4ai-mcp
Runs locally, communicates via stdio. Same tools, same payment flow.

## How payments work

Every paid tool requires a Lightning Network micropayment. The flow:

1. Call create_payment(toolName="generate_image") → returns { paymentId, invoice, amountSats }
2. Pay the Lightning invoice (BOLT11)
3. Call generate_image(paymentId="...", prompt="...") → returns result

Free tools (no payment): list_models, get_model_pricing, check_payment_status, check_job_status, get_job_result, get_cost_estimate, get_error_codes, list_planned_services, vote_on_service, confirm_ai_call.

## Available tools and pricing

### Instant tools (result returned immediately)
- generate_image: Text to image. 100-200 sats.
- edit_image: Edit images with natural language. 200-450 sats.
- generate_text: Frontier LLMs. Per-character pricing (100-1000 chars/sat).
- translate_text: 119 languages. 1 sat per 1000 chars (min 1 sat). Accepts English names or ISO-639 codes / locale tags.
- generate_music: Full songs up to 6 min with AI vocals. 300 sats.
- text_to_speech: 3 tiers — OmniVoice (602+ langs, 100 chars/sat), Inworld Premium (#1 TTS, 50 chars/sat), Minimax Studio (voice clone, 10 chars/sat).
- analyze_image: Visual Q&A. 21 sats.
- extract_document: OCR to Markdown. 10 sats/page.
- extract_receipt: Structured JSON from receipts. 50 sats/page.
- convert_file: 200+ format pairs. 100 sats.
- merge_pdfs: Merge multiple PDFs. 100 sats.
- convert_html_to_pdf: HTML/Markdown to PDF. 50 sats.
- send_sms: SMS worldwide. Price varies by destination.
- send_email: Email delivery. 200 sats.
- place_call: Spoken message to any phone. Price varies.
- send_fax: Send fax worldwide (PDF URL or typed text). 500 sats for up to 10 pages, +50 sats per additional page (max 350).
- receive_fax: Open 24h window to receive a fax at our shared number, email delivery. 500 sats (+200 OCR).
- remove_background: Background removal. 5 sats.
- upscale_image: 2x/4x super-resolution. 5 sats.
- restore_face: Face restoration. 5 sats.
- detect_nsfw: NSFW classification. 2 sats.
- detect_objects: Object detection with bounding boxes. 5 sats.
- remove_object: Remove objects by description. 15 sats.
- colorize_image: Colorize B&W photos. 5 sats.
- deblur_image: Fix blurry photos. 20 sats.

### Async tools (return requestId, poll with check_job_status)
- generate_video: Text to video. 300-550 sats/sec (3-15 sec).
- animate_image: Image to video. 100 sats/sec.
- generate_3d_model: Photo to 3D GLB. 350 sats.
- clone_voice: Clone voice from audio sample. 7500 sats.
- transcribe_audio: Audio to text. 10 sats/min. 13 languages.
- ai_call: AI voice agent for two-way phone calls. ~150-250 sats.
- epub_to_audiobook: Book to M4B audiobook with chapters. Min 500 sats.

## Complete example: generate an image

Step 1 — Create payment:
POST https://sats4ai.com/api/mcp
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_payment","arguments":{"toolName":"generate_image"}}}

Response: {"result":{"content":[{"type":"text","text":"{\"paymentId\":\"abc123\",\"invoice\":\"lnbc1000n1...\",\"amountSats\":100}"}]}}

Step 2 — Pay the Lightning invoice with your wallet.

Step 3 — Call the tool:
POST https://sats4ai.com/api/mcp
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_image","arguments":{"paymentId":"abc123","prompt":"A futuristic Bitcoin-powered robot"}}}

Response: {"result":{"content":[{"type":"text","text":"{\"imageUrl\":\"https://sats4ai.com/uploads/img-abc123.png\"}"}]}}

## Error handling

Tool errors include an error_code for programmatic recovery:
- PAYMENT_REQUIRED: Invoice not paid yet
- PAYMENT_EXPIRED: Invoice expired (create a new one)
- TIMEOUT: Upstream provider timed out
- CONTENT_FILTERED: Content policy violation
- UPSTREAM_FAILED: Provider error

Failed paid calls include an LNURL-withdraw refund link in the error data.

## Discovery endpoints

- MCP server: https://sats4ai.com/api/mcp (JSON-RPC, tools/list)
- OpenAPI 3.1 spec: https://sats4ai.com/api/openapi.json (auto-synced from L402 manifest)
- L402 manifest: https://sats4ai.com/.well-known/l402-services (now includes input_schema per service)
- MCP manifest: https://sats4ai.com/.well-known/mcp
- Agent card: https://sats4ai.com/.well-known/agent.json
- Semantic search: https://sats4ai.com/api/discover?q=your+query
- Cost estimator: https://sats4ai.com/api/estimate-cost
- Error code catalog: https://sats4ai.com/api/error-codes
- Model list: POST to MCP endpoint with tools/call name="list_models"