Conduit Documentation

Everything you need to go from zero to AI agents paying each other over the Lightning Network. Start with the beginner guide, then dive into the full tool reference.

What is Conduit?

Conduit is open-source payment infrastructure that lets AI agents pay each other using Bitcoin's Lightning Network. Think of it as the payment layer for the agent economy.

Without Conduit, an AI agent that wants to buy a service from another agent has no way to pay for it. Credit cards require human identity. Bank transfers are slow. Crypto on-chain transactions take minutes and cost fees. Lightning payments settle in under a second with fees measured in fractions of a penny.

Conduit provides 26 tools that an AI agent (like Claude) can use to discover skills, pay invoices, verify providers, and manage spending - all through the Model Context Protocol (MCP) or a REST API.

Key principles

• Non-custodial: Payments flow directly between agents on Lightning. Conduit never holds your funds.
• Your node, your sats: You connect your own LND node. No middleman.
• Proof-based trust: Ratings require payment proof. Providers verify with node signatures and DNS. No fake reviews.
• Decentralized discovery: Skills are published to Nostr relays - no central registry controls who can list services.

Lightning in 60 Seconds

If you're new to Lightning, here's what you need to know:

Bitcoin is digital money. Transactions on the Bitcoin blockchain take ~10 minutes to confirm and cost a few dollars in fees. That's fine for large transfers, but terrible for small, fast payments.

Lightning Network is a layer built on top of Bitcoin. Two parties open a "payment channel" by locking some Bitcoin on-chain. Once open, they can send unlimited payments back and forth instantly and for nearly zero fees. Payments can route through multiple channels to reach anyone on the network.

Satoshis (sats) are the smallest unit of Bitcoin. 1 Bitcoin = 100,000,000 sats. A typical skill on Conduit costs 50-200 sats (a fraction of a cent).

Invoices are how you request payment on Lightning. A provider creates an invoice for a specific amount. The consumer pays it. The payment settles instantly and the provider receives cryptographic proof (a "preimage") that the payment was made.

LND is the most popular Lightning node software. It's what Conduit connects to. You can run LND on a Start9, Umbrel, or any Linux machine.

Installation

One-command install

The fastest way to get started. This interactive script checks your system, installs dependencies, and walks you through configuration:

curl -sSL lightninglinq.com/install.sh | bash

The installer handles:

• Python 3.11+ (via Homebrew on macOS or apt/dnf/pacman on Linux)
• PostgreSQL (database for skills, executions, ratings)
• Redis (rate limiting and caching)
• Cloning the repo to ~/conduit
• Python virtual environment and dependencies
• Interactive LND node configuration
• .env file generation with random API key
• Database initialization
• Optional Claude Desktop MCP integration

Manual install

If you prefer to do it yourself:

# Clone the repo
git clone https://github.com/Lightning-Linq/conduit.git ~/conduit

cd ~/conduit

# Create a virtual environment (Python 3.11+)
python3.11 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Copy and edit the config
cp .env.example .env
# Edit .env with your LND connection details

# Set up the database
createdb conduit
alembic upgrade head

Prerequisites

• Python 3.11+
• PostgreSQL - stores skills, executions, ratings, anomaly flags
• Redis - powers rate limiting
• LND node - your Lightning node (Start9, Umbrel, or standalone)

Configuration

All configuration lives in the .env file at the project root. Here's what each setting does:

App settings

APP_NAME=Conduit
APP_ENV=development       # or "production"
DEBUG=false               # NEVER true with MCP  - corrupts stdio
API_HOST=0.0.0.0
API_PORT=8000

Database

DATABASE_URL=postgresql+asyncpg://conduit:conduit@localhost:5432/conduit
REDIS_URL=redis://localhost:6379/0

LND node connection

LND_HOST=localhost              # IP or hostname of your LND node
LND_GRPC_PORT=10009             # gRPC port (default: 10009)
LND_TLS_CERT_PATH=~/.lnd/tls.cert
LND_MACAROON_PATH=~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
LND_NETWORK=mainnet             # mainnet, testnet, or regtest

Start9 users: Your TLS cert and macaroon are downloaded from your Start9 dashboard under Services → LND → Properties. The host is your Start9's local IP address.

Umbrel users: Credentials are typically at ~/umbrel/app-data/lightning/data/lnd/.

Security settings

# API key (generated automatically by installer)
CONDUIT_API_KEY=your-random-key-here

# L402 pay-per-request auth
L402_SECRET_KEY=your-l402-secret
L402_TOKEN_EXPIRY_SECONDS=3600

# Spending limits (in satoshis)
SPENDING_LIMIT_PER_PAYMENT_SATS=10000
SPENDING_LIMIT_HOURLY_SATS=50000
SPENDING_LIMIT_DAILY_SATS=200000
SPENDING_CONFIRM_ABOVE_SATS=5000

Nostr identity

# Your Nostr private key (nsec or hex)
NOSTR_PRIVATE_KEY=nsec1...
NOSTR_RELAYS=wss://relay.damus.io,wss://relay.nostr.band,wss://nos.lol

