# OpenNode MCP > OpenNode MCP Server handles Bitcoin and Lightning Network payments directly from your AI client. Use it to create charges (BOLT11 invoices or on-chain addresses), initiate withdrawals, and manage refunds for crypto payouts. It lets your agent process real money movement without leaving the chat window. ## Overview - **Category:** payment-processing - **Price:** Free - **Tags:** bitcoin, lightning-network, crypto-payments, merchant-services, payouts ## Description Listen up. This OpenNode MCP Server lets your agent handle Bitcoin and Lightning Network payments right inside the chat window. You won't need to jump into a separate dashboard; it manages real money movement for you. **Processing Payments and Charges** When you gotta take payment, the server handles it. If you know the customer needs to pay via BOLT11 or an on-chain address, use `create_charge` to generate that new charge record—it'll give you the right details whether they need a specific Lightning invoice or just standard BTC details. You can also check out all your paid charges anytime by running `list_charges`. Need cash back? If a client overpaid on a charge, run `create_refund`, and the server records that refund for you. **Moving Funds (Withdrawals)** When it's time to pay out, the agent kicks off the process. You initiate fund withdrawals using `initiate_withdrawal`—this covers both Lightning invoices and standard BTC addresses, and it even lets you preview what a payout will look like first. Once that initial request is made, you confirm the actual payout: for Lightning Network payments, use `confirm_ln_withdrawal`; if it's going to an on-chain Bitcoin address, run `confirm_chain_withdrawal`. For specific payouts, you can check the status using `get_withdrawal`, or look up details about a past charge with `get_charge` and track any recorded refund by calling `get_refund`. To get the full picture of money coming in and going out, list all historical account activity records chronologically with `list_activity`; you'll also get a paginated rundown of every payout attempt through `list_withdrawals`, or see a complete history of charges using `list_charges`. **Setting Up Infrastructure & Accounts** You don't have to set up payment endpoints manually. You can tell the server to generate and record static on-chain Bitcoin addresses for receiving funds via `create_address`. If you need a recurring payment collection point, use `create_lnurl_pay` to generate and save a static Lightning Network address (LNURL-Pay). The server keeps track of all these endpoints; grab your list of long-term BTC addresses with `list_addresses`, or see every LNURL-Pay endpoint you've set up by calling `list_lnurl_pay`. You can also review every refund transaction that ever happened using `list_refunds`. **Monitoring and Rates** Always know what your books look like. Use `get_account_balance` to pull the current total balance across all connected crypto assets. Need to see what currencies are accepted for payments? Run `get_currencies` to list them out, or check the current exchange rates between various crypto pairs with `get_rates`. You can also set up future payouts by using `set_scheduled_withdrawals` to manage bank withdrawal statuses. **Managing Exchanges and Records** If you gotta swap assets, start an exchange process between BTC and fiat currency equivalents using `initiate_exchange`. The server tracks every single transaction. You can see a rundown of all your initiated payouts by calling `list_withdrawals`, or check the status of any specific withdrawal payout with `get_withdrawal`. ## Tools ### get_account_balance Retrieves the current total balance across all connected crypto assets. ### list_activity Lists all historical account activity records in chronological order. ### create_address Generates and records a static on-chain Bitcoin address for receiving funds. ### list_addresses Retrieves a list of static, long-term on-chain addresses you have set up. ### create_charge Creates a new charge, generating the necessary BOLT11 invoice or on-chain payment details. ### get_charge Fetches specific details and status information for a known charge ID. ### list_charges Lists all successfully processed and paid charges for review. ### get_currencies Lists every cryptocurrency supported as an originating payment currency. ### initiate_exchange Starts an exchange process between BTC and fiat currency equivalents. ### create_lnurl_pay Generates and records a static Lightning Network address (LNURL-Pay) for payments. ### list_lnurl_pay Retrieves a list of static Lightning Network payment URLs (LNURL-Pay). ### initiate_lnurl_withdrawal Initiates a withdrawal payout using the LNURL-Pay system. ### get_rates Provides current exchange rates between various crypto pairs. ### create_refund Creates a refund record for a charge that was paid in excess of the amount due. ### get_refund Retrieves specific information regarding a refund transaction. ### list_refunds Lists all recorded refund transactions. ### set_scheduled_withdrawals Sets or updates the status for scheduled bank withdrawals. ### confirm_chain_withdrawal Confirms a withdrawal payout destined for a Bitcoin (on-chain) address. ### confirm_ln_withdrawal Confirms a withdrawal payout destined for a Lightning Network invoice. ### get_withdrawal Fetches the full details and status of a previously initiated withdrawal payout. ### initiate_withdrawal Starts the process for a fund withdrawal, supporting both Lightning and Chain payouts. This call can also preview payouts. ### list_withdrawals Retrieves a paginated list of all initiated and completed withdrawal payouts. ## Prompt Examples **Prompt:** ``` Create a charge for 10000 satoshis with the description 'Coffee purchase'. ``` **Response:** ``` I've created the charge using `create_charge`. Here is your Lightning Invoice (BOLT11): `lnbc100u...` and the on-chain address: `tb1q...`. The charge ID is `ch_123456`. ``` **Prompt:** ``` List my paid charges on page 1. ``` **Response:** ``` Retrieving paid charges... I found 3 paid charges via `list_charges`. Notable payments include 'Order #1002' (ID: `ch_abc123`) and 'Donation' (ID: `ch_xyz789`). ``` **Prompt:** ``` Get the details of charge ID ch_abc123. ``` **Response:** ``` Inspecting charge `ch_abc123` using `get_charge`... The charge is marked as 'paid' for 5000 satoshis, created on 2023-10-27, with the description 'API Access'. ``` ## Capabilities ### Process Payments The agent generates a new Bitcoin charge using either an on-chain address or a BOLT11 invoice. ### Initiate Payouts You trigger fund withdrawals to specific Lightning invoices or BTC addresses, which the client then confirms for execution. ### Check Status & History The agent retrieves real-time data, listing charges (`list_charges`), payouts (`list_withdrawals`), and general account activity (`list_activity`). ### Manage Addresses You create static on-chain addresses or LNURL-Pay endpoints for recurring payment collection. ### Handle Disputes The agent can generate a refund (`create_refund`) if a charge was underpaid. ## Use Cases ### Reconciling a Failed Payment Batch The team ran 50 payments, but some failed or were underpaid. Instead of downloading CSVs and cross-referencing IDs, the agent first runs `list_charges`. Then, for any identified short payment, it calls `create_refund` to flag the necessary credit adjustment. This completes the audit trail in minutes. ### Setting up Merchant Payout Rails A new merchant needs payouts every Friday. The ops engineer uses `get_account_balance` first, confirming funds are available. Then, they use `initiate_withdrawal`, followed by the required confirmation call (e.g., `confirm_chain_withdrawal`), making the payout automated and auditable. ### Onboarding a New Client/Service A new service needs payments. The agent runs `create_lnurl_pay` to generate a permanent LNURL-Pay endpoint, followed by `list_addresses` to ensure the corresponding on-chain address is also set up for maximum collection flexibility. ### Immediate Payment Inquiry A customer claims they paid but their order isn't marked. The agent uses `get_charge` with the transaction ID, instantly confirming if the payment arrived and showing details like the amount received and creation date. ## Benefits - **Automated Charge Creation:** Use `create_charge` to instantly generate payment requests. Your agent handles the complexity—it returns both a BOLT11 invoice and a usable on-chain BTC address, eliminating manual data entry. - **Full Payout Visibility:** Never guess where your funds went. The combination of `list_withdrawals`, `get_withdrawal`, and `list_activity` lets you audit every payout status, from initiation to completion. - **Multi-Network Support:** You don't need separate tools for BTC or LN. The server supports both through functions like `initiate_withdrawal` and dedicated confirmation calls (`confirm_ln_withdrawal`). - **Refund Management:** If a payment is short, you don't have to manually calculate credits. Just run `create_refund`, and the system tracks the necessary adjustments. - **Recurring Collection:** Set up permanent collection points using `create_address` or `create_lnurl_pay`. Your agent generates these static addresses so customers always pay the right way. ## How It Works The bottom line is that you control complex financial transactions by passing specific commands to the OpenNode API through your AI client. 1. Subscribe to the server and input your OpenNode API Key. 2. Your AI client calls a specific function (e.g., `get_account_balance`). 3. The server executes the payment action and returns structured data—like an invoice, balance amount, or transaction ID—to your chat. ## Frequently Asked Questions **How do I handle payments that were underpaid using create_charge?** You don't have to worry about it. After identifying the shortfall, simply run `create_refund`. This generates a record for the exact amount needed, keeping your ledger accurate and auditable. **Can I list all past payments using list_charges?** Yes. `list_charges` retrieves every successfully processed charge ID. You can then pass these IDs to `get_charge` if you need the specific details or payment status for an individual record. **What's the difference between initiate_withdrawal and confirm_chain_withdrawal?** `initiate_withdrawal` starts the process and can show a preview. `confirm_chain_withdrawal` is the final, explicit call needed to execute the payout on the Bitcoin chain after you have reviewed the details. **How do I get my current BTC balance?** Use `get_account_balance`. This tool provides a single figure for your total account holdings across all monitored assets. It's the first step before any payout attempt. **How do I use `create_address` to generate a static Bitcoin receiving address?** You call `create_address` when you need a stable, on-chain wallet point for incoming payments. This generates predictable BTC addresses that don't change frequently, simplifying your payment collection setup. **Before I process an exchange, how do I use `get_rates`?** Use `get_rates` to fetch the current market data between BTC and Fiat currencies. Checking these rates first ensures you calculate the precise payout amount before initiating the transfer via `initiate_exchange`. **What is the process for generating an LNURL-Pay address using `create_lnurl_pay`?** `create_lnurl_pay` generates a static Lightning Network URL payment request. This method provides a standardized, easy-to-read address format ideal for quick and reliable payments on the Lightning network. **How do I manage scheduled payouts with `set_scheduled_withdrawals`?** You use `set_scheduled_withdrawals` to define when and how frequently your fiat bank withdrawals should occur. This tool allows you to automate payout timing, giving you control over disbursement schedules. **How do I generate a new Bitcoin payment request?** Use the `create_charge` tool. Provide the amount in satoshis (or specify a currency like USD) and an optional description. The tool returns a BOLT11 Lightning invoice and an on-chain address. **Can I preview a withdrawal before confirming it?** Yes. Call `initiate_withdrawal` with `auto_confirm` set to false. This generates a preview. You can then finalize it using `confirm_chain_withdrawal` or `confirm_ln_withdrawal` depending on the type. **How do I check my past withdrawals?** You can use the `list_withdrawals` tool to retrieve a list of past withdrawals, with optional filters for page size, page number, and withdrawal type (like 'ln' or 'chain').