# Send aperture: the L402 aware reverse proxy to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "aperture",
    "name": "aperture: the L402 aware reverse proxy",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/Roasbeef/aperture",
    "canonicalUrl": "https://clawhub.ai/Roasbeef/aperture",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/aperture",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=aperture",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "templates/docker-compose-aperture.yml",
      "templates/aperture-regtest.yaml",
      "templates/aperture-example.yaml",
      "scripts/setup.sh",
      "scripts/install.sh"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "aperture",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-11T16:28:16.119Z",
      "expiresAt": "2026-05-18T16:28:16.119Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=aperture",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=aperture",
        "contentDisposition": "attachment; filename=\"aperture-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "aperture"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/aperture"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/aperture",
    "downloadUrl": "https://openagent3.xyz/downloads/aperture",
    "agentUrl": "https://openagent3.xyz/skills/aperture/agent",
    "manifestUrl": "https://openagent3.xyz/skills/aperture/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/aperture/agent.md"
  }
}
```
## Documentation

### Aperture - L402 Lightning Reverse Proxy

Aperture is a reverse proxy that implements the L402 protocol, enabling
payment-gated API access via the Lightning Network. It sits in front of your
backend services and requires Lightning micropayments before granting access.

Source: github.com/lightninglabs/aperture

### Quick Start

# 1. Install aperture
skills/aperture/scripts/install.sh

# 2. Generate config (connects to local lnd)
skills/aperture/scripts/setup.sh

# 3. Ensure invoice.macaroon exists (required for L402 invoice creation)
#    If not present, bake one with the macaroon-bakery skill:
skills/macaroon-bakery/scripts/bake.sh --role invoice-only \\
    --save-to ~/.lnd/data/chain/bitcoin/mainnet/invoice.macaroon

# 4. Start aperture
skills/aperture/scripts/start.sh

# 5. Test with lnget
lnget -k --no-pay https://localhost:8081/api/test

### How Aperture Works

Client requests a protected resource through Aperture
Aperture responds with HTTP 402 + WWW-Authenticate: L402 header containing
a macaroon and a Lightning invoice
Client pays the invoice and obtains the preimage
Client retries with Authorization: L402 <macaroon>:<preimage>
Aperture validates the token and proxies to the backend service

### Installation

skills/aperture/scripts/install.sh

This will:

Verify Go is installed
Run go install github.com/lightninglabs/aperture/cmd/aperture@latest
Verify aperture is on $PATH

To install manually:

go install github.com/lightninglabs/aperture/cmd/aperture@latest

Or build from source:

git clone https://github.com/lightninglabs/aperture.git
cd aperture
make install

### Setup

skills/aperture/scripts/setup.sh

This generates ~/.aperture/aperture.yaml from the config template with
sensible defaults. The setup script auto-detects the local lnd node paths.

Options:

# Custom network
setup.sh --network testnet

# Custom lnd paths
setup.sh --lnd-host localhost:10009 \\
         --lnd-tls ~/.lnd/tls.cert \\
         --lnd-macdir ~/.lnd/data/chain/bitcoin/mainnet

# Custom listen port
setup.sh --port 8081

# Disable TLS (development only)
setup.sh --insecure

# Disable auth (no payments required)
setup.sh --no-auth

### Start

skills/aperture/scripts/start.sh

Starts aperture as a background process reading ~/.aperture/aperture.yaml.

Options:

start.sh --foreground         # Run in foreground
start.sh --config /path/to   # Custom config path

### Stop

skills/aperture/scripts/stop.sh

### Configuration

Config file: ~/.aperture/aperture.yaml

### Invoice Macaroon Requirement

Aperture requires invoice.macaroon in the configured macdir to create
Lightning invoices for L402 challenges. This is not the same as
admin.macaroon. If the macaroon is missing, aperture will fail to start or
will return errors when clients request paid resources.

To bake an invoice macaroon with the macaroon-bakery skill:

skills/macaroon-bakery/scripts/bake.sh --role invoice-only \\
    --save-to ~/.lnd/data/chain/bitcoin/mainnet/invoice.macaroon

The setup.sh script will warn you if invoice.macaroon is not found at the
expected path.

### Minimal Agent Configuration

This is the minimal config for an agent hosting paid endpoints with a local
lnd node:

listenaddr: "localhost:8081"
insecure: true
debuglevel: "info"
dbbackend: "sqlite"
sqlite:
  dbfile: "~/.aperture/aperture.db"

authenticator:
  network: "mainnet"
  lndhost: "localhost:10009"
  tlspath: "~/.lnd/tls.cert"
  macdir: "~/.lnd/data/chain/bitcoin/mainnet"

services:
  - name: "my-api"
    hostregexp: ".*"
    pathregexp: "^/api/.*$"
    address: "127.0.0.1:8080"
    protocol: http
    price: 100

### Service Configuration

Each service entry defines a backend to protect:

services:
  - name: "service-name"
    # Match requests by host (regex).
    hostregexp: "^api.example.com$"

    # Match requests by path (regex).
    pathregexp: "^/paid/.*$"

    # Backend address to proxy to.
    address: "127.0.0.1:8080"

    # Protocol: http or https.
    protocol: http

    # Static price in satoshis.
    price: 100

    # Macaroon capabilities granted at base tier.
    capabilities: "read,write"

    # Token expiry in seconds (31557600 = 1 year).
    timeout: 31557600

    # Paths exempt from payment.
    authwhitelistpaths:
      - "^/health$"
      - "^/public/.*$"

    # Per-endpoint rate limits (token bucket).
    ratelimits:
      - pathregexp: "^/api/query.*$"
        requests: 10
        per: 1s
        burst: 20

### Authentication Backends

Direct LND Connection

authenticator:
  network: "mainnet"
  lndhost: "localhost:10009"
  tlspath: "~/.lnd/tls.cert"
  macdir: "~/.lnd/data/chain/bitcoin/mainnet"

Lightning Node Connect (LNC)

authenticator:
  network: "mainnet"
  passphrase: "your-pairing-phrase"
  mailboxaddress: "mailbox.terminal.lightning.today:443"

Disable Authentication

authenticator:
  disable: true

### Database Backends

SQLite (recommended for agents):

dbbackend: "sqlite"
sqlite:
  dbfile: "~/.aperture/aperture.db"

PostgreSQL:

dbbackend: "postgres"
postgres:
  host: "localhost"
  port: 5432
  user: "aperture"
  password: "secret"
  dbname: "aperture"

### TLS Configuration

# Auto Let's Encrypt certificate.
autocert: true
servername: "api.example.com"

# Or disable TLS (development/local only).
insecure: true

If neither is set, Aperture generates self-signed certs in ~/.aperture/.

### Dynamic Pricing

Connect to a gRPC price server instead of static prices:

services:
  - name: "my-api"
    dynamicprice:
      enabled: true
      grpcaddress: "127.0.0.1:10010"
      insecure: false
      tlscertpath: "/path/to/pricer/tls.cert"

### Hosting Paid Content for Agents

A common pattern is hosting information that other agents pay to access:

# 1. Start a simple HTTP backend with your content
mkdir -p /tmp/paid-content
echo '{"data": "valuable information"}' > /tmp/paid-content/info.json
cd /tmp/paid-content && python3 -m http.server 8080 &

# 2. Configure aperture to protect it
skills/aperture/scripts/setup.sh --insecure --port 8081

# 3. Start aperture
skills/aperture/scripts/start.sh

# 4. Other agents can now pay and fetch
lnget --max-cost 100 https://localhost:8081/api/info.json

### Integration with lnget and lnd

With all three components running:

# Verify lnd is running
skills/lnd/scripts/lncli.sh getinfo

# Start aperture (uses same lnd for invoice generation)
skills/aperture/scripts/start.sh

# Fetch a paid resource
lnget --max-cost 1000 https://localhost:8081/api/data

# Check tokens
lnget tokens list

### File Locations

PathPurpose~/.aperture/aperture.yamlConfiguration file~/.aperture/aperture.dbSQLite database~/.aperture/tls.certTLS certificate~/.aperture/tls.keyTLS private key~/.aperture/aperture.logLog file

### Port already in use

Change listenaddr in config to a different port, or use setup.sh --port.

### LND connection refused

Verify lnd is running and wallet is unlocked. Check lndhost, tlspath, and
macdir in the config point to the correct lnd instance.

### No 402 challenge returned

Check that the request path matches a service's pathregexp and is not in
authwhitelistpaths. Verify authenticator.disable is not true.

### Token validation fails

The client must present the exact macaroon from the challenge with the correct
preimage. Verify the preimage matches the payment hash.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: Roasbeef
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-11T16:28:16.119Z
- Expires at: 2026-05-18T16:28:16.119Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/aperture)
- [Send to Agent page](https://openagent3.xyz/skills/aperture/agent)
- [JSON manifest](https://openagent3.xyz/skills/aperture/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/aperture/agent.md)
- [Download page](https://openagent3.xyz/downloads/aperture)