lnbits/docs/devs/agents_extensions.md

layout, parent, title, nav_order

layout	parent	title	nav_order
default	For developers	Agent Guide - Python Extensions	4

Agent Guide - Python Extensions

This guide is for AI agents or developers using AI to build traditional (Python) LNbits extensions. It defines what to change, what not to change, and the expected structure.

Hard Rules (Non-Negotiable)

• Do not change core LNbits files.
• Only edit files inside your extension folder.
• Do not add new Python dependencies unless explicitly approved.

Extension Folder Layout (Python)

Your extension lives under:

lnbits/extensions/<ext_id>/

Typical files to edit:

• views.py (HTML routes)
• views_api.py (API routes)
• crud.py / models.py (storage logic + models)
• migrations.py (DB schema)
• templates/<ext_id>/ (HTML)
• static/ (JS/CSS/images)
• config.json, manifest.json, README.md

What You Can Do

Python extensions can:

• Define their own database schema via migrations.py
• Run long-running background tasks via *_start() and *_stop() hooks
• Access LNbits internal services directly in Python
• Expose custom API routes under /<ext_id>/api/v1/...

What You Must Not Do

• Do not modify core services or routes.
• Do not patch LNbits internals for your extension.
• Avoid direct DB access outside your own schema.

Background Tasks

Implement background tasks by exposing:

def <ext_id>_start():
def <ext_id>_stop():

Use register_invoice_listener or wait_for_paid_invoices if you need to react to payments.

Testing Checklist

• Extension loads without errors.
• Migrations apply cleanly.
• Routes are registered under /<ext_id>/....
• Background tasks start/stop cleanly.