Metadata-Version: 2.4
Name: conduit-lightning
Version: 0.1.0
Summary: Lightning Payment Rails for AI Agents — discover, pay for, and execute skills over Lightning via MCP or REST
Project-URL: Homepage, https://github.com/Lightning-Linq/Conduit
Project-URL: Repository, https://github.com/Lightning-Linq/Conduit
Project-URL: Issues, https://github.com/Lightning-Linq/Conduit/issues
Author: Lightning Linq
License: MIT License
        
        Copyright (c) 2026 Conduit-Agentic
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agents,bitcoin,l402,lightning,mcp,nostr,nwc,payments
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: alembic>=1.13.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: coincurve>=20.0.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: grpcio>=1.64.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: protobuf>=5.27.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pymacaroons>=0.13.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: qrcode[pil]>=7.4.0
Requires-Dist: redis>=5.0.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.30
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.64.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: publish
Requires-Dist: build>=1.2.0; extra == 'publish'
Requires-Dist: twine>=5.0.0; extra == 'publish'
Description-Content-Type: text/markdown

# Conduit

**Lightning Payment Rails for AI Agents** | by [Lightning Linq](https://lightninglinq.com)

Conduit is a non-custodial payment infrastructure layer that lets AI agents transact over the Lightning Network. It exposes a skill marketplace and Lightning tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), enabling any MCP-compatible AI (like Claude) to discover, purchase, and rate agent-provided services -- all settled instantly in Bitcoin.

Conduit never takes custody of funds. Payments flow directly between agents on Lightning. Conduit provides coordination, discovery, reputation, and security -- never custody.

> Conduit is the first product from **Lightning Linq**, an open-source company building Lightning infrastructure for AI agents.

## How It Works

```
┌──────────────────────────────────────────────────────────┐
│                     Claude Desktop                        │
│                  (or any MCP client)                      │
└──────────────┬───────────────────────────────────────────┘
               │ MCP (stdio)
               ▼
┌──────────────────────────────────────────────────────────┐
│                   Conduit MCP Server                      │
│                                                           │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐ │
│  │  Lightning   │  │  Marketplace │  │    Security      │ │
│  │   Tools      │  │    Tools     │  │    Layer         │ │
│  │             │  │              │  │                   │ │
│  │ • invoices  │  │ • discover   │  │ • API key auth   │ │
│  │ • payments  │  │ • register   │  │ • macaroons      │ │
│  │ • balance   │  │ • execute    │  │ • spending limits │ │
│  │ • decode    │  │ • rate       │  │ • rate limiting   │ │
│  │             │  │ • verify     │  │ • anomaly detect  │ │
│  └──────┬──────┘  └──────┬───────┘  └─────────────────┘ │
│         │                │                                │
└─────────┼────────────────┼────────────────────────────────┘
          │                │
          ▼                ▼
┌──────────────┐   ┌──────────────┐
│   LND Node   │   │  PostgreSQL  │
│  (your node) │   │  (local DB)  │
│              │   │              │
│  non-custodial   │  skills,     │
│  payments    │   │  executions, │
│              │   │  ratings,    │
│              │   │  audit logs  │
└──────────────┘   └──────────────┘
```

## Features

**Lightning Network Integration** — Create and pay invoices via your own LND node. Decode payment requests, check payment status, view node info and channel balances. Non-custodial: your keys, your node, your sats.

**Skill Marketplace** — Register skills with pricing, categories, and input/output schemas. Discover skills by keyword, category, or price range. Request executions with automatic Lightning invoicing. Webhook-based execution engine with payment proof delivery. Rating system backed by cryptographic payment proofs.

**Security Stack** — API key authentication, scoped macaroon authorization (8 permissions, 4 profiles), per-payment/hourly/daily spending limits, in-memory sliding window rate limiting, anomaly detection (self-payment, rapid repeat, structuring, volume spike), rating integrity (preimage verification, duplicate prevention, weighted averages), and provider verification via Lightning node signatures and domain proof.

## Quick Start

```bash
git clone https://github.com/Lightning-Linq/conduit.git
cd conduit
chmod +x install.sh
./install.sh
```

The install script handles everything: checks prerequisites (Python 3.11+, PostgreSQL), creates virtual environment, installs dependencies, generates a secure API key, sets up the database, runs migrations, and shows you how to wire it into Claude Desktop.

### Prerequisites

- **Python 3.11+** — `brew install python@3.11` or use pyenv
- **PostgreSQL 16** — `brew install postgresql@16 && brew services start postgresql@16`
- **LND node** — running and accessible (local, remote, or via Tor)

