conduit-btc 0.8.4__tar.gz

conduit_btc-0.8.4/LICENSE

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

conduit_btc-0.8.4/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: conduit-btc
+Version: 0.8.4
+Summary: Self-hosted, non-custodial Bitcoin Lightning payments for autonomous AI agents — your node, your keys, your rules.
+Author: Jake Knowles
+License: MIT
+Project-URL: Homepage, https://github.com/Jake1848/conduit
+Project-URL: Documentation, https://github.com/Jake1848/conduit
+Project-URL: Repository, https://github.com/Jake1848/conduit
+Project-URL: Issues, https://github.com/Jake1848/conduit/issues
+Keywords: bitcoin,lightning,ai-agents,payments,lnd,self-hosted,non-custodial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# conduit-btc
+
+Python SDK for **Conduit** — self-hosted, non-custodial Bitcoin Lightning
+payment infrastructure for autonomous AI agents.
+
+**Your node, your keys, your rules.** Conduit is software tooling that you run
+on your own infrastructure, against your own LND node, with your own keys. It
+never touches your funds — it's a thin client for *your* Conduit instance.
+
+```bash
+pip install conduit-btc
+```
+
+> The importable package is `conduit`:
+>
+> ```python
+> from conduit import Agent
+> ```
+
+## Quickstart
+
+Point the SDK at the Conduit instance you deployed (a 5-minute Docker deploy
+against your own LND node), create an agent, and send a payment:
+
+```python
+import conduit
+from conduit import Agent
+
+# Connect to YOUR self-hosted Conduit instance
+conduit.api_key = "ck_live_..."              # an API key from your instance
+conduit.base_url = "https://conduit.example.com"  # your Conduit URL
+
+# Create an autonomous wallet with an optional spending policy
+agent = Agent.create(name="compute-router-7", daily_limit=50_000)
+
+agent.policy.attach(
+    max_per_hour=10_000,
+    allowlist=["02beef..."],
+)
+
+# Send a Lightning payment
+receipt = agent.pay(
+    to="compute-node-7@lnd.example.com",
+    sats=150,
+    memo="dataset query",
+)
+
+print(receipt.hash, receipt.settled_in_ms)
+print(receipt.fee_sats, receipt.platform_fee_sats)
+```
+
+## Client-centric API (`ConduitClient`)
+
+Prefer a single client object with explicit methods over the `Agent`
+active-record style? `ConduitClient` wraps the same retrying, idempotent HTTP
+client and adds operator funding (`credit_agent`) — from `pip install` to a
+settled payment in a few lines:
+
+```python
+from conduit import ConduitClient
+
+client = ConduitClient(base_url="https://conduit.example.com", api_key="ck_live_...")
+
+agent = client.create_agent("compute-router-7")
+client.credit_agent(agent.id, sats=10_000)            # operator funds the agent
+
+receipt = client.send_payment(agent.id, dest_pubkey="02beef...", sats=500)
+print(receipt.status, receipt.platform_fee_sats)      # 'settled', 2
+
+print(client.get_balance(agent.id).available)         # spendable sats
+for tx in client.list_transactions(agent.id):
+    print(tx.direction, tx.amount_sats, tx.status)
+```
+
+Both styles talk to the same instance — use whichever you prefer.
+
+## Platform fee on receipts
+
+Every payment receipt includes a **`platform_fee_sats`** field — the per-transaction
+platform fee in satoshis configured by the operator who deployed the instance.
+It is **separate** from `fee_sats` (the LND routing fee):
+
+- `fee_sats` — the Lightning Network routing fee paid to route the payment.
+- `platform_fee_sats` — the operator's usage-based revenue, charged on top, kept
+  on settle, and refunded in full if the payment fails.
+
+The fee is configured on your instance via `PLATFORM_FEE_PERCENT` (default `0.5`%),
+`PLATFORM_FEE_MIN_SATS` (default `1`), and `PLATFORM_FEE_MAX_SATS` (default `1000`).
+
+```python
+receipt = agent.pay(to="...", sats=10_000)
+print(receipt.amount_sats)        # 10000
+print(receipt.fee_sats)           # LND routing fee
+print(receipt.platform_fee_sats)  # your platform's per-tx revenue
+```
+
+## Configuration
+
+The SDK reads `CONDUIT_API_KEY` and `CONDUIT_API_URL` (default
+`https://api.conduit.energy`, the hosted demo console) from the environment.
+Set `CONDUIT_API_URL` to the URL of your own Conduit deployment.
+
+```bash
+export CONDUIT_API_KEY=ck_live_xxxxxxxxxxxxx
+export CONDUIT_API_URL=https://conduit.example.com
+```
+
+or explicitly in code:
+
+```python
+import conduit
+conduit.api_key = "ck_live_..."
+conduit.base_url = "https://conduit.example.com"
+```
+
+## Errors
+
+```python
+from conduit import PolicyViolation, InsufficientBalance, PaymentFailed
+
+try:
+    agent.pay(to=..., sats=...)
+except PolicyViolation as e:
+    print(e.code, e.message)  # e.g. "DAILY_LIMIT_EXCEEDED"
+```
+
+See the full error code list in the API docs.
+
+## Links
+
+- Repository: <https://github.com/Jake1848/conduit>
+- License: MIT

