Docs
Reference for FunkPayAI MCP tools, the btcfunkpay REST API, and the funkpay.js checkout widget.
FunkPayAI exposes 11 tools via the Model Context Protocol. Claude Code and any MCP-compatible client can call them autonomously.
| Tool | Description |
|---|---|
| get_balance | Wallet balance in satoshis |
| get_new_address | Generate a fresh Bitcoin receive address |
| send_payment | Send BTC to an address — subject to approval policy |
| get_transaction | Status and confirmation count for a txid |
| list_transactions | Recent wallet transactions (up to 100) |
| create_invoice | Create a payment invoice on a btcfunkpay merchant. Pass sku and the merchant resolves the price automatically. |
| get_invoice_status | Poll invoice status: pending → detected → confirmed |
| wait_for_payment | Block until an invoice is detected or confirmed on-chain |
| discover_products | Browse or search a merchant's product catalog. Human-in-the-loop: show catalog, let user pick, then buy with create_invoice. |
| list_merchants | Trusted merchant servers configured by the user |
| discover_merchant | Auto-discover a FunkPay server for a domain via /.well-known/funkpay.json |
Add this to your Claude Code MCP config (~/.claude/claude_desktop_config.json or .claude/settings.json):
{
"mcpServers": {
"funkpayai": {
"command": "node",
"args": ["~/.funkpay/mcp-stdio.mjs"]
}
}
}
The proxy is written by FunkPayAI at ~/.funkpay/mcp-stdio.mjs on first launch. It auto-starts the desktop app if it is not running.
btcfunkpay exposes a REST API for invoice management and product discovery. Base URL is the server you self-host.
# Create invoice (agent flow) POST /invoices { "sku": "FUNK-001" } # price resolved by merchant → { payment_id, address, amount_sat, amount_fiat, currency, exchange_rate, bip21_uri, expires_at } # Poll invoice status GET /invoices/:id → { status, confirmations, received_sat, txid, amount_fiat, currency, exchange_rate } # Product catalog — paginated list GET /funkpay/product GET /funkpay/product?query=sticker[&limit=20&offset=0] → { total, limit, offset, products: [ <product>, … ] } # Product catalog — single product by SKU (FunkPay contract) GET /funkpay/product?sku=FUNK-001 → { "sku": "FUNK-001", # required "name": "FunkPay Sticker Pack", # required "price_fiat": 4.99, # fiat price (preferred) "currency": "USD", # USD | EUR | GBP | JPY | CAD | CHF | AUD "price_sat": null, # fixed sat price (fallback if no fiat) "description": "…", "type": "product", # product | subscription "image": "", "active": true }
Price resolution: if price_fiat + currency are set, btcfunkpay fetches the live BTC rate from mempool.space and computes amount_sat at invoice creation. Otherwise price_sat is used as-is.
Status lifecycle: pending → detected → confirmed | overpaid | expired
One script tag. Works on any site — static HTML, React, Shopify, WordPress. Shadow DOM keeps styles isolated.
<div id="funkpay" data-server="https://your-btcfunkpay-server.com" data-amount-fiat="25.00" data-currency="EUR" data-theme="auto"></div> <script src="https://btcfunk.com/pay/funkpay.js"></script>
The widget renders a QR code, monitors the address, and fires a funkpay:confirmed event on your page when payment is detected.
Checkout widget — one script tag, works on any site. Renders a Bitcoin QR code, monitors the address, and updates the page automatically on confirmation. No backend changes needed on the frontend.
btcfunk.com/pay/funkpay.js →Electron desktop app for macOS, Windows, Linux. Runs a pruned Bitcoin Core node (~10 GB). Exposes MCP tools so an AI agent can create invoices, send payments, and wait for on-chain confirmation autonomously.
github →Python/FastAPI server you self-host. Generates addresses, monitors the mempool and confirmed blocks, fires webhooks. Exposes a product catalog with SKU and fiat pricing.
github →