btcpay-mcp

Get BTCPay Server version and system information.

Returns the server version, supported features, and system status. Use this to verify connectivity and check what features are available.

No store ID or API key required for this endpoint.

List all BTCPay Server stores accessible with the current API key.

Returns store IDs, names, and websites. Use a store ID from this list as the storeId parameter for invoice operations.

Get detailed information about a specific BTCPay store.

Args: store_id: Store ID (optional — uses BTCPAY_STORE_ID env var if empty).

Returns store configuration including default currency, speed policy, payment tolerance, and checkout settings.

List payment methods enabled for a BTCPay store.

Args: store_id: Store ID (optional — uses BTCPAY_STORE_ID env var if empty).

Returns enabled payment methods including on-chain (BTC, LTC, etc.) and Lightning, with network details and connection status.

Create a new BTCPay invoice.

Args: amount: Payment amount as a string (e.g., '0.001' or '10.00'). Precision is preserved because amounts are sent as strings. currency: Currency code (e.g., 'BTC', 'USD', 'EUR'). Default: 'BTC'. order_id: Optional order ID for tracking (stored in metadata). item_desc: Optional item description (stored in metadata).

Returns the invoice ID, status, checkout URL, and expiration time. Use the checkout URL to direct users to the payment page.

Get details and status of a BTCPay invoice.

Args: invoice_id: The invoice ID (UUID string returned by create_invoice).

Returns invoice status, amounts, payments received, and timing information. Status values: New, Processing, Settled, Expired, Invalid.

List invoices from the default BTCPay store.

Args: status_filter: Optional status to filter by: 'New', 'Processing', 'Settled', 'Expired', or 'Invalid'. Leave empty for all.

Returns a list of recent invoices with IDs, amounts, statuses, and dates.

Get the current BTCPay exchange rate for a currency pair.

Args: currency_pair: Currency pair in format 'BTC_USD', 'BTC_EUR', etc. Default: 'BTC_USD'.

Returns the current exchange rate from BTCPay's configured rate provider.

List all pull payments (donations, subscriptions, payroll) for the store.

Args: include_archived: Whether to include archived pull payments. Default: False.

Pull payments allow you to set up payment links that others can claim. Common uses: donations, recurring payouts, payroll.

Create a new pull payment for donations, subscriptions, or payroll.

Args: name: Name/label for the pull payment. amount: Payment amount as a string (e.g., '0.01'). currency: Currency code (e.g., 'BTC', 'USD'). Default: 'BTC'. description: Optional description. auto_approve: Auto-approve claims without manual review. Default: False. expires_at: Optional expiration (ISO 8601, e.g., '2026-04-01T00:00:00Z').

Returns the pull payment ID, payment link, and configuration.

List all payouts (actual payout transactions) for the store.

Payouts are claims against pull payments. Each payout represents money moved to a destination (wallet address, Lightning node, etc.).

List all payment requests (reusable payment links) for the store.

Payment requests are persistent payment pages that generate invoices on demand — useful for recurring billing, tipping, and donations.

Create a new payment request (reusable payment link).

Args: title: Title for the payment request. amount: Payment amount as a string (e.g., '0.001'). currency: Currency code (e.g., 'BTC', 'USD'). Default: 'BTC'. description: Optional description shown to payers. expiry_days: Days until expiration (0 = no expiry). Default: 0. allow_custom_amounts: Allow payers to set custom amounts. Default: False.

Returns the payment request ID and a payment link.

Get details of a specific payment request.

Args: payment_request_id: The payment request ID.

Returns payment request details including title, amount, status, and generated invoice count.

List all webhooks configured for the store.

Webhooks notify your application about payment events (invoice created, settled, expired, etc.) in real time.

Create a new webhook for real-time payment notifications.

Args: url: The URL to receive webhook POST requests. events: Comma-separated event types or 'all'. Common events: InvoiceSettled, InvoiceExpired, InvoiceInvalid, InvoiceReceivedPayment, InvoicePaymentSettled. Default: 'all'. secret: Optional secret for HMAC-SHA256 signature verification. automatic_redelivery: Auto-redeliver failed webhooks. Default: False.

Returns the webhook ID and configuration.

Refund a BTCPay invoice.

Args: invoice_id: The invoice ID to refund. refund_variant: Refund calculation method. Options: 'RateThen' (use rate at time of invoice, default), 'CurrentRate', 'Fiat' (refund exact fiat amount), 'OverpaidAmount' (refund only overpayment). payout_method_id: Optional payout method ID for the refund destination. subtract_percentage: Percentage to subtract from refund (0-100). Default: 0.

Returns the refund result with pull payment ID and amount.

Get Lightning node info and balance for the store.

Args: crypto_code: Crypto code (e.g., 'BTC', 'BTCTest'). Default: 'BTC'.

Returns node alias, version, channel count, peer count, and balances.

List Lightning channels for the store's Lightning node.

Args: crypto_code: Crypto code (e.g., 'BTC', 'BTCTest'). Default: 'BTC'.

Returns channel list with remote node, capacity, balances, and status.

Get wallet balance for a payment method (on-chain wallet).

Args: payment_method_id: Payment method ID (e.g., 'BTC' for the store's default BTC wallet). Leave empty to use the first BTC-like method.

Returns confirmed/unconfirmed balance for the wallet.

List on-chain wallet transactions for a payment method.

Args: payment_method_id: Payment method ID (e.g., 'BTC'). Leave empty to use 'BTC' by default.

Returns a list of wallet transactions with amounts, confirmations, and statuses.