bridgenode 0.1.0__tar.gz

bridgenode-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: bridgenode
+Version: 0.1.0
+Summary: Official Python SDK for BridgeNode — automated x402 payment auth for AI agents
+Author-email: BridgeNode <eli.BNx@proton.me>
+License: MIT
+Project-URL: Homepage, https://bridgenode.cc
+Project-URL: Source, https://github.com/BridgeNode/x402-client
+Project-URL: Tracker, https://github.com/BridgeNode/x402-client/issues
+Keywords: x402,payment,solana,ed25519,ai,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pynacl>=1.6.0
+Requires-Dist: base58>=2.1.0
+
+# bridgenode
+
+Official Python SDK for **BridgeNode** — automated x402 payment auth for AI agents.
+
+`pip install bridgenode`
+
+## Quick start
+
+```python
+from bridgenode import X402Client
+
+client = X402Client()
+print(f"My address: {client.address}")
+
+response = await client.request(messages=[
+    {"role": "user", "content": "Hello, who are you?"}
+])
+print(response["choices"][0]["message"]["content"])
+```
+
+## How it works
+
+1. Generates an ed25519 keypair (if none provided)
+2. Signs each request with a UUID nonce
+3. Sends X-Address / X-Signature / X-Nonce headers
+4. Handles 402, 401, 409 responses automatically
+
+## Install from source
+
+```bash
+cd bridgenode
+pip install -e .
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- httpx, pynacl, base58
+
+## License
+
+MIT — BridgeNode (https://bridgenode.cc)

bridgenode-0.1.0/README.md

@@ -0,0 +1,42 @@
+# bridgenode
+
+Official Python SDK for **BridgeNode** — automated x402 payment auth for AI agents.
+
+`pip install bridgenode`
+
+## Quick start
+
+```python
+from bridgenode import X402Client
+
+client = X402Client()
+print(f"My address: {client.address}")
+
+response = await client.request(messages=[
+    {"role": "user", "content": "Hello, who are you?"}
+])
+print(response["choices"][0]["message"]["content"])
+```
+
+## How it works
+
+1. Generates an ed25519 keypair (if none provided)
+2. Signs each request with a UUID nonce
+3. Sends X-Address / X-Signature / X-Nonce headers
+4. Handles 402, 401, 409 responses automatically
+
+## Install from source
+
+```bash
+cd bridgenode
+pip install -e .
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- httpx, pynacl, base58
+
+## License
+
+MIT — BridgeNode (https://bridgenode.cc)

bridgenode-0.1.0/bridgenode/__init__.py

@@ -0,0 +1,10 @@
+"""x402-client — Python SDK for x402 Payment Required protocol.
+
+Automatically handles HTTP 402 responses: detects payment challenges,
+generates ed25519 keys, signs nonces, and retries with proper auth headers.
+"""
+
+from .client import X402Client
+
+__version__ = "0.1.0"
+__all__ = ["X402Client"]

bridgenode-0.1.0/bridgenode/auth.py

@@ -0,0 +1,61 @@
+"""Ed25519 key generation and signing for x402 authentication."""
+
+import uuid
+from typing import Tuple
+
+import base58
+import nacl.encoding
+import nacl.signing
+
+
+def generate_keypair() -> Tuple[str, str]:
+    """Generate a new ed25519 keypair.
+
+    Returns:
+        Tuple of (private_key_base58, public_key_base58)
+    """
+    sk = nacl.signing.SigningKey.generate()
+    private_key = base58.b58encode(sk.encode() + sk.verify_key.encode()).decode()
+    public_key = base58.b58encode(sk.verify_key.encode()).decode()
+    return private_key, public_key
+
+
+def sign_nonce(nonce: str, private_key_base58: str) -> str:
+    """Sign a nonce with the given ed25519 private key.
+
+    Args:
+        nonce: The nonce string to sign (usually a UUID).
+        private_key_base58: Base58-encoded ed25519 private key.
+
+    Returns:
+        Base58-encoded 64-byte ed25519 signature.
+    """
+    priv_bytes = base58.b58decode(private_key_base58)
+    seed = priv_bytes[:32] if len(priv_bytes) > 32 else priv_bytes
+    sk = nacl.signing.SigningKey(seed)
+    signed = sk.sign(nonce.encode("utf-8"))
+    return base58.b58encode(signed.signature).decode()
+
+
+def generate_nonce() -> str:
+    """Generate a UUID v4 nonce for x402 authentication.
+
+    Returns:
+        UUID string (e.g., "123e4567-e89b-12d3-a456-426614174000")
+    """
+    return str(uuid.uuid4())
+
+
+def get_public_key(private_key_base58: str) -> str:
+    """Derive public key from private key.
+
+    Args:
+        private_key_base58: Base58-encoded ed25519 private key.
+
+    Returns:
+        Base58-encoded public key.
+    """
+    priv_bytes = base58.b58decode(private_key_base58)
+    seed = priv_bytes[:32] if len(priv_bytes) > 32 else priv_bytes
+    sk = nacl.signing.SigningKey(seed)
+    return base58.b58encode(sk.verify_key.encode()).decode()

bridgenode-0.1.0/bridgenode/client.py

@@ -0,0 +1,245 @@
+"""X402Client — automated x402 payment handler for BridgeNode and compatible endpoints.
+
+Usage:
+    client = X402Client(private_key="...")
+    response = client.request("https://bridgenode.cc/v1/inference", {
+        "messages": [{"role": "user", "content": "Hello"}]
+    })
+    print(response["choices"][0]["message"]["content"])
+"""
+
+import base64
+import json
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .auth import generate_keypair, generate_nonce, get_public_key, sign_nonce
+from .exceptions import X402AuthError, X402Error, X402InsufficientBalance, X402PaymentRequired
+
+logger = logging.getLogger("bridgenode")
+
+# Default BridgeNode URL
+BRIDGENODE_URL = "https://bridgenode.cc/v1/inference"
+# Default payment address (BridgeNode main wallet)
+BRIDGENODE_PAYMENT_ADDRESS = "BHMDv3ri3LBEZjEzJgDZeUiguVX7LmsCstTXbM3dL8rN"
+
+
+class X402Client:
+    """HTTP client that handles 402 Payment Required automatically.
+
+    On receiving a 402 response:
+    1. Parses the PAYMENT-REQUIRED header for payment terms
+    2. Generates a UUID nonce and signs it with ed25519
+    3. Retries the request with X-Address, X-Signature, X-Nonce headers
+
+    If no private_key is provided, a new keypair is generated automatically.
+    """
+
+    def __init__(
+        self,
+        private_key: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        """Initialize the x402 client.
+
+        Args:
+            private_key: Base58-encoded ed25519 private key. If None, generates a new one.
+            http_client: Optional httpx.AsyncClient for custom configuration.
+                         A new client is created if not provided.
+        """
+        if private_key:
+            self._private_key = private_key
+            self._public_key = get_public_key(private_key)
+        else:
+            self._private_key, self._public_key = generate_keypair()
+            logger.info(
+                "Generated new keypair. Address: %s\n"
+                "Keep this private key safe for future sessions:\n%s",
+                self._public_key, self._private_key,
+            )
+
+        self._http = http_client or httpx.AsyncClient(timeout=120.0)
+
+    @property
+    def address(self) -> str:
+        """Solana wallet address (ed25519 public key, base58)."""
+        return self._public_key
+
+    async def request(
+        self,
+        url: str = BRIDGENODE_URL,
+        messages: Optional[list] = None,
+        max_tokens: int = 256,
+        stream: bool = False,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """Send a request with automatic x402 payment handling.
+
+        First tries with auth headers. If server returns 402,
+        generates nonce, signs it, and retries.
+
+        Args:
+            url: The x402-protected endpoint URL.
+            messages: List of message dicts [{"role": "...", "content": "..."}].
+            max_tokens: Maximum output tokens (default 256).
+            stream: Enable SSE streaming (default False).
+            **kwargs: Additional JSON body fields.
+
+        Returns:
+            Response dict with choices and response_metadata.
+
+        Raises:
+            X402PaymentRequired: Server requires payment and client can't pay.
+            X402AuthError: Invalid signature or auth failure.
+            X402InsufficientBalance: Agent has insufficient balance.
+            X402Error: Other x402 protocol errors.
+        """
+        body = {
+            "messages": messages or [{"role": "user", "content": "Hello"}],
+            "max_tokens": max_tokens,
+            "stream": stream,
+            **kwargs,
+        }
+
+        # Generate nonce and sign for first attempt
+        nonce = generate_nonce()
+        signature = sign_nonce(nonce, self._private_key)
+
+        headers = {
+            "X-Address": self._public_key,
+            "X-Signature": signature,
+            "X-Nonce": nonce,
+            "Content-Type": "application/json",
+        }
+
+        logger.debug(
+            "Sending request to %s (address: %s...)", url, self._public_key[:12]
+        )
+
+        resp = await self._http.post(url, json=body, headers=headers)
+
+        if resp.status_code == 200:
+            return resp.json()
+
+        if resp.status_code == 402:
+            return await self._handle_402(resp, url, body)
+
+        if resp.status_code == 401:
+            raise X402AuthError(f"Invalid signature: {resp.text[:200]}")
+
+        if resp.status_code == 409:
+            # Nonce collision — retry with new nonce
+            logger.warning("Nonce conflict, retrying with new nonce")
+            new_nonce = generate_nonce()
+            new_sig = sign_nonce(new_nonce, self._private_key)
+            headers["X-Nonce"] = new_nonce
+            headers["X-Signature"] = new_sig
+            resp = await self._http.post(url, json=body, headers=headers)
+            if resp.status_code == 200:
+                return resp.json()
+            raise X402Error(f"Nonce conflict on retry: {resp.status_code} {resp.text[:200]}")
+
+        raise X402Error(f"Unexpected HTTP {resp.status_code}: {resp.text[:500]}")
+
+    async def _handle_402(
+        self,
+        resp: httpx.Response,
+        url: str,
+        body: dict,
+    ) -> Dict[str, Any]:
+        """Handle a 402 Payment Required response.
+
+        Parses the PAYMENT-REQUIRED header, extracts payment terms,
+        and retries with a fresh nonce and signature.
+
+        If the 402 is due to insufficient balance, raises X402InsufficientBalance.
+        """
+        payment_header = resp.headers.get("PAYMENT-REQUIRED", "")
+
+        if payment_header:
+            try:
+                payment_req = json.loads(base64.b64decode(payment_header).decode())
+                accepts = payment_req.get("accepts", [])
+                if accepts:
+                    terms = accepts[0]
+                    required_amount = terms.get("amount", "?")
+                    pay_to = terms.get("payTo", "?")
+                    network = terms.get("network", "?")
+
+                    logger.info(
+                        "Payment required: %s %s tokens to %s (network: %s)",
+                        required_amount, terms.get("asset", "USDC"), pay_to, network,
+                    )
+
+                    # Check if this is an insufficient balance response
+                    detail = resp.json() if resp.text else {}
+                    if isinstance(detail, dict) and detail.get("error") == "Insufficient balance":
+                        raise X402InsufficientBalance(
+                            f"Insufficient balance. Required: ${detail.get('required', '?')}, "
+                            f"Balance: ${detail.get('balance', '?')}, "
+                            f"Pay to: {detail.get('payTo', pay_to)}"
+                        )
+            except (json.JSONDecodeError, base64.binascii.Error, UnicodeDecodeError) as e:
+                logger.warning("Failed to parse PAYMENT-REQUIRED header: %s", e)
+
+        # Retry with fresh nonce (the previous nonce was never recorded)
+        new_nonce = generate_nonce()
+        new_sig = sign_nonce(new_nonce, self._private_key)
+        headers = {
+            "X-Address": self._public_key,
+            "X-Signature": new_sig,
+            "X-Nonce": new_nonce,
+            "Content-Type": "application/json",
+        }
+
+        retry_resp = await self._http.post(url, json=body, headers=headers)
+
+        if retry_resp.status_code == 200:
+            return retry_resp.json()
+
+        # Still failing — check again for insufficient balance
+        if retry_resp.status_code == 402:
+            detail = retry_resp.json() if retry_resp.text else {}
+            if isinstance(detail, dict) and isinstance(detail.get("detail"), dict):
+                err = detail["detail"]
+                if err.get("error") == "Insufficient balance":
+                    raise X402InsufficientBalance(
+                        f"Insufficient balance. Required: ${err.get('required', '?')}, "
+                        f"Balance: ${err.get('balance', '?')}, "
+                        f"Pay to: {err.get('payTo', BRIDGENODE_PAYMENT_ADDRESS)}"
+                    )
+
+            raise X402PaymentRequired(
+                f"Payment required. "
+                f"Deposit USDC to {BRIDGENODE_PAYMENT_ADDRESS} (Solana mainnet). "
+                f"Check balance at https://bridgenode.cc/v1/balance/{self._public_key}"
+            )
+
+        if retry_resp.status_code == 401:
+            raise X402AuthError(f"Signature rejected on retry: {retry_resp.text[:200]}")
+
+        raise X402Error(
+            f"Payment retry failed (HTTP {retry_resp.status_code}): {retry_resp.text[:500]}"
+        )
+
+    async def check_balance(self, address: Optional[str] = None) -> float:
+        """Check off-chain USDC balance on BridgeNode.
+
+        Args:
+            address: Solana wallet address. Uses client address if not provided.
+
+        Returns:
+            Balance in USDC.
+        """
+        addr = address or self._public_key
+        resp = await self._http.get(f"https://bridgenode.cc/v1/balance/{addr}")
+        if resp.status_code == 200:
+            data = resp.json()
+            return float(data.get("balance", 0.0))
+        raise X402Error(f"Balance check failed: HTTP {resp.status_code}")
+
+    async def close(self):
+        """Close the underlying HTTP client."""
+        await self._http.aclose()

bridgenode-0.1.0/bridgenode/exceptions.py

@@ -0,0 +1,20 @@
+"""Custom exceptions for x402-client."""
+
+
+class X402Error(Exception):
+    """Base exception for all x402-client errors."""
+
+
+class X402PaymentRequired(X402Error):
+    """Server returned 402 Payment Required and client could not pay.
+
+    This happens when no private key is configured or payment failed.
+    """
+
+
+class X402AuthError(X402Error):
+    """Authentication error - invalid signature or address mismatch."""
+
+
+class X402InsufficientBalance(X402Error):
+    """Server returned 402 with insufficient balance."""

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

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: bridgenode
+Version: 0.1.0
+Summary: Official Python SDK for BridgeNode — automated x402 payment auth for AI agents
+Author-email: BridgeNode <eli.BNx@proton.me>
+License: MIT
+Project-URL: Homepage, https://bridgenode.cc
+Project-URL: Source, https://github.com/BridgeNode/x402-client
+Project-URL: Tracker, https://github.com/BridgeNode/x402-client/issues
+Keywords: x402,payment,solana,ed25519,ai,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pynacl>=1.6.0
+Requires-Dist: base58>=2.1.0
+
+# bridgenode
+
+Official Python SDK for **BridgeNode** — automated x402 payment auth for AI agents.
+
+`pip install bridgenode`
+
+## Quick start
+
+```python
+from bridgenode import X402Client
+
+client = X402Client()
+print(f"My address: {client.address}")
+
+response = await client.request(messages=[
+    {"role": "user", "content": "Hello, who are you?"}
+])
+print(response["choices"][0]["message"]["content"])
+```
+
+## How it works
+
+1. Generates an ed25519 keypair (if none provided)
+2. Signs each request with a UUID nonce
+3. Sends X-Address / X-Signature / X-Nonce headers
+4. Handles 402, 401, 409 responses automatically
+
+## Install from source
+
+```bash
+cd bridgenode
+pip install -e .
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- httpx, pynacl, base58
+
+## License
+
+MIT — BridgeNode (https://bridgenode.cc)

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+bridgenode/__init__.py
+bridgenode/auth.py
+bridgenode/client.py
+bridgenode/exceptions.py
+bridgenode.egg-info/PKG-INFO
+bridgenode.egg-info/SOURCES.txt
+bridgenode.egg-info/dependency_links.txt
+bridgenode.egg-info/entry_points.txt
+bridgenode.egg-info/requires.txt
+bridgenode.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+x402-demo = bridgenode.__main__:main

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

@@ -0,0 +1,3 @@
+httpx>=0.28.0
+pynacl>=1.6.0
+base58>=2.1.0

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

@@ -0,0 +1 @@
+bridgenode

bridgenode-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bridgenode"
+version = "0.1.0"
+description = "Official Python SDK for BridgeNode — automated x402 payment auth for AI agents"
+authors = [
+    {name = "BridgeNode", email = "eli.BNx@proton.me"},
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+keywords = ["x402", "payment", "solana", "ed25519", "ai", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "httpx>=0.28.0",
+    "pynacl>=1.6.0",
+    "base58>=2.1.0",
+]
+
+[project.urls]
+Homepage = "https://bridgenode.cc"
+Source = "https://github.com/BridgeNode/x402-client"
+Tracker = "https://github.com/BridgeNode/x402-client/issues"
+
+[project.scripts]
+x402-demo = "bridgenode.__main__:main"

bridgenode-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+