@billium/mcp

@billium/mcp

The official Billium MCP server — manage non-custodial crypto invoices and webhooks from any Model Context Protocol host: Claude Code, Claude Desktop, Cursor, and others.

Once connected, you can just ask:

"Create a $49.99 invoice for order #1234 and give me the checkout link." "List my last 10 invoices and tell me which are still awaiting payment." "Add a webhook to https://api.myshop.com/billium that fires on invoice.paid."

…and the agent calls Billium directly.

Requirements

• Node.js ≥ 18
• A Billium secret API key (sk_...) and your merchant ID (mer_...), from the dashboard under Settings → Developer → API keys.

Configuration

The server reads three environment variables:

Variable	Required	Description
BILLIUM_API_KEY	✅	Secret API key (sk_...)
BILLIUM_MERCHANT_ID	✅	Merchant ID (mer_...)
BILLIUM_BASE_URL	—	Override the API base URL (self-hosted / testing)

Claude Code

claude mcp add billium \
  --env BILLIUM_API_KEY=sk_your_key \
  --env BILLIUM_MERCHANT_ID=mer_your_id \
  -- npx -y @billium/mcp

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json, or Cursor's mcp.json):

{
  "mcpServers": {
    "billium": {
      "command": "npx",
      "args": ["-y", "@billium/mcp"],
      "env": {
        "BILLIUM_API_KEY": "sk_your_key",
        "BILLIUM_MERCHANT_ID": "mer_your_id"
      }
    }
  }
}

Tools

23 tools across invoices, webhooks, customers, products, and wallets.

Invoices

Tool	Description
create_invoice	Create a crypto payment invoice (auto idempotency key)
get_invoice	Fetch an invoice by ID with status, payments, and timeline
list_invoices	List invoices with pagination and search
cancel_invoice	Cancel an unpaid invoice

Webhooks

Tool	Description
create_webhook	Register a webhook endpoint for invoice/payment events
list_webhooks	List configured webhook endpoints
update_webhook	Update a webhook's URL, events, or settings
delete_webhook	Delete a webhook endpoint
ping_webhook	Send a test event to a webhook endpoint

Customers

Tool	Description
list_customers	List customers with pagination and search
get_customer	Fetch a customer by ID
get_customer_stats	Revenue and invoice stats for a customer
update_customer	Update a customer's name/address/phone

Products

Tool	Description
create_product	Create a product for hosted checkout
get_product	Fetch a product by ID
list_products	List products with pagination and search
update_product	Update a product
delete_product	Delete a product

Wallets

Tool	Description
list_wallets	List wallet configurations (public config only)
get_wallet	Fetch a wallet by ID
create_wallet	Add a DIRECT_WALLET (address) or XPUB_WALLET (xpub)
update_wallet	Update a wallet's config
delete_wallet	Delete a wallet

Security

• Your secret key never leaves your machine — the server runs locally and talks directly to the Billium API over HTTPS.
• Settlement is non-custodial: payments go straight to your wallet; Billium never holds funds.
• create_invoice always sends an idempotency key (generated if you don't pass one), so a retried call never creates a duplicate invoice.

How it works

This server is a thin MCP wrapper over the @billium/node SDK, exposed over stdio. Each tool validates its input with zod and forwards it to the SDK.

License

MIT