onyx-paid-mcp — build a paid MCP server in 5 lines

USDC settlement on Base. No Stripe, no API keys, no signup flow. Charge AI agents per call directly through the protocol they already speak.

from onyx_paid_mcp import App

app = App(
    name="hello-paid-mcp",
    receive_address="0xYourBaseWallet",
    network="base",   # or "base-sepolia" for free testnet
)

@app.tool(
    name="echo",
    price_usdc="0.001",
    description="Returns whatever you send.",
    input_schema={"type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"]},
)
def echo(text: str) -> dict:
    return {"echoed": text}

if __name__ == "__main__":
    app.serve(port=8080)

That's it. pip install onyx-paid-mcp, point at any wallet address, decorate any function. You now have:

Streamable HTTP MCP at /mcp/ — installable in Claude Desktop, Cursor, Cline, mcp-use
REST endpoint at /v1/<tool> — for non-MCP agents
HTTP 402 gate that charges your wallet per call in USDC
Bazaar-discoverable manifest at /.well-known/x402.json — Coinbase auto-indexes
Free introspection at /, /manifest, /health

Why

Every MCP today is free-as-in-unmetered. That breaks at scale for any tool with real per-call expense (OCR, scraping infra, LLM passes, anything backed by a physical resource). onyx-paid-mcp lets you charge directly through the agent's wallet — the same way a paywall works in a browser, except the wallet signs an EIP-3009 USDC authorization instead of pulling out a credit card.

Install

pip install onyx-paid-mcp

Generate a Base wallet (gen_wallet.py in this repo, or any EVM wallet generator), set it as ONYX_RECEIVE, run your tool. Agents pay you in USDC the second they call.

Reference implementation

onyx-actions — the live server using this framework. Paid tools across Base on-chain primitives, captcha OCR, URL text extraction, DNS, WHOIS, email validation, IP geo, FX, browser automation, and a workflow chainer. All shipped as one-file modules in tools_pkg/.

Tool	Price
`onyx_base_tx_explainer`	$0.05
`onyx_base_tx_simulator`	$0.10
`onyx_base_token_risk_scan`	$0.25
`onyx_base_tx_decode`	$0.002
`onyx_token_metadata`	$0.001
`onyx_solana_tx_explainer`	$0.05
`onyx_solana_token_metadata`	$0.0008
`onyx_solana_token_risk_scan`	$0.25
`onyx_solana_jupiter_quote`	$0.001
`onyx_solana_wallet_activity`	$0.002
`onyx_ens_resolve`	$0.0008
`onyx_solve_captcha`	$0.003
`onyx_url_text`	$0.001
`onyx_url_unshorten`	$0.0005
`onyx_whois`	$0.001
`onyx_dns_lookup`	$0.0005
`onyx_email_validate`	$0.0008
`onyx_ip_geolocate`	$0.0008
`onyx_fx_convert`	$0.0008
`onyx_password_strength`	$0.0003
`onyx_user_agent_parse`	$0.0003
`onyx_browser_*` (6 tools)	$0.002–$0.008
`onyx_agent_workflow`	$0.020

Smithery listing: https://smithery.ai/servers/dimitrilaouanis/onyx-mcp

Integrations in flight

Stagehand (Browserbase) — pay-per-call captcha hook over x402. Spec: BROWSERBASE_INTEGRATION.md. Discussion: #1.

How agents call you

Try it against the live reference server with one command — no install:

curl -X POST https://onyx-actions.onrender.com/v1/onyx_solana_jupiter_quote \
  -H "content-type: application/json" \
  -d '{"input_mint":"So11111111111111111111111111111111111111112","output_mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"1000000000"}' -i
# → HTTP 402 Payment Required
# → payment-required: <base64-encoded JSON with payTo, asset, amount, inputSchema>

Then sign an EIP-3009 USDC authorization and retry with X-PAYMENT: <signed>:

# Full client demo — shows the 402 → sign → 200 loop in 50 lines:
python examples/agent_pay.py onyx_solana_jupiter_quote
# Set ONYX_DEMO_KEY=0x... to actually pay + get the result

Any x402-aware client SDK (Coinbase CDP, Cloudflare Agent SDK, Privy, mcp-use) handles the loop in ~5 lines. Agents don't need to know your URL — the Coinbase Bazaar crawler picks up your /.well-known/x402.json from on-chain settled payments.

Configure

The framework defaults are sane. Customize via constructor or env:

Field	Default	Note
`name`	required	shows up in MCP, manifest, landing page
`receive_address`	required	where USDC settles
`network`	`base-sepolia`	or `base` for mainnet
`facilitator_url`	x402.org public	swap for Coinbase CDP / xpay / your own
`public_url`	None	sets the canonical URL in manifests
`description`	empty	short one-liner
`homepage`	None	optional landing page URL

Self-hosting checklist

Generate or pick a Base wallet (just an address — private key never leaves your machine; this is a receive-only flow)
Funded wallet not required to receive — only senders need USDC
Pick a host: Render free tier works; Fly.io machines for always-on; Cloudflare Tunnel + Oracle ARM for zero-cost-zero-cold-start
pip install onyx-paid-mcp, write your app.py, deploy
Submit https://your-server/.well-known/x402.json to Coinbase Bazaar — first settled payment auto-indexes you everywhere

Status

v0.1.0 — released April 2026. Battle-tested on onyx-actions.onrender.com (live since Apr 24).

License

MIT — see LICENSE.

onyx mcp