conduit_btc-0.8.4/README.md

@@ -0,0 +1,132 @@
+# conduit-btc
+
+Python SDK for **Conduit** — self-hosted, non-custodial Bitcoin Lightning
+payment infrastructure for autonomous AI agents.
+
+**Your node, your keys, your rules.** Conduit is software tooling that you run
+on your own infrastructure, against your own LND node, with your own keys. It
+never touches your funds — it's a thin client for *your* Conduit instance.
+
+```bash
+pip install conduit-btc
+```
+
+> The importable package is `conduit`:
+>
+> ```python
+> from conduit import Agent
+> ```
+
+## Quickstart
+
+Point the SDK at the Conduit instance you deployed (a 5-minute Docker deploy
+against your own LND node), create an agent, and send a payment:
+
+```python
+import conduit
+from conduit import Agent
+
+# Connect to YOUR self-hosted Conduit instance
+conduit.api_key = "ck_live_..."              # an API key from your instance
+conduit.base_url = "https://conduit.example.com"  # your Conduit URL
+
+# Create an autonomous wallet with an optional spending policy
+agent = Agent.create(name="compute-router-7", daily_limit=50_000)
+
+agent.policy.attach(
+    max_per_hour=10_000,
+    allowlist=["02beef..."],
+)
+
+# Send a Lightning payment
+receipt = agent.pay(
+    to="compute-node-7@lnd.example.com",
+    sats=150,
+    memo="dataset query",
+)
+
+print(receipt.hash, receipt.settled_in_ms)
+print(receipt.fee_sats, receipt.platform_fee_sats)
+```
+
+## Client-centric API (`ConduitClient`)
+
+Prefer a single client object with explicit methods over the `Agent`
+active-record style? `ConduitClient` wraps the same retrying, idempotent HTTP
+client and adds operator funding (`credit_agent`) — from `pip install` to a
+settled payment in a few lines:
+
+```python
+from conduit import ConduitClient
+
+client = ConduitClient(base_url="https://conduit.example.com", api_key="ck_live_...")
+
+agent = client.create_agent("compute-router-7")
+client.credit_agent(agent.id, sats=10_000)            # operator funds the agent
+
+receipt = client.send_payment(agent.id, dest_pubkey="02beef...", sats=500)
+print(receipt.status, receipt.platform_fee_sats)      # 'settled', 2
+
+print(client.get_balance(agent.id).available)         # spendable sats
+for tx in client.list_transactions(agent.id):
+    print(tx.direction, tx.amount_sats, tx.status)
+```
+
+Both styles talk to the same instance — use whichever you prefer.
+
+## Platform fee on receipts
+
+Every payment receipt includes a **`platform_fee_sats`** field — the per-transaction
+platform fee in satoshis configured by the operator who deployed the instance.
+It is **separate** from `fee_sats` (the LND routing fee):
+
+- `fee_sats` — the Lightning Network routing fee paid to route the payment.
+- `platform_fee_sats` — the operator's usage-based revenue, charged on top, kept
+  on settle, and refunded in full if the payment fails.
+
+The fee is configured on your instance via `PLATFORM_FEE_PERCENT` (default `0.5`%),
+`PLATFORM_FEE_MIN_SATS` (default `1`), and `PLATFORM_FEE_MAX_SATS` (default `1000`).
+
+```python
+receipt = agent.pay(to="...", sats=10_000)
+print(receipt.amount_sats)        # 10000
+print(receipt.fee_sats)           # LND routing fee
+print(receipt.platform_fee_sats)  # your platform's per-tx revenue
+```
+
+## Configuration
+
+The SDK reads `CONDUIT_API_KEY` and `CONDUIT_API_URL` (default
+`https://api.conduit.energy`, the hosted demo console) from the environment.
+Set `CONDUIT_API_URL` to the URL of your own Conduit deployment.
+
+```bash
+export CONDUIT_API_KEY=ck_live_xxxxxxxxxxxxx
+export CONDUIT_API_URL=https://conduit.example.com
+```
+
+or explicitly in code:
+
+```python
+import conduit
+conduit.api_key = "ck_live_..."
+conduit.base_url = "https://conduit.example.com"
+```
+
+## Errors
+
+```python
+from conduit import PolicyViolation, InsufficientBalance, PaymentFailed
+
+try:
+    agent.pay(to=..., sats=...)
+except PolicyViolation as e:
+    print(e.code, e.message)  # e.g. "DAILY_LIMIT_EXCEEDED"
+```
+
+See the full error code list in the API docs.
+
+## Links
+
+- Repository: <https://github.com/Jake1848/conduit>
+- License: MIT