### Claude Desktop Configuration

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "conduit-lightning": {
      "command": "/path/to/conduit/.venv/bin/python",
      "args": ["-m", "conduit.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/conduit/src"
      }
    }
  }
}
```

Restart Claude Desktop. Ask Claude: *"What's my Lightning node balance?"*

## MCP Tools Reference

Conduit exposes 19 tools over the Model Context Protocol.

### Lightning Tools

| Tool | Permission | Description |
|------|-----------|-------------|
| `get_node_info` | lightning:read | Node alias, pubkey, active channels, peers |
| `get_balance` | lightning:read | On-chain and channel balances |
| `create_invoice` | lightning:invoice | Generate a Lightning invoice |
| `pay_invoice` | lightning:pay | Pay a Lightning invoice (with spending limits) |
| `decode_invoice` | lightning:read | Decode a payment request without paying |
| `check_payment` | lightning:read | Check if a payment has settled |

### Marketplace Tools

| Tool | Permission | Description |
|------|-----------|-------------|
| `discover_skills` | marketplace:read | Search skills by keyword, category, price |
| `get_skill_details` | marketplace:read | Full details including schemas and ratings |
| `register_skill` | marketplace:write | List a new skill on the marketplace |
| `request_skill_execution` | marketplace:execute | Request execution (generates invoice) |
| `confirm_skill_execution` | marketplace:execute | Confirm payment and trigger webhook |
| `submit_rating` | marketplace:execute | Rate a skill (requires payment proof) |

### Verification Tools

| Tool | Permission | Description |
|------|-----------|-------------|
| `request_verification` | marketplace:write | Start node or domain verification |
| `submit_verification` | marketplace:write | Complete verification with proof |
| `get_verification_status` | marketplace:read | Check a skill's verification badges |

### Security Tools

| Tool | Permission | Description |
|------|-----------|-------------|
| `get_spending_status` | security:read | Current spending vs. limits |
| `create_macaroon` | security:admin | Mint a scoped authorization token |
| `list_permissions` | security:read | Show active permissions |
| `get_anomaly_report` | security:read | View flagged suspicious patterns |

## Security Model

Conduit uses defense-in-depth with multiple security layers.

**Authentication** — An API key is required to start the server. Without it, the MCP server refuses to run.

**Authorization** — Macaroon-based scoping with 8 permission levels. Create restricted tokens for specific use cases (read-only, marketplace-only, spending-only).

**Spending Controls** — Configurable per-payment limits (default 10,000 sats), hourly caps (50,000 sats), daily caps (200,000 sats), and confirmation prompts for payments above a threshold.

**Rate Limiting** — Per-tool sliding window rate limits. Write operations are tightly limited (e.g., 5 skill registrations per 10 minutes). Read operations are generous (60/min).

**Anomaly Detection** — Runs after every payment and execution. Detects self-payment, rapid repeat transactions, structuring near limits, and volume spikes. Advisory mode: flags are logged but transactions aren't blocked.

**Rating Integrity** — Ratings require a payment preimage (SHA-256 proof of purchase). One rating per execution (enforced by unique constraint). 30-second minimum delay. Weighted averages discount repeat reviewers (1/n diminishing weight).

**Provider Verification** — Providers can prove identity via Lightning node signatures (`lncli signmessage`) or domain verification (`.well-known` URL). Verified skills display trust badges in marketplace listings.

## Configuration

All settings via environment variables or `.env`:

```bash
# API Key (required)
CONDUIT_API_KEY=your-secret-key

# LND Connection
LND_HOST=192.168.1.x
LND_GRPC_PORT=10009
LND_TLS_CERT_PATH=credentials/full-chain.pem
LND_MACAROON_PATH=credentials/admin.macaroon
LND_NETWORK=mainnet

# Database
DATABASE_URL=postgresql+asyncpg://conduit:conduit@localhost:5432/conduit

# Spending Limits (sats, 0 = no limit)
SPENDING_LIMIT_PER_PAYMENT_SATS=10000
SPENDING_LIMIT_HOURLY_SATS=50000
SPENDING_LIMIT_DAILY_SATS=200000
SPENDING_CONFIRM_ABOVE_SATS=5000

# Keep false for MCP servers (echo corrupts stdio transport)
DEBUG=false
```

## Project Structure

```
src/conduit/
├── mcp_server.py                # MCP server entry point — 19 tools
├── core/
│   ├── config.py                # Settings from .env
│   └── database.py              # Async SQLAlchemy + asyncpg
├── models/
│   ├── skill.py                 # Skill marketplace listings
│   ├── execution.py             # Skill execution tracking
│   ├── rating.py                # Payment-proof-backed ratings
│   ├── spending_log.py          # Spending audit trail
│   └── anomaly_flag.py          # Suspicious pattern flags
├── services/
│   ├── lnd.py                   # LND gRPC client (sign, verify, pay)
│   ├── spending_limiter.py      # Payment limit enforcement
│   ├── macaroon_auth.py         # Scoped authorization tokens
│   ├── rate_limiter.py          # Sliding window rate limits
│   ├── anomaly_detector.py      # Transaction pattern detection
│   ├── rating_integrity.py      # Anti-gaming for ratings
│   ├── provider_verification.py # Node + domain verification
│   └── skill_executor.py        # Webhook-based execution engine
└── alembic/                     # Database migrations
```

## Roadmap

- [x] Lightning Network integration (LND gRPC)
- [x] MCP server with 19 tools
- [x] Skill marketplace (register, discover, execute, rate)
- [x] PostgreSQL persistence with Alembic migrations
- [x] Full security stack (auth, macaroons, limits, anomaly detection)
- [x] Provider verification (Lightning node + domain)
- [x] One-command install script
- [x] Nostr protocol for decentralized skill discovery (NIP-01/19/33)
- [x] Nostr Wallet Connect (NWC) with NIP-44 v2 encryption
- [x] REST API layer alongside MCP (27 endpoints, FastAPI)
- [ ] Multi-node federation
- [ ] Package for distribution (`pip install conduit-lightning`)

## License

MIT — see [LICENSE](LICENSE).
