---
layout: default
parent: For developers
title: Agent Guide - WASM Extensions
nav_order: 3
---

# Agent Guide - WASM Extensions

This guide is written for AI agents or developers using AI to build LNbits WASM extensions. It describes what to change, what not to change, and the available capabilities/limits.

## Hard Rules (Non-Negotiable)

- Do **not** change core LNbits files. Only edit files inside your extension folder.
- Do **not** add new Python dependencies.
- Do **not** rely on long-running WASM processes. WASM runs per-call with timeouts.

## Extension Folder Layout (WASM)

Your extension lives under:

```
lnbits/extensions/<ext_id>/
```

You should only edit files under this folder, typically:

- `config.json` (metadata, permissions, tags, public handlers)
- `wasm/` (your `module.wasm` or `module.wat`)
- `static/` (frontend assets)
- `templates/` (HTML pages)
- `manifest.json`, `README.md`, `description.md` (docs and metadata)

## Required Config Fields

In `config.json`:

- `id` / `name`
- `extension_type: "wasm"`
- `permissions` (required API permissions)
- `public_wasm_functions` (handlers callable from public routes)
- `public_kv_keys` (publicly readable KV keys)
- `payment_tags` (list of tags the user may grant for watcher access)

Example:

```json
{
  "id": "myext",
  "name": "MyExt",
  "extension_type": "wasm",
  "permissions": [
    {"id": "ext.db.read_write", "label": "DB access", "description": "..."},
    {
      "id": "api.POST:/api/v1/payments",
      "label": "Create invoices",
      "description": "..."
    },
    {
      "id": "ext.payments.watch",
      "label": "Watch payments",
      "description": "..."
    },
    {
      "id": "ext.tasks.schedule",
      "label": "Schedule tasks",
      "description": "..."
    },
    {"id": "ext.db.sql", "label": "SQL access", "description": "..."}
  ],
  "public_wasm_functions": [
    "public_create_invoice",
    "on_tag_payment",
    "on_schedule"
  ],
  "public_kv_keys": ["public_lists", "public_tasks"],
  "payment_tags": ["coinflip", "myext"]
}
```

## What the WASM Host Can Do

WASM runs in a short-lived subprocess. It can:

- Read/write extension KV (`/api/v1/kv/*`)
- Read/write secret KV (`/api/v1/secret/*`)
- Call internal LNbits endpoints (only if declared + granted)
- Publish websockets (`ws_publish`)
- Run backend tag watchers and scheduled handlers (server-side triggers)

## Permissions Model

Your extension can only call or access what is declared and granted:

- `api.METHOD:/path` for internal endpoints (core or other extensions)
- `ext.db.read_write` for KV access
- `ext.payments.watch` for payment watchers
- `ext.tasks.schedule` for scheduled jobs
- `ext.db.sql` for SQL interface

If the endpoint doesn’t exist, permissions won’t save.

## Tag Watchers (Backend)

You can register tag watchers:

```
POST /<ext_id>/api/v1/watch_tag
{
  "tag": "coinflip",
  "wallet_id": "<wallet-id>",
  "handler": "on_tag_payment",
  "store_key": "tag:coinflip:last_payment"
}
```

Constraints:

- Tag must be in `payment_tags` and granted by the user.
- Watchers are persisted and restored on restart.

## Scheduled Tasks (Backend)

You can schedule periodic handlers:

```
POST /<ext_id>/api/v1/schedule
{
  "interval_seconds": 30,
  "handler": "on_schedule",
  "store_key": "schedule:last_run"
}
```

Constraints:

- Requires `ext.tasks.schedule` permission.
- Minimum interval is 5 seconds.
- Stored in extension KV and restored on restart.

## SQL Interface (Limited)

You can run SQL within your extension schema:

- `/api/v1/sql/query` (SELECT only)
- `/api/v1/sql/exec` (limited DDL/DML)

Rules:

- Single statement only
- No `PRAGMA`, no `sqlite_master`
- No cross-schema access

## Public Pages (No Keys)

Public pages must not depend on `window.g` or wallet keys.
They can call:

- `/{ext_id}/api/v1/public/kv/{key}`
- `/{ext_id}/api/v1/public/call/{handler}`

## What Not To Do

- Do not write to core routes or override existing LNbits paths.
- Do not add background threads; use watchers or scheduler instead.
- Do not assume the WASM process persists.

## Testing Checklist

- Permissions show correctly in the extensions UI.
- Public handlers are in `public_wasm_functions`.
- Public KV keys are explicitly listed.
- Tag watchers only use allowed tags.
- Scheduled handlers run and update KV as expected.