conduit_btc-0.8.4/conduit/__init__.py

@@ -0,0 +1,64 @@
+"""Conduit — Bitcoin Lightning payments for autonomous AI agents.
+
+    from conduit import Agent, Policy
+
+    agent = Agent.create(name="compute-router-7", daily_limit=50_000)
+    agent.policy.attach(max_per_hour=10_000, allowlist=["02beef..."])
+    receipt = agent.pay(to="compute-node-7@lnd.conduit.energy", sats=150, memo="dataset")
+    print(receipt.hash, receipt.settled_in_ms)
+"""
+
+from .agent import Agent, Balance, LedgerAdjustment
+from .client import Conduit, default_client, set_default_client
+from .conduit_client import ConduitClient
+from .errors import (
+    AgentNotFound,
+    AuthenticationError,
+    ConduitError,
+    InsufficientBalance,
+    PaymentFailed,
+    PermissionDenied,
+    PolicyViolation,
+    RateLimited,
+    WebhookVerificationError,
+)
+from .invoice import Invoice
+from .payment import Receipt
+from .policy import Policy
+from .transaction import Transaction
+from .webhook import parse_webhook, verify_webhook
+
+# Module-level config — populated from CONDUIT_API_KEY / CONDUIT_API_URL env vars
+# lazily on first use. See client.py.
+api_key: str | None = None
+base_url: str | None = None
+
+__version__ = "0.8.4"
+
+__all__ = [
+    "Agent",
+    "ConduitClient",
+    "Conduit",
+    "Balance",
+    "LedgerAdjustment",
+    "default_client",
+    "set_default_client",
+    "Policy",
+    "Receipt",
+    "Invoice",
+    "Transaction",
+    "ConduitError",
+    "AuthenticationError",
+    "PermissionDenied",
+    "PolicyViolation",
+    "InsufficientBalance",
+    "PaymentFailed",
+    "AgentNotFound",
+    "RateLimited",
+    "WebhookVerificationError",
+    "verify_webhook",
+    "parse_webhook",
+    "api_key",
+    "base_url",
+    "__version__",
+]

