spawnpay-paywall

Charge AI agents per-call for any async function. Drop-in wrapper for MCP tools, REST handlers, or any function the agent might call. Settles in USDC on Base L2.

Why

You shipped an MCP server. Agents are calling it. You're eating LLM costs, scraping costs, or just compute, and there's no way to charge for it without forcing every user to sign up for Stripe and paste a credit card. Paywall solves that. Calling agents already have wallets, you just declare a price.

Install

npm install spawnpay-paywall

Use

import { paywall } from 'spawnpay-paywall';

// Your existing tool implementation
async function fetchTweet({ url }) {
  const r = await fetch(url);
  return await r.text();
}

// Wrap it. Done.
export const fetchTweetPaid = paywall(
  {
    price: 0.01,           // USDC per call
    vendor: 'SP_yourCode', // your spawnpay referral code (or 0x wallet)
    description: 'fetch_tweet',
  },
  fetchTweet,
);

The calling agent needs SPAWNPAY_API_KEY in its env. Every call charges them 0.01 USDC, sends it to your wallet, then runs the original function. If the charge fails, the original never runs.

In an MCP server

Wrap each paid tool's handler. The MCP framework doesn't know paywall exists.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { paywall } from 'spawnpay-paywall';

const server = new Server({ name: 'my-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });

const decompile = paywall(
  { price: 0.10, vendor: 'SP_yourCode', description: 'decompile_binary' },
  async ({ binary_path }) => {
    /* ... real work ... */
    return { code: '...', symbols: [...] };
  },
);

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === 'decompile') {
    const result = await decompile(req.params.arguments);
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  }
});

Caller side

The agent calling your MCP needs a spawnpay key. Cheapest path: install spawnpay-mcp, run spawnpay_signup once, get $5 USDC credit free.

{
  "mcpServers": {
    "spawnpay": { "command": "npx", "args": ["-y", "spawnpay-mcp"] },
    "your-mcp": {
      "command": "npx",
      "args": ["-y", "your-mcp"],
      "env": { "SPAWNPAY_API_KEY": "spk_caller_key_here" }
    }
  }
}

Errors

Paywall throws PaywallError with a .code you can branch on:

| Code | Means | |------|-------| | NO_API_KEY | Caller didn't set SPAWNPAY_API_KEY | | INSUFFICIENT_BALANCE | Caller's wallet is empty | | CREDIT_LOCKED | Signup credit not yet unlocked | | DAILY_LIMIT | Caller hit their daily spend ceiling | | BAD_VENDOR | Your vendor SP_ code isn't registered | | NETWORK | Spawnpay backend unreachable | | BACKEND | 5xx from spawnpay | | CHARGE_FAILED | Catch-all 4xx |

Each error has .message and an optional .hint you can show the user.

Idempotency

Paywall auto-generates an idempotency key per (description, input, ~minute) — re-runs of the same call within ~60s don't double-charge, but a distinct call later does. Override via your own retry layer if you need a different policy.

Receipts

Every successful charge calls your onCharge hook (if provided) and passes a receipt object to the wrapped function as the second argument:

const myTool = paywall(
  { price: 0.01, vendor: 'SP_x', onCharge: (r) => console.log('paid:', r.txHash) },
  async (input, ctx) => {
    // ctx.receipt = { txHash, amount, vendor, currency, status, deduplicated }
    return doWork(input);
  },
);

Pricing your tool

| Cost shape | Suggested price | |------------|-----------------| | Calls a paid LLM API | LLM cost × 1.2 | | Scrape / API proxy | $0.001 – $0.01 | | Compute-heavy (decompile, parse, transcribe) | $0.05 – $1.00 | | Curated data lookup | $0.01 – $0.10 |

Spawnpay takes 0.5%. You keep 99.5%.

Examples

| Example | Tool | Price | |---------|------|-------| | paid-search-mcp | web_search (Wikipedia + HN, swap to Brave/Tavily/Serper) | $0.005 | | tweet-fetcher-mcp | fetch_tweet (fxtwitter API) | $0.001 |

License

MIT