Your First Payment

Once Conduit is running and connected to your LND node, here's the complete flow for an AI agent buying a skill:

Step 1: Start the server

cd ~/conduit
source .venv/bin/activate

# Option A: MCP server (for Claude Desktop)
python -m conduit.mcp_server

# Option B: REST API
uvicorn conduit.api.main:app --reload

Step 2: Check your node

Verify Conduit can talk to your Lightning node:

# MCP tool call:
get_node_info

# Response:
# Node Alias: MyNode
# Pubkey: 02abc...
# Active Channels: 3
# Synced to Chain: True

Step 3: Discover a skill

discover_skills(query="translate", max_price_sats=100)

# Response:
# [abc-123] English to Spanish Translation
#   Category: translation | Price: 50 sats
#   Provider: LangBot

Step 4: Request execution

request_skill_execution(
    skill_id="abc-123",
    input_data={"text": "Hello world"}
)

# Response:
# Price: 50 sats
# Pay this invoice:
# Payment Request: lnbc500n1p...

Step 5: Pay the invoice

pay_invoice(payment_request="lnbc500n1p...")

# Response:
# Payment Successful!
# Amount: 50 sats
# Preimage: 0a1b2c3d...

Step 6: Confirm and get results

confirm_skill_execution(
    execution_id="exec-456",
    payment_preimage="0a1b2c3d..."
)

# Response:
# Skill Executed Successfully!
# Output: {"translated_text": "Hola mundo"}

Step 7: Rate the skill

submit_rating(
    execution_id="exec-456",
    score=5,
    payment_preimage="0a1b2c3d...",
    comment="Fast and accurate"
)

# Rating requires payment proof  - no fake reviews.

Lightning Tools 6 tools

Core Lightning Network operations - create invoices, send payments, check balances, and inspect transactions.

Marketplace Tools 7 tools

Discover, register, execute, and rate skills on the Conduit marketplace.

Security Tools 6 tools

Spending limits, macaroon-scoped authorization, anomaly detection, and provider verification.

Nostr Tools 4 tools

Publish and discover skills on Nostr relays for decentralized, censorship-resistant discovery.

L402 Tools 3 tools

HTTP 402 Payment Required meets Lightning. Pay-per-request API access without API keys.

Architecture

Conduit sits between AI agents and the Lightning Network. Every request passes through three middleware layers before reaching your node:

• Rate Limiting - per-tool sliding window with 429 + Retry-After headers
• L402 / API Key Auth - either a pre-shared API key or pay-per-request L402 tokens
• Verification Enforcement - warn or block unverified providers based on policy

The core layer provides 26 MCP tools and REST API endpoints covering Lightning payments, a skill marketplace, Nostr discovery, macaroon auth, spending limits, and anomaly detection.

At the bottom is your LND node - your channels, your sats, your keys. Conduit coordinates but never takes custody.

Macaroon Auth

Macaroons are bearer tokens with intersection semantics. Unlike API keys (all-or-nothing), macaroons can be attenuated: you can take an admin macaroon and derive a restricted version that only allows read operations or only marketplace tools.

Conduit ships with four built-in profiles:

• admin - full access to all 26 tools
• readonly - view balances, discover skills, check status (no payments, no writes)
• marketplace - skill discovery and execution only (no direct Lightning operations)
• spending - Lightning payments + skill execution (no skill registration)

Use create_macaroon to mint tokens for different agents with appropriate access levels.

Spending Limits

Spending limits prevent runaway costs from AI agents. Every payment goes through four checks:

• Per-payment cap - reject any single payment above the limit
• Hourly limit - sliding window, resets automatically
• Daily limit - 24-hour sliding window
• Confirmation threshold - payments above this amount require human approval via a one-shot confirmation token

The confirmation token is cryptographically bound to the specific payment (tool, amount, payment hash) and expires in ~2 minutes. An agent cannot bypass this by simply retrying.

Provider Verification

Verification proves a skill provider is who they claim to be. Two methods:

• Node verification - the provider signs a challenge message with their Lightning node's private key using lncli signmessage. This proves they control a real, funded node.
• Domain verification - the provider places a challenge file at https://example.com/.well-known/conduit-verify.txt. This proves they control the domain via DNS TXT record verification.

Verification badges are shown in marketplace listings. Badges expire and must be renewed periodically to ensure ongoing control.

Nostr Discovery

Nostr is a simple, decentralized protocol for publishing and subscribing to events via relays. Conduit uses Nostr (kind 38383 events) for skill discovery that doesn't depend on any central marketplace.

When you publish a skill to Nostr, it's broadcast to multiple relays. Any Conduit node anywhere in the world can discover it by querying those relays. There's no registration, no approval process, no gatekeeping.

Your Nostr identity is a cryptographic keypair. The public key (npub) becomes your identity on the network. Configure NOSTR_PRIVATE_KEY in your .env to persist your identity across restarts.