conduit_btc-0.8.4/conduit/agent.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from .client import Conduit, default_client
+from .invoice import Invoice
+from .payment import Receipt, _parse_dt
+from .policy import Policy
+from .transaction import Transaction
+
+
+def _new_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+@dataclass
+class Balance:
+    available: int
+    pending: int
+    total: int
+
+
+@dataclass
+class LedgerAdjustment:
+    """Result of an operator credit/debit on an agent's virtual balance."""
+
+    agent_id: str
+    transaction_id: str
+    delta_sats: int  # positive = credit, negative = debit
+    balance_sats: int
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "LedgerAdjustment":
+        return cls(
+            agent_id=data["agent_id"],
+            transaction_id=data["transaction_id"],
+            delta_sats=int(data["delta_sats"]),
+            balance_sats=int(data["balance_sats"]),
+        )
+
+
+class Agent:
+    """An autonomous wallet with optional spending policy.
+
+    Mirrors the website code panel:
+
+        agent = Agent.create(name="compute-router-7", daily_limit=50_000)
+        agent.policy.attach(max_per_hour=10_000, allowlist=["02beef..."])
+        receipt = agent.pay(to="compute-node-7@lnd.conduit.energy",
+                            sats=150, memo="dataset query")
+    """
+
+    def __init__(
+        self,
+        *,
+        id: str,
+        name: str,
+        pubkey: str | None,
+        active: bool,
+        created_at: datetime,
+        client: Conduit | None = None,
+    ) -> None:
+        self.id = id
+        self.name = name
+        self.pubkey = pubkey
+        self.active = active
+        self.created_at = created_at
+        self._client = client or default_client()
+        self.policy = Policy(self, client=self._client)
+
+    # --- factory methods ---
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        daily_limit: int | None = None,
+        metadata: dict[str, Any] | None = None,
+        *,
+        client: Conduit | None = None,
+    ) -> "Agent":
+        c = client or default_client()
+        payload: dict[str, Any] = {"name": name}
+        if daily_limit is not None:
+            payload["daily_limit"] = daily_limit
+        if metadata is not None:
+            payload["metadata"] = metadata
+        data = c.post("/v1/agents", json=payload)
+        return cls._from_api(data, client=c)
+
+    @classmethod
+    def get(cls, agent_id: str, *, client: Conduit | None = None) -> "Agent":
+        c = client or default_client()
+        data = c.get(f"/v1/agents/{agent_id}")
+        return cls._from_api(data, client=c)
+
+    @classmethod
+    def list(cls, *, client: Conduit | None = None) -> list["Agent"]:
+        c = client or default_client()
+        # The API paginates /v1/agents (default 50, max 500). Page through with
+        # has_more so the whole fleet is returned, never silently truncated (M7).
+        items: list[dict[str, Any]] = []
+        offset = 0
+        for _ in range(200):  # safety cap (100k agents)
+            data = c.get("/v1/agents", params={"limit": 500, "offset": offset})
+            page = data.get("data", [])
+            items.extend(page)
+            if not data.get("has_more") or not page:
+                break
+            offset += 500
+        return [cls._from_api(item, client=c) for item in items]
+
+    @classmethod
+    def _from_api(cls, data: dict[str, Any], client: Conduit) -> "Agent":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            pubkey=data.get("pubkey"),
+            active=bool(data.get("active", True)),
+            created_at=_parse_dt(data["created_at"]),
+            client=client,
+        )
+
+    # --- actions ---
+
+    def pay(
+        self,
+        *,
+        to: str,
+        sats: int,
+        memo: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Receipt:
+        """Pay a Lightning address (`name@host`) or a BOLT11 invoice.
+
+        An `Idempotency-Key` is sent automatically (a fresh UUID4 if you don't
+        provide one) so an automatic retry can never double-pay. Pass an
+        explicit `idempotency_key` to make a manual retry idempotent too.
+        """
+        data = self._client.post(
+            "/v1/payments/pay",
+            json={
+                "agent_id": self.id,
+                "to": to,
+                "sats": sats,
+                "memo": memo,
+                "metadata": metadata,
+            },
+            idempotency_key=idempotency_key or _new_idempotency_key(),
+        )
+        return Receipt.from_api(data)
+
+    def send_invoice(
+        self,
+        payment_request: str,
+        *,
+        sats: int | None = None,
+        memo: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> Receipt:
+        """Pay a BOLT11 invoice (or zero-amount invoice with explicit sats)."""
+        data = self._client.post(
+            "/v1/payments/send",
+            json={
+                "agent_id": self.id,
+                "payment_request": payment_request,
+                "sats": sats,
+                "memo": memo,
+            },
+            idempotency_key=idempotency_key or _new_idempotency_key(),
+        )
+        return Receipt.from_api(data)
+
+    def keysend(
+        self,
+        dest_pubkey: str,
+        sats: int,
+        *,
+        memo: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> Receipt:
+        data = self._client.post(
+            "/v1/payments/send",
+            json={
+                "agent_id": self.id,
+                "dest_pubkey": dest_pubkey,
+                "sats": sats,
+                "memo": memo,
+            },
+            idempotency_key=idempotency_key or _new_idempotency_key(),
+        )
+        return Receipt.from_api(data)
+
+    def receive(
+        self, amount: int, *, memo: str | None = None, expiry: int = 3600
+    ) -> Invoice:
+        """Create a Lightning invoice that other agents/services can pay."""
+        data = self._client.post(
+            "/v1/invoices",
+            json={"agent_id": self.id, "amount": amount, "memo": memo, "expiry": expiry},
+        )
+        return Invoice.from_api(data)
+
+    def credit(
+        self,
+        sats: int,
+        *,
+        reason: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> "LedgerAdjustment":
+        """Operator top-up: credit this agent's virtual balance from the
+        operator's own node liquidity. Requires an admin-scope key."""
+        payload: dict[str, Any] = {"sats": sats}
+        if reason is not None:
+            payload["reason"] = reason
+        if metadata is not None:
+            payload["metadata"] = metadata
+        data = self._client.post(f"/v1/agents/{self.id}/credit", json=payload)
+        return LedgerAdjustment.from_api(data)
+
+    def debit(
+        self,
+        sats: int,
+        *,
+        reason: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> "LedgerAdjustment":
+        """Operator sweep: debit this agent's virtual balance back to the
+        operator's treasury. Requires an admin-scope key."""
+        payload: dict[str, Any] = {"sats": sats}
+        if reason is not None:
+            payload["reason"] = reason
+        if metadata is not None:
+            payload["metadata"] = metadata
+        data = self._client.post(f"/v1/agents/{self.id}/debit", json=payload)
+        return LedgerAdjustment.from_api(data)
+
+    @property
+    def balance(self) -> Balance:
+        data = self._client.get(f"/v1/agents/{self.id}/balance")
+        return Balance(
+            available=int(data["available_sats"]),
+            pending=int(data["pending_sats"]),
+            total=int(data["total_sats"]),
+        )
+
+    def transactions(self, *, limit: int = 50, direction: str | None = None) -> list[Transaction]:
+        params: dict[str, Any] = {"limit": limit}
+        if direction:
+            params["direction"] = direction
+        data = self._client.get(f"/v1/agents/{self.id}/transactions", params=params)
+        return [Transaction.from_api(item) for item in data.get("data", [])]
+
+    def deactivate(self) -> None:
+        self._client.delete(f"/v1/agents/{self.id}")
+        self.active = False
+
+    def __repr__(self) -> str:
+        return f"<Agent id={self.id!r} name={self.name!r} active={self.active}>"