# Sats4AI

> Bitcoin-powered AI tools. 40+ services — image, video, text, speech (602+ languages), transcription, translation, OCR, communication, file conversion. 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.
- 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.
- 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)
- L402 manifest: https://sats4ai.com/.well-known/l402-services
- 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
- Model list: POST to MCP endpoint with tools/call name="list_models"