interline 0.1.0__tar.gz

interline-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Choppaaahh
+
+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.

interline-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: interline
+Version: 0.1.0
+Summary: Neutral, non-custodial MCP server that lets any AI agent pay across payment rails (x402 today, more landing) through one integration — rail-discovery + routing + a unified receipt ledger.
+License: MIT
+Keywords: mcp,model-context-protocol,x402,agent-payments,payment-router,agentic-payments,non-custodial,usdc,ai-agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: x402>=2.13
+Requires-Dist: eth-account>=0.13
+Requires-Dist: web3>=7.0
+Requires-Dist: fastapi>=0.110
+Provides-Extra: server
+Requires-Dist: uvicorn>=0.27; extra == "server"
+Dynamic: license-file
+
+# Interline (MCP server)
+
+**Rail-discovery + future-proof payments for AI agents — as an MCP server.**
+
+Two things your agent gets, **today**:
+1. **Discover** which payment rail(s) any paid endpoint accepts — *before* paying. (The discovery layer single-rail clients don't have.)
+2. **Pay** through it — non-custodial, your own key, capped.
+
+And the part that pays off across **every rail**: **integrate once.** Three rails are live today — [x402](https://x402.org) (HTTP 402 + USDC) on EVM (Base Sepolia) and on Solana (devnet), plus **MPP** on Tempo (Moderato testnet) — all behind the *same tool*. Real on-chain agent-to-agent settles are confirmed on all three. Every future rail drops in with **zero code change**. **Never re-integrate agent payments again** — when the next rail ships, your agent already speaks it.
+
+This is **not "another x402 MCP."** Single-rail clients make you wire up one rail (and re-wire for the next). This is the **discovery + routing layer above them** — same shape OpenRouter has for models. Non-custodial by design: payments use **your own wallet key**; this server never holds, sees, or routes funds through itself.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `discover_payment_rails(url)` | Probe a paid endpoint; report **which rails + prices** it accepts. **No payment.** The discovery layer. |
+| `pay_for_resource(url, task, max_price_usdc)` | Pay + fetch through the accepted rail; return content **+ a settlement receipt**. Never exceeds `max_price_usdc`. |
+| `payment_history(limit)` | The **unified cross-rail receipt ledger** — every settlement, every rail, one view. |
+
+## Install
+
+```bash
+pip install interline        # (or: uvx interline)
+```
+
+### Add to Claude Desktop / Cursor / any MCP client
+
+```jsonc
+{
+  "mcpServers": {
+    "interline": {
+      "command": "uvx",
+      "args": ["interline"],
+      "env": {
+        "APV0_BUYER_PRIVATE_KEY": "0x...",   // YOUR wallet key — stays in your env, never leaves your machine
+        "APV0_NETWORK": "base-sepolia"        // or "base" for mainnet
+      }
+    }
+  }
+}
+```
+
+Local dev (from a clone):
+
+```jsonc
+{ "mcpServers": { "interline": {
+    "command": "python", "args": ["-m", "mcp_router.server"],
+    "cwd": "/path/to/interline-routes",
+    "env": { "APV0_BUYER_PRIVATE_KEY": "0x...", "APV0_NETWORK": "base-sepolia" }
+}}}
+```
+
+`discover_payment_rails` needs no key (it only reads the 402 challenge). `pay_for_resource` needs `APV0_BUYER_PRIVATE_KEY` (your funded wallet).
+
+## Non-custodial guarantee
+
+- The router **never holds funds.** `discover` only reads a public 402 challenge; `pay` signs with **your** key, locally, bounded by `max_price_usdc`.
+- The fee model (when one exists) is a **software/routing fee billed to you, the developer — never a cut of the funds flow.** That's the line between software (this) and money transmission (not this).
+
+## Status
+
+Three rails live — x402 USDC on EVM (Base Sepolia) and on Solana (devnet), plus MPP on Tempo (Moderato testnet). Real on-chain agent-to-agent settles confirmed on all three. Neutral by construction: `discover_payment_rails` surfaces *any* rail an endpoint offers, and each additional rail is a drop-in adapter with no caller change. Built on the [interline-routes](https://github.com/Choppaaahh/interline-routes) rail-agnostic core.

interline-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Interline — agent-to-agent payment router
+
+An **agent-to-agent payment router**: one agent does work, another agent pays for
+it, no human keys a card. **Interline** is a neutral, non-custodial router over the
+fragmented agent-payment-rail stack — *"OpenRouter for agent payments."* Built on
+[x402](https://x402.org) (HTTP-402 micropayments, USDC), aggregator-shaped so adding
+a rail is one adapter, not a rewrite.
+
+Today it routes payments across **three live rails** — **x402** USDC on EVM
+(Base Sepolia) and on Solana (devnet), plus **MPP** on Tempo (Moderato testnet) —
+all behind one `Paywall.gate()` call. Real on-chain agent-to-agent settles are
+confirmed on all three. It ships an **MCP router** so agents can discover + pay
+endpoints, and includes a **Google-AP2 inbound adapter** — a signed AP2 mandate
+(verified, constraint-checked + freshness-gated) settles non-custodially on the rails.
+
+
+## Run the demo (no wallet, no faucet, no risk)
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python3 run_demo.py
+```
+
+Expected: `DEMO PASS — agent paid agent, settlement receipt issued`.
+
+What just happened (the x402 "exact-evm" loop):
+
+```
+buyer GET /work
+  -> seller 402 + PaymentRequirements {amount, asset=USDC, payTo, network}
+  -> buyer signs an EIP-3009 transferWithAuthorization (gasless USDC auth)
+  -> buyer retries with X-PAYMENT header (base64 signed payload)
+  -> facilitator VERIFIES the signature (real signer-recovery) + checks policy
+  -> facilitator SETTLES (mock: fake tx hash; live: on-chain USDC transfer)
+  -> seller 200 + work product + X-PAYMENT-RESPONSE receipt (tx hash)
+```
+
+The facilitator's verify step is **real cryptography** even in mock mode — it
+recovers the EIP-712 signer and matches it to the authorization. Only the
+on-chain broadcast is mocked. So a passing demo proves the buyer's signing is
+protocol-correct against real USDC.
+
+## Files
+
+| file | role |
+|---|---|
+| `router/paywall.py` | the reusable `Paywall` primitive — gate any endpoint behind x402 in one `.gate()` call |
+| `router/ledger.py` | settlement receipt-ledger → `logs/agent_payment_settlements.jsonl` (audit trail) |
+| `router/seller.py` | FastAPI agent that sells work — defines the requirements + work, wires one `Paywall.gate()` |
+| `router/buyer.py` | agent that auto-pays 402s (`pay_and_get`) with a client-side spend limit |
+| `router/eip3009.py` | the one crypto-subtle file: EIP-3009 typed-data, shared by buyer+facilitator so they can't drift |
+| `router/facilitator_mock.py` | in-process verify+settle (real sig check, mock chain) — the dry-run rail |
+| `router/facilitator_real.py` | live x402 facilitator over HTTP via the x402 SDK's own client; `get_facilitator()` picks mock↔real by config |
+| `router/config.py` | network/asset facts + `.env` loader; mock↔testnet↔mainnet is a one-line env change |
+| `run_demo.py` | end-to-end smoke (ephemeral keys, mock facilitator) |
+| `run_live.py` | live runner — settles a real x402 payment on Base Sepolia |
+
+## Go live (Base Sepolia testnet)
+
+1. **Two testnet wallets** (buyer signs, seller receives):
+   ```bash
+   python3 -c "from eth_account import Account; a=Account.create(); print('addr', a.address); print('key', a.key.hex())"
+   ```
+   Do this twice. Keep the keys out of git (use `.env`).
+2. **Fund the buyer** with Base Sepolia testnet USDC (Circle faucet) + a little
+   testnet ETH for any gas the facilitator relays.
+3. **`.env`** (copy `.env.example` → `.env`, it's gitignored + auto-loaded):
+   ```
+   APV0_NETWORK=base-sepolia
+   APV0_BUYER_PRIVATE_KEY=0x...        # buyer testnet key (signs)
+   APV0_SELLER_ADDRESS=0x...           # seller address (receives)
+   APV0_FACILITATOR_URL=https://x402.org/facilitator
+   ```
+4. **Run it live:**
+   ```bash
+   python3 run_live.py
+   ```
+   The seller now uses `RealFacilitator` (the x402 SDK's own facilitator client),
+   the buyer auto-pays the 402, and x402.org broadcasts the EIP-3009 USDC transfer
+   on-chain. You get a real tx hash → `https://sepolia.basescan.org/tx/<hash>`.
+
+   > Gasless: with EIP-3009 the **facilitator relays gas**, so the buyer only needs
+   > testnet **USDC**, not ETH.
+
+## Gate your own endpoint (the product primitive)
+
+```python
+from router.paywall import Paywall
+from router.facilitator_real import get_facilitator
+
+paywall = Paywall(get_facilitator(), my_requirements_fn)   # mock ↔ real by env
+
+@app.get("/my-endpoint")
+def my_endpoint(request: Request):
+    return paywall.gate(request, lambda: do_expensive_work())
+```
+
+That one `.gate()` call handles the whole x402 V2 dance — 402 challenge → verify →
+settle → record receipt → deliver — and appends every settlement to the
+receipt-ledger. The deployer never touches the protocol or holds a key.
+
+## v1 dogfood — pay an agent, get REAL work back
+
+v0 proved the *payment*. v1 proves the *loop*: a buyer agent pays → a seller agent
+does **real inference** → returns the result + a settlement receipt. The seller's
+`_do_the_work(task)` is the product's integration point (plug in your own
+model/compute/service).
+
+```bash
+APV0_OPENROUTER_KEY=sk-or-... python3 run_v1_dogfood.py "your task here"
+```
+→ `V1 DOGFOOD PASS — agent paid agent for real work ✅` (mock payment + real model
+call by default; set `APV0_NETWORK=base-sepolia` for a real on-chain settle under
+the same loop). Without a key it returns a stub so the product still runs.
+
+This is the authentic loop: an agent doing real work, metered + paid-for over
+x402 — the same primitive whether the work is a model call, a compute job, or
+any other billable agent task.
+

interline-0.1.0/interline.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: interline
+Version: 0.1.0
+Summary: Neutral, non-custodial MCP server that lets any AI agent pay across payment rails (x402 today, more landing) through one integration — rail-discovery + routing + a unified receipt ledger.
+License: MIT
+Keywords: mcp,model-context-protocol,x402,agent-payments,payment-router,agentic-payments,non-custodial,usdc,ai-agent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: x402>=2.13
+Requires-Dist: eth-account>=0.13
+Requires-Dist: web3>=7.0
+Requires-Dist: fastapi>=0.110
+Provides-Extra: server
+Requires-Dist: uvicorn>=0.27; extra == "server"
+Dynamic: license-file
+
+# Interline (MCP server)
+
+**Rail-discovery + future-proof payments for AI agents — as an MCP server.**
+
+Two things your agent gets, **today**:
+1. **Discover** which payment rail(s) any paid endpoint accepts — *before* paying. (The discovery layer single-rail clients don't have.)
+2. **Pay** through it — non-custodial, your own key, capped.
+
+And the part that pays off across **every rail**: **integrate once.** Three rails are live today — [x402](https://x402.org) (HTTP 402 + USDC) on EVM (Base Sepolia) and on Solana (devnet), plus **MPP** on Tempo (Moderato testnet) — all behind the *same tool*. Real on-chain agent-to-agent settles are confirmed on all three. Every future rail drops in with **zero code change**. **Never re-integrate agent payments again** — when the next rail ships, your agent already speaks it.
+
+This is **not "another x402 MCP."** Single-rail clients make you wire up one rail (and re-wire for the next). This is the **discovery + routing layer above them** — same shape OpenRouter has for models. Non-custodial by design: payments use **your own wallet key**; this server never holds, sees, or routes funds through itself.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `discover_payment_rails(url)` | Probe a paid endpoint; report **which rails + prices** it accepts. **No payment.** The discovery layer. |
+| `pay_for_resource(url, task, max_price_usdc)` | Pay + fetch through the accepted rail; return content **+ a settlement receipt**. Never exceeds `max_price_usdc`. |
+| `payment_history(limit)` | The **unified cross-rail receipt ledger** — every settlement, every rail, one view. |
+
+## Install
+
+```bash
+pip install interline        # (or: uvx interline)
+```
+
+### Add to Claude Desktop / Cursor / any MCP client
+
+```jsonc
+{
+  "mcpServers": {
+    "interline": {
+      "command": "uvx",
+      "args": ["interline"],
+      "env": {
+        "APV0_BUYER_PRIVATE_KEY": "0x...",   // YOUR wallet key — stays in your env, never leaves your machine
+        "APV0_NETWORK": "base-sepolia"        // or "base" for mainnet
+      }
+    }
+  }
+}
+```
+
+Local dev (from a clone):
+
+```jsonc
+{ "mcpServers": { "interline": {
+    "command": "python", "args": ["-m", "mcp_router.server"],
+    "cwd": "/path/to/interline-routes",
+    "env": { "APV0_BUYER_PRIVATE_KEY": "0x...", "APV0_NETWORK": "base-sepolia" }
+}}}
+```
+
+`discover_payment_rails` needs no key (it only reads the 402 challenge). `pay_for_resource` needs `APV0_BUYER_PRIVATE_KEY` (your funded wallet).
+
+## Non-custodial guarantee
+
+- The router **never holds funds.** `discover` only reads a public 402 challenge; `pay` signs with **your** key, locally, bounded by `max_price_usdc`.
+- The fee model (when one exists) is a **software/routing fee billed to you, the developer — never a cut of the funds flow.** That's the line between software (this) and money transmission (not this).
+
+## Status
+
+Three rails live — x402 USDC on EVM (Base Sepolia) and on Solana (devnet), plus MPP on Tempo (Moderato testnet). Real on-chain agent-to-agent settles confirmed on all three. Neutral by construction: `discover_payment_rails` surfaces *any* rail an endpoint offers, and each additional rail is a drop-in adapter with no caller change. Built on the [interline-routes](https://github.com/Choppaaahh/interline-routes) rail-agnostic core.

interline-0.1.0/interline.egg-info/SOURCES.txt

@@ -0,0 +1,29 @@
+LICENSE
+README.md
+pyproject.toml
+interline.egg-info/PKG-INFO
+interline.egg-info/SOURCES.txt
+interline.egg-info/dependency_links.txt
+interline.egg-info/entry_points.txt
+interline.egg-info/requires.txt
+interline.egg-info/top_level.txt
+mcp_router/README.md
+mcp_router/__init__.py
+mcp_router/discovery.py
+mcp_router/selftest.py
+mcp_router/server.py
+router/__init__.py
+router/buyer.py
+router/config.py
+router/facilitator_mock.py
+router/facilitator_real.py
+router/ledger.py
+router/paywall.py
+router/seller.py
+router/wallet.py
+router/inbound/__init__.py
+router/inbound/ap2_adapter.py
+router/rails/__init__.py
+router/rails/base.py
+router/rails/mpp_rail.py
+router/rails/x402_rail.py

interline-0.1.0/interline.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

interline-0.1.0/interline.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+interline = mcp_router.server:main

interline-0.1.0/interline.egg-info/requires.txt

@@ -0,0 +1,9 @@
+mcp>=1.0
+httpx>=0.28
+x402>=2.13
+eth-account>=0.13
+web3>=7.0
+fastapi>=0.110
+
+[server]
+uvicorn>=0.27

interline-0.1.0/interline.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+mcp_router
+router

interline-0.1.0/mcp_router/README.md

@@ -0,0 +1,63 @@
+# Interline (MCP server)
+
+**Rail-discovery + future-proof payments for AI agents — as an MCP server.**
+
+Two things your agent gets, **today**:
+1. **Discover** which payment rail(s) any paid endpoint accepts — *before* paying. (The discovery layer single-rail clients don't have.)
+2. **Pay** through it — non-custodial, your own key, capped.
+
+And the part that pays off across **every rail**: **integrate once.** Three rails are live today — [x402](https://x402.org) (HTTP 402 + USDC) on EVM (Base Sepolia) and on Solana (devnet), plus **MPP** on Tempo (Moderato testnet) — all behind the *same tool*. Real on-chain agent-to-agent settles are confirmed on all three. Every future rail drops in with **zero code change**. **Never re-integrate agent payments again** — when the next rail ships, your agent already speaks it.
+
+This is **not "another x402 MCP."** Single-rail clients make you wire up one rail (and re-wire for the next). This is the **discovery + routing layer above them** — same shape OpenRouter has for models. Non-custodial by design: payments use **your own wallet key**; this server never holds, sees, or routes funds through itself.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `discover_payment_rails(url)` | Probe a paid endpoint; report **which rails + prices** it accepts. **No payment.** The discovery layer. |
+| `pay_for_resource(url, task, max_price_usdc)` | Pay + fetch through the accepted rail; return content **+ a settlement receipt**. Never exceeds `max_price_usdc`. |
+| `payment_history(limit)` | The **unified cross-rail receipt ledger** — every settlement, every rail, one view. |
+
+## Install
+
+```bash
+pip install interline        # (or: uvx interline)
+```
+
+### Add to Claude Desktop / Cursor / any MCP client
+
+```jsonc
+{
+  "mcpServers": {
+    "interline": {
+      "command": "uvx",
+      "args": ["interline"],
+      "env": {
+        "APV0_BUYER_PRIVATE_KEY": "0x...",   // YOUR wallet key — stays in your env, never leaves your machine
+        "APV0_NETWORK": "base-sepolia"        // or "base" for mainnet
+      }
+    }
+  }
+}
+```
+
+Local dev (from a clone):
+
+```jsonc
+{ "mcpServers": { "interline": {
+    "command": "python", "args": ["-m", "mcp_router.server"],
+    "cwd": "/path/to/interline-routes",
+    "env": { "APV0_BUYER_PRIVATE_KEY": "0x...", "APV0_NETWORK": "base-sepolia" }
+}}}
+```
+
+`discover_payment_rails` needs no key (it only reads the 402 challenge). `pay_for_resource` needs `APV0_BUYER_PRIVATE_KEY` (your funded wallet).
+
+## Non-custodial guarantee
+
+- The router **never holds funds.** `discover` only reads a public 402 challenge; `pay` signs with **your** key, locally, bounded by `max_price_usdc`.
+- The fee model (when one exists) is a **software/routing fee billed to you, the developer — never a cut of the funds flow.** That's the line between software (this) and money transmission (not this).
+
+## Status
+
+Three rails live — x402 USDC on EVM (Base Sepolia) and on Solana (devnet), plus MPP on Tempo (Moderato testnet). Real on-chain agent-to-agent settles confirmed on all three. Neutral by construction: `discover_payment_rails` surfaces *any* rail an endpoint offers, and each additional rail is a drop-in adapter with no caller change. Built on the [interline-routes](https://github.com/Choppaaahh/interline-routes) rail-agnostic core.

interline-0.1.0/mcp_router/__init__.py

@@ -0,0 +1 @@
+"""Interline — MCP server: let any MCP agent pay across payment rails (neutral, non-custodial)."""

interline-0.1.0/mcp_router/discovery.py

@@ -0,0 +1,152 @@
+"""
+Rail discovery — given a paid endpoint, report which payment rails it accepts.
+
+THIS is the differentiator vs "another x402 payment MCP": one call tells an agent
+*every* way it could pay an endpoint, across whatever rails the endpoint offers —
+the neutral router's rail-discovery layer. Today x402 is live; as rails land (MPP, …)
+they surface in the same shape with zero caller change.
+
+The parse step (`parse_accepts`) is split from the network fetch (`discover_rails`) so
+the normalization is golden-fixture testable with no network.
+"""
+from __future__ import annotations
+
+import httpx
+
+# x402/MPP payment `scheme` → human rail name. Grows as rails land.
+# Unknown schemes fall through to themselves, so discovery still SURFACES a rail we don't
+# yet have a pretty name for (neutrality: report what's offered, don't hide it).
+SCHEME_TO_RAIL = {"exact": "x402", "mpp": "mpp"}
+
+# Default token decimals when not derivable from the challenge (USDC = 6).
+_DEFAULT_DECIMALS = 6
+
+
+def parse_accepts(body: dict) -> list[dict]:
+    """Pure: normalize an x402 402-challenge body's `accepts` array into a rail list."""
+    rails: list[dict] = []
+    for a in (body.get("accepts") or []):
+        scheme = a.get("scheme", "?")
+        extra = a.get("extra") or {}
+        amt = a.get("amount")
+        try:
+            human = f"{int(amt) / 10 ** _DEFAULT_DECIMALS:.6f} {extra.get('name', 'token')}"
+        except (TypeError, ValueError):
+            human = str(amt)
+        rails.append({
+            "rail": SCHEME_TO_RAIL.get(scheme, scheme),
+            "scheme": scheme,
+            "network": a.get("network"),
+            "asset": a.get("asset"),
+            "amount_atomic": amt,
+            "price": human,
+            "pay_to": a.get("payTo"),
+        })
+    return rails
+
+
+def discover_rails(url: str, timeout: float = 15.0) -> dict:
+    """GET `url`; if it returns a 402 challenge, report the rails it accepts. NO payment is made."""
+    try:
+        r = httpx.get(url, timeout=timeout, follow_redirects=True)
+    except Exception as e:  # noqa: BLE001 — surface the failure as data, don't raise into the agent
+        return {"url": url, "error": f"fetch failed: {e}", "rails": []}
+    if r.status_code != 402:
+        return {
+            "url": url, "paid": False, "status_code": r.status_code,
+            "note": "no 402 payment challenge (endpoint is free, or not an x402 resource)",
+            "rails": [],
+        }
+    try:
+        body = r.json()
+    except Exception:  # noqa: BLE001
+        return {"url": url, "paid": True, "error": "402 body was not JSON", "rails": []}
+    rails = parse_accepts(body)
+    return {
+        "url": url, "paid": True, "x402_version": body.get("x402Version"),
+        "rail_count": len(rails), "rails": rails,
+    }
+
+
+# ── known-rails capability registry ──────────────────────────────────────────
+# The neutral router is legible about the WHOLE landscape — including rails it does
+# NOT settle itself. `route_mode` is the honesty knob:
+#   native-settle = Interline settles this directly (x402) or via an inbound adapter
+#                   that lands on x402 (AP2). We move the funds.
+#   handoff       = Interline recognizes the protocol + routes an agent TO it, but does
+#                   NOT settle it — the protocol settles in its own world (Virtuals' own
+#                   x402 escrow; OpenAI/Stripe ACP's card-only delegated payment).
+KNOWN_RAILS = [
+    {
+        "name": "x402",
+        "kind": "settlement-rail",
+        "route_mode": "native-settle",
+        "networks": ["eip155 (EVM)", "solana (SVM)"],
+        "settle_asset": "USDC",
+        "what": "HTTP-402 micropayments. Interline settles natively across EVM + Solana behind one Paywall.",
+        "docs": "https://x402.org",
+    },
+    {
+        "name": "mpp",
+        "kind": "settlement-rail",
+        "route_mode": "native-settle",
+        "networks": ["tempo (stablecoin)"],
+        "settle_asset": "stablecoin",
+        "what": "Machine Payments Protocol (Stripe + Tempo, IETF draft-ryan-httpauth-payment). HTTP-402 "
+                "challenge/credential/receipt — convergent with x402, RFC-7235 framed. Interline settles it as "
+                "a second PROTOCOL behind the same Paywall (the cross-protocol wedge: pay an endpoint via x402 OR "
+                "mpp through one integration). Phase-1 runs the mock facilitator; live Tempo settle (official "
+                "pympp SDK) is gated on a funded Tempo wallet — no Stripe account required.",
+        "docs": "https://mpp.dev",
+    },
+    {
+        "name": "ap2",
+        "kind": "authorization-layer",
+        "route_mode": "native-settle",
+        "networks": ["eip155 (EVM)", "solana (SVM)"],
+        "settle_asset": "USDC",
+        "what": "Google Agent Payments Protocol — signed SD-JWT mandates. Interline's AP2 inbound adapter "
+                "verifies the mandate + constraints + freshness, then settles on x402. One seam for the "
+                "card/agent-commerce tier (UCP / Mastercard / Amex / PayPal all delegate to AP2).",
+        "docs": "https://github.com/google-agentic-commerce/AP2",
+    },
+    {
+        "name": "virtuals-acp",
+        "kind": "commerce-ecosystem",
+        "route_mode": "handoff",
+        "networks": ["eip155:8453 (Base)"],
+        "settle_asset": "USDC",
+        "what": "Virtuals Protocol Agent Commerce Protocol — a crypto-native agent marketplace running its OWN "
+                "x402 rail + on-chain escrow on Base. Interline routes an agent to it (handoff); it settles in "
+                "its own ecosystem, not ours. Python SDK: virtuals-acp.",
+        "docs": "https://whitepaper.virtuals.io/about-virtuals/agent-commerce-protocol-acp",
+    },
+    {
+        "name": "openai-stripe-acp",
+        "kind": "commerce-layer",
+        "route_mode": "handoff",
+        "networks": ["card / PSP networks"],
+        "settle_asset": "fiat (card)",
+        "what": "OpenAI/Stripe Agentic Commerce Protocol (ChatGPT Instant Checkout). Its delegated payment is "
+                "CARD-ONLY (payment_method_type=card, settled through PSP/card networks), so Interline routes an "
+                "agent to it (handoff) — our crypto rail can't be the settlement target.",
+        "docs": "https://github.com/agentic-commerce-protocol/agentic-commerce-protocol",
+    },
+]
+
+
+def known_rails_catalog() -> dict:
+    """The neutral router's full rail catalog — what Interline knows about + how it relates to each.
+
+    Separates rails Interline SETTLES natively (route_mode=native-settle: x402, AP2-via-adapter) from
+    protocols it ROUTES an agent to but does not settle (route_mode=handoff: Virtuals' own x402 escrow,
+    OpenAI/Stripe ACP's card-only delegated payment). Legibility over the whole landscape — reporting
+    every rail, including ones we don't move funds on — IS the neutral-router thesis."""
+    settles = [r["name"] for r in KNOWN_RAILS if r["route_mode"] == "native-settle"]
+    handoffs = [r["name"] for r in KNOWN_RAILS if r["route_mode"] == "handoff"]
+    return {
+        "rail_count": len(KNOWN_RAILS),
+        "native_settle": settles,
+        "handoff": handoffs,
+        "rails": KNOWN_RAILS,
+    }