{
  "openapi": "3.1.0",
  "info": {
    "title": "Spawnpay API",
    "description": "Universal payment proxy + per-call USDC wallet for AI agents across 228 indexed MCP tools and 33 BYOK API providers. Two products on one wallet:\n\n1. **Universal proxy** — route any HTTP call to 33 registered third-party providers through `/api/proxy`. BYOK upstream credential, flat $0.001 USDC routing fee per upstream 2xx. Free providers (Wikipedia, HN, Open-Meteo, Frankfurter, FxTwitter) are edge-served and don't require any key.\n2. **Paywall SDK** — wrap any async function or MCP tool with a per-call USDC charge (0.5% settlement fee, 99.5% to tool author) via `spawnpay-paywall` (Node) or `spawnpay_paywall` (Python).\n\nDeposits and withdrawals use Base L2 (Coinbase); internal transfers use the ledger. New agents get $7 USDC instant sandbox credit via `POST /api/signup`.",
    "version": "0.5.0",
    "contact": { "name": "Spawnpay", "url": "https://spawnpay.ai" },
    "license": { "name": "MIT", "url": "https://spawnpay.ai/docs" }
  },
  "servers": [
    { "url": "https://spawnpay.ai", "description": "Production gateway" }
  ],
  "components": {
    "securitySchemes": {
      "spawnpayBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "spk_live_...",
        "description": "Spawnpay API key. Get one for free by running `npx spawnpay-mcp` once, or `POST /api/signup`."
      }
    },
    "schemas": {
      "ProxyRequest": {
        "type": "object",
        "required": ["provider"],
        "properties": {
          "provider": { "type": "string", "description": "Provider slug (see GET /api/proxy/providers)." },
          "path": { "type": "string", "default": "/", "description": "Upstream path." },
          "method": { "type": "string", "enum": ["GET","POST","PUT","PATCH","DELETE"], "default": "GET" },
          "query": { "type": "object", "additionalProperties": true, "description": "Query params appended to the upstream URL." },
          "body": { "description": "Upstream request body (JSON or string)." },
          "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Extra upstream headers. Hop-by-hop and spawnpay-auth headers are stripped." },
          "providerKey": { "type": "string", "description": "BYOK upstream credential. Required for any non-free provider. May also be passed as X-Provider-Key header." },
          "idempotencyKey": { "type": "string", "description": "Optional. Auto-generated 60s-bucket key if absent." },
          "responseEncoding": { "type": "string", "enum": ["utf8","base64"], "description": "Auto-detected for audio/image/video content-types. Force base64 for binary." }
        }
      },
      "ProxyResponse": {
        "type": "object",
        "properties": {
          "provider": { "type": "string" },
          "path": { "type": "string" },
          "method": { "type": "string" },
          "status": { "type": "integer", "description": "Upstream HTTP status." },
          "headers": { "type": "object", "additionalProperties": { "type": "string" } },
          "body": { "description": "Upstream response body (object if JSON, string otherwise)." },
          "encoding": { "type": "string", "enum": ["utf8","base64"] },
          "bytes": { "type": "integer" },
          "edge": { "type": "boolean", "description": "True if served from the Vercel edge (free providers)." },
          "charged": {
            "type": "object",
            "properties": {
              "amount": { "type": "number", "description": "$0.001 USDC on upstream 2xx for paid providers, $0 otherwise." },
              "currency": { "type": "string", "enum": ["USDC"] },
              "txHash": { "type": ["string","null"], "description": "Internal transaction hash, prefixed 0xproxy_." }
            }
          },
          "deduplicated": { "type": "boolean" }
        }
      },
      "Provider": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "baseUrl": { "type": "string", "format": "uri" },
          "docs": { "type": "string", "format": "uri" },
          "free": { "type": "boolean" },
          "methods": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  },
  "paths": {
    "/api/proxy": {
      "post": {
        "summary": "Route a call to a registered provider",
        "description": "Charges $0.001 USDC per upstream 2xx (paid providers only). Free providers are edge-served, no charge, no apiKey required. BYOK key via X-Provider-Key header or providerKey body field.",
        "security": [{ "spawnpayBearer": [] }],
        "parameters": [
          {
            "name": "X-Provider-Key",
            "in": "header",
            "required": false,
            "schema": { "type": "string" },
            "description": "BYOK credential for the upstream provider. Required for paid providers."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProxyRequest" },
              "examples": {
                "openai-chat": {
                  "summary": "GPT-4o-mini via Spawnpay",
                  "value": {
                    "provider": "openai",
                    "path": "/v1/chat/completions",
                    "method": "POST",
                    "body": { "model": "gpt-4o-mini", "messages": [{ "role": "user", "content": "hi" }] }
                  }
                },
                "openmeteo-free": {
                  "summary": "Open-Meteo Paris forecast (no key)",
                  "value": {
                    "provider": "openmeteo",
                    "path": "/v1/forecast",
                    "method": "GET",
                    "query": { "latitude": 48.85, "longitude": 2.35, "current": "temperature_2m" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upstream returned 2xx — charge applied (paid) or free edge-served.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyResponse" } } }
          },
          "401": { "description": "Missing or invalid spawnpay key (only required for paid providers)." },
          "404": { "description": "Unknown provider slug." },
          "405": { "description": "Method not allowed for this provider." },
          "503": { "description": "Backend rolling out. Catalog still live at /api/proxy/providers." }
        }
      },
      "get": {
        "summary": "Self-describing docs",
        "description": "Returns the catalog plus a runnable curl example. Useful for crawlers / agents discovering the API.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": { "type": "string" },
                    "method": { "type": "string" },
                    "description": { "type": "string" },
                    "pricePerCall": { "type": "number" },
                    "currency": { "type": "string" },
                    "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } },
                    "example": { "type": "object" },
                    "docs": { "type": "string" },
                    "playground": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/proxy/providers": {
      "get": {
        "summary": "List supported providers",
        "description": "Edge-served (5-min cached). 21 paid BYOK providers + 4 free + FxTwitter.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } },
                    "pricePerCall": { "type": "number" },
                    "currency": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/signup": {
      "post": {
        "summary": "Create a Spawnpay agent wallet",
        "description": "Issues a new wallet on Base L2 with $5 USDC signup credit (+$2 with a referral). Returns the spk_live_ API key.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "referralCode": { "type": "string", "description": "SP_xxx code from another agent." },
                  "source": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKey": { "type": "string" },
                    "agentId": { "type": "string" },
                    "walletAddress": { "type": "string" },
                    "referralCode": { "type": "string" },
                    "creditBalance": { "type": "number" },
                    "bonusUnlocksAt": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/wallet/balance": {
      "get": {
        "summary": "Check wallet balance",
        "security": [{ "spawnpayBearer": [] }],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": { "type": "string" },
                    "creditBalance": { "type": "number" },
                    "fundedBalance": { "type": "number" },
                    "totalBalance": { "type": "number" },
                    "creditLocked": { "type": "boolean" },
                    "bonusUnlocksAt": { "type": ["string","null"] },
                    "network": { "type": "string", "enum": ["base"] }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/wallet/send": {
      "post": {
        "summary": "Send USDC to another wallet or SP_ code",
        "description": "0.5% platform fee. Internal sends (to another Spawnpay agent) settle instantly without on-chain gas.",
        "security": [{ "spawnpayBearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "amount"],
                "properties": {
                  "to": { "type": "string", "description": "0x... wallet OR SP_ referral code." },
                  "amount": { "type": "string" },
                  "currency": { "type": "string", "enum": ["USDC", "ETH"], "default": "USDC" },
                  "idempotencyKey": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "txHash": { "type": ["string","null"] },
                    "fee": { "type": "number" },
                    "referralPaid": { "type": "number" },
                    "internal": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "summary": "Public network stats",
        "description": "No auth required. Total agents, transactions, USDC volume, treasury balance.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalAgents": { "type": "integer" },
                    "totalTransactions": { "type": "integer" },
                    "totalVolume": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Proxy", "description": "Universal payment proxy for AI agents" },
    { "name": "Wallet", "description": "USDC wallet operations on Base L2" },
    { "name": "Public", "description": "No-auth endpoints (stats, catalog)" }
  ]
}