check_invoice_status
Verify payment status for Lightning Network invoices using invoice ID to confirm successful transactions.
Instructions
Check if a Lightning invoice has been paid. Use the invoice ID from create_invoice.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | The invoice ID returned from create_invoice |
Implementation Reference
- Implementation of the check_invoice_status tool handler which uses wallet instances (LND or Strike) to query invoice state.
async def check_invoice_status( invoice_id: str, wallet: "Union[LndWallet, NWCWallet, OpenNodeWallet, StrikeWallet, None]" = None, ) -> str: """ Check if a Lightning invoice has been paid. Use the invoice ID returned from create_invoice to check whether the invoice has been paid, is still pending, or has expired. Args: invoice_id: The invoice ID returned from create_invoice wallet: Wallet instance Returns: JSON with invoice status including whether it has been paid """ if not invoice_id or not invoice_id.strip(): return json.dumps({ "success": False, "error": "Invoice ID is required" }) if not wallet: return json.dumps({ "success": False, "error": "Wallet not configured. Set LND_REST_HOST+LND_MACAROON_HEX, STRIKE_API_KEY, OPENNODE_API_KEY, or NWC_CONNECTION_STRING environment variable." }) try: from ..lnd_wallet import LndWallet from ..strike_wallet import StrikeWallet if isinstance(wallet, LndWallet): # Use LND REST API to check invoice status status = await wallet.get_invoice_status(invoice_id.strip()) if status["is_paid"]: message = f"Invoice {invoice_id} has been PAID!" elif status["is_pending"]: message = f"Invoice {invoice_id} is still pending payment." else: message = f"Invoice {invoice_id} status: {status['state']}" return json.dumps({ "success": True, "provider": "LND", "invoice": { "id": status["id"], "state": status["state"], "isPaid": status["is_paid"], "isPending": status["is_pending"], "amountSats": status["amount_sats"], "settledAt": status.get("settled_at"), }, "message": message, }, indent=2) elif isinstance(wallet, StrikeWallet): # Use Strike API to check invoice status payment = await wallet._request("GET", f"/invoices/{invoice_id}") state = payment.get("state", "UNKNOWN") amount = payment.get("amount", {}) amount_value = amount.get("amount") if isinstance(amount, dict) else None paid_at = payment.get("paidAt") is_paid = state.upper() in ("PAID", "COMPLETED") is_pending = state.upper() in ("UNPAID", "PENDING") if is_paid: message = f"Invoice {invoice_id} has been PAID!" elif is_pending: message = f"Invoice {invoice_id} is still pending payment." else: message = f"Invoice {invoice_id} status: {state}" return json.dumps({ "success": True, "provider": "Strike", "invoice": { "id": invoice_id, "state": state, "isPaid": is_paid, "isPending": is_pending, "amount": amount_value, "paidAt": paid_at, }, "message": message, }, indent=2) else: provider_name = type(wallet).__name__.replace("Wallet", "") return json.dumps({ "success": False, "error": f"Invoice status check is not supported with {provider_name} wallet.", "hint": "Use LND (set LND_REST_HOST+LND_MACAROON_HEX) or Strike (set STRIKE_API_KEY) for invoice status checking." }) except Exception as e: logger.exception("Error checking invoice status") return json.dumps({ "success": False, "error": sanitize_error(str(e)) }) - Tool definition and registration in the MCP server for 'check_invoice_status'.
name="check_invoice_status", description=( "Check if a Lightning invoice has been paid. " "Use the invoice ID from create_invoice." ), inputSchema={ "type": "object", "properties": { "invoice_id": { "type": "string", "description": "The invoice ID returned from create_invoice", }, }, "required": ["invoice_id"], }, ), - Tool invocation routing within the MCP server for 'check_invoice_status'.
elif name == "check_invoice_status": result = await check_invoice_status( invoice_id=arguments.get("invoice_id", ""), wallet=self.wallet, )