aifinpay-agent 0.1.0a1__tar.gz

aifinpay_agent-0.1.0a1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: aifinpay-agent
+Version: 0.1.0a1
+Summary: Non-custodial x402 payment client for autonomous AI agents on AiFinPay (Solana + Polygon)
+Author-email: "CoinSecurities (SECCO)" <contact@aifinpay.company>
+License: MIT
+Project-URL: Homepage, https://aifinpay.company
+Project-URL: Documentation, https://aifinpay.company/docs
+Project-URL: Repository, https://github.com/enot3615/oracle-financial-hub-59
+Project-URL: Issues, https://github.com/enot3615/oracle-financial-hub-59/issues
+Keywords: x402,ai-agent,solana,polygon,payments,non-custodial,ed25519
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyNaCl>=1.5
+Requires-Dist: base58>=2.1
+Requires-Dist: requests>=2.28
+
+# aifinpay-agent (Python)
+
+Non-custodial x402 payment client for autonomous AI agents on
+[AiFinPay](https://aifinpay.company).
+
+The Ed25519 keypair is generated locally and never leaves your process. The
+SDK only sends a one-time SHA-256 + Ed25519 signature in the `x-signature`
+header to authenticate against AiFinPay-protected endpoints.
+
+## Install
+
+```bash
+pip install aifinpay-agent
+```
+
+## Quick start
+
+```python
+from aifinpay import Agent
+
+# Generate a fresh keypair locally — never transmitted
+agent = Agent.new()
+print("Fund this address:", agent.address)
+print("Save this secret:", agent.secret_b58)  # store securely!
+
+# Wait until the wallet has at least $0.01 worth on-chain
+agent.wait_for_funding(min_usd_cents=1)
+
+# Request an invoice for a Seat (USDC on Solana)
+invoice = agent.reserve_seat_invoice(amount_usd=1.00, asset="USDC")
+print("Invoice:", invoice.raw)
+# Build + sign + submit the Solana transaction with @solana/web3.js, anchorpy,
+# or solana-py — the invoice contains program_id, treasury_vault, mints, etc.
+
+# Once the Seat is on-chain, any AiFinPay-gated endpoint just works:
+resp = agent.get("https://aifinpay.company/api/stats")
+print(resp.json())
+```
+
+## Loading an existing keypair
+
+```python
+# from solana-keygen JSON file
+agent = Agent.from_keypair_file("~/agent-wallet.json")
+
+# from base58 secret string
+agent = Agent.from_secret_b58("3RvZm7Gw...")
+```
+
+## How x402 auth works under the hood
+
+For every gated request the SDK:
+
+1. `GET /nonce` → receives a one-time UUID with 60s TTL
+2. computes `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`
+3. signs with Ed25519, base58-encodes the signature
+4. retries the original request with headers:
+   - `x-agent-pubkey: <base58 pubkey>`
+   - `x-nonce: <uuid>`
+   - `x-signature: <base58 sig>`
+
+The server verifies the signature, checks the agent has a live Seat PDA
+on-chain, and serves the resource.
+
+## Privacy
+
+- **The server never sees your private key.** Period.
+- Nonces are consumed on use; replay-resistant.
+- All transactions are public and on-chain — Solana + Polygon mainnet.
+
+## License
+
+MIT.

aifinpay_agent-0.1.0a1/README.md

@@ -0,0 +1,73 @@
+# aifinpay-agent (Python)
+
+Non-custodial x402 payment client for autonomous AI agents on
+[AiFinPay](https://aifinpay.company).
+
+The Ed25519 keypair is generated locally and never leaves your process. The
+SDK only sends a one-time SHA-256 + Ed25519 signature in the `x-signature`
+header to authenticate against AiFinPay-protected endpoints.
+
+## Install
+
+```bash
+pip install aifinpay-agent
+```
+
+## Quick start
+
+```python
+from aifinpay import Agent
+
+# Generate a fresh keypair locally — never transmitted
+agent = Agent.new()
+print("Fund this address:", agent.address)
+print("Save this secret:", agent.secret_b58)  # store securely!
+
+# Wait until the wallet has at least $0.01 worth on-chain
+agent.wait_for_funding(min_usd_cents=1)
+
+# Request an invoice for a Seat (USDC on Solana)
+invoice = agent.reserve_seat_invoice(amount_usd=1.00, asset="USDC")
+print("Invoice:", invoice.raw)
+# Build + sign + submit the Solana transaction with @solana/web3.js, anchorpy,
+# or solana-py — the invoice contains program_id, treasury_vault, mints, etc.
+
+# Once the Seat is on-chain, any AiFinPay-gated endpoint just works:
+resp = agent.get("https://aifinpay.company/api/stats")
+print(resp.json())
+```
+
+## Loading an existing keypair
+
+```python
+# from solana-keygen JSON file
+agent = Agent.from_keypair_file("~/agent-wallet.json")
+
+# from base58 secret string
+agent = Agent.from_secret_b58("3RvZm7Gw...")
+```
+
+## How x402 auth works under the hood
+
+For every gated request the SDK:
+
+1. `GET /nonce` → receives a one-time UUID with 60s TTL
+2. computes `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`
+3. signs with Ed25519, base58-encodes the signature
+4. retries the original request with headers:
+   - `x-agent-pubkey: <base58 pubkey>`
+   - `x-nonce: <uuid>`
+   - `x-signature: <base58 sig>`
+
+The server verifies the signature, checks the agent has a live Seat PDA
+on-chain, and serves the resource.
+
+## Privacy
+
+- **The server never sees your private key.** Period.
+- Nonces are consumed on use; replay-resistant.
+- All transactions are public and on-chain — Solana + Polygon mainnet.
+
+## License
+
+MIT.

aifinpay_agent-0.1.0a1/aifinpay/__init__.py

@@ -0,0 +1,23 @@
+"""
+AiFinPay agent SDK — non-custodial x402 payment client.
+
+Quick start:
+
+    from aifinpay import Agent
+
+    agent = Agent.new()                 # generate fresh Ed25519 keypair locally
+    print("Fund:", agent.address)
+
+    agent.wait_for_funding(min_usd_cents=100)
+    invoice = agent.reserve_seat(amount_usd=1.00, asset="USDC")
+    receipt = agent.send_signed(invoice)
+
+    # any HTTP call to AiFinPay-protected endpoints auto-handles x402:
+    resp = agent.request("GET", "https://aifinpay.company/api/stats")
+"""
+
+from .client import Agent
+from .errors import AiFinPayError, FundingTimeoutError, X402Error
+
+__version__ = "0.1.0a1"
+__all__ = ["Agent", "AiFinPayError", "FundingTimeoutError", "X402Error"]

aifinpay_agent-0.1.0a1/aifinpay/client.py

@@ -0,0 +1,232 @@
+"""Low-level Agent client. Non-custodial: keypair never leaves this process."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import nacl.signing  # PyNaCl
+import base58
+import requests
+
+from .errors import (
+    AiFinPayError,
+    FundingTimeoutError,
+    SeatNotFoundError,
+    X402Error,
+)
+
+DEFAULT_BASE_URL = "https://aifinpay.company"
+DEFAULT_TIMEOUT = 30  # seconds
+
+
+@dataclass
+class Invoice:
+    """An on-chain payment invoice returned by the AiFinPay backend."""
+
+    amount_usd: float
+    treasury_vault: str
+    program_id: str
+    nonce: str
+    raw: Dict[str, Any]
+
+
+class Agent:
+    """A non-custodial AiFinPay agent.
+
+    The Ed25519 keypair lives only in this Python process. The SDK never
+    transmits the secret key; only ``signature(SHA256("AiFinPay-x402:{nonce}:{pubkey}"))``
+    is sent in the ``x-signature`` header.
+    """
+
+    def __init__(
+        self,
+        signing_key: nacl.signing.SigningKey,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+    ):
+        self._sk = signing_key
+        self._vk = signing_key.verify_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers["User-Agent"] = "aifinpay-agent-py/0.1.0"
+
+    # ── Constructors ────────────────────────────────────────────────────────
+
+    @classmethod
+    def new(cls, **kwargs) -> "Agent":
+        """Generate a fresh Ed25519 keypair locally."""
+        return cls(nacl.signing.SigningKey.generate(), **kwargs)
+
+    @classmethod
+    def from_secret_b58(cls, secret_b58: str, **kwargs) -> "Agent":
+        """Load from a 64-byte base58 secret (Solana style: secret + pub)."""
+        raw = base58.b58decode(secret_b58)
+        if len(raw) == 64:
+            raw = raw[:32]
+        if len(raw) != 32:
+            raise AiFinPayError(
+                f"secret must decode to 32 or 64 bytes, got {len(raw)}"
+            )
+        return cls(nacl.signing.SigningKey(raw), **kwargs)
+
+    @classmethod
+    def from_keypair_file(cls, path: str, **kwargs) -> "Agent":
+        """Load a Solana CLI ``solana-keygen`` JSON file (array of 64 ints)."""
+        with open(path) as f:
+            arr = json.load(f)
+        if not isinstance(arr, list) or len(arr) != 64:
+            raise AiFinPayError(f"{path}: expected 64-byte array")
+        return cls(nacl.signing.SigningKey(bytes(arr[:32])), **kwargs)
+
+    # ── Public properties ──────────────────────────────────────────────────
+
+    @property
+    def address(self) -> str:
+        """Solana base58 public key."""
+        return base58.b58encode(bytes(self._vk)).decode()
+
+    @property
+    def secret_b58(self) -> str:
+        """Base58-encoded secret. Save this somewhere safe."""
+        return base58.b58encode(bytes(self._sk) + bytes(self._vk)).decode()
+
+    # ── Manifesto / discovery ──────────────────────────────────────────────
+
+    def manifesto(self) -> Dict[str, Any]:
+        r = self._session.get(
+            f"{self.base_url}/manifesto.json", timeout=self.timeout
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def well_known(self) -> Dict[str, Any]:
+        r = self._session.get(
+            f"{self.base_url}/.well-known/x402.json", timeout=self.timeout
+        )
+        r.raise_for_status()
+        return r.json()
+
+    # ── x402 auth ──────────────────────────────────────────────────────────
+
+    def _fetch_nonce(self) -> Dict[str, Any]:
+        r = self._session.get(f"{self.base_url}/nonce", timeout=self.timeout)
+        r.raise_for_status()
+        return r.json()
+
+    def _sign_nonce(self, nonce: str) -> str:
+        msg = f"AiFinPay-x402:{nonce}:{self.address}".encode()
+        digest = hashlib.sha256(msg).digest()
+        sig = self._sk.sign(digest).signature
+        return base58.b58encode(sig).decode()
+
+    def auth_headers(self) -> Dict[str, str]:
+        """Build a fresh x402 header set (nonces are one-time, 60s TTL)."""
+        nonce_info = self._fetch_nonce()
+        nonce = nonce_info["nonce"]
+        return {
+            "x-agent-pubkey": self.address,
+            "x-nonce": nonce,
+            "x-signature": self._sign_nonce(nonce),
+        }
+
+    # ── Funding / Seat ────────────────────────────────────────────────────
+
+    def has_seat(self) -> bool:
+        r = self._session.get(
+            f"{self.base_url}/api/seat/{self.address}", timeout=self.timeout
+        )
+        r.raise_for_status()
+        return bool(r.json().get("has_seat"))
+
+    def wait_for_funding(
+        self, min_usd_cents: int = 100, poll_seconds: int = 5, timeout: int = 600
+    ) -> None:
+        """Poll the leaderboard until this address shows up with at least
+        ``min_usd_cents`` reserved on its Seat. Raises FundingTimeoutError."""
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            r = self._session.get(
+                f"{self.base_url}/api/leaderboard?merge=true",
+                timeout=self.timeout,
+            )
+            r.raise_for_status()
+            for entry in r.json().get("leaderboard", []):
+                if entry.get("pubkey") == self.address:
+                    cents = int(float(entry.get("usd", 0)) * 100)
+                    if cents >= min_usd_cents:
+                        return
+            time.sleep(poll_seconds)
+        raise FundingTimeoutError(
+            f"address {self.address} never reached {min_usd_cents} cents on-chain"
+        )
+
+    # ── Invoices (server returns instructions, agent executes on-chain) ────
+
+    def reserve_seat_invoice(
+        self, amount_usd: float, asset: str = "USDC"
+    ) -> Invoice:
+        """Request an invoice for reserving a Seat. The returned ``raw`` dict
+        contains everything you need to build and submit the on-chain
+        transaction with the Solana / Polygon SDK of your choice."""
+        endpoint = "/api/invoice" if asset.upper() == "SOL" else "/api/invoice-spl"
+        payload: Dict[str, Any] = {
+            "amount_usd": amount_usd,
+            "agent_pubkey": self.address,
+        }
+        if asset.upper() != "SOL":
+            payload["asset"] = asset.upper()
+        r = self._session.post(
+            f"{self.base_url}{endpoint}", json=payload, timeout=self.timeout
+        )
+        r.raise_for_status()
+        data = r.json()
+        return Invoice(
+            amount_usd=amount_usd,
+            treasury_vault=data.get("treasury_vault", ""),
+            program_id=data.get("program_id", ""),
+            nonce=data.get("nonce", ""),
+            raw=data,
+        )
+
+    # ── Convenience: x402-aware HTTP request ──────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        max_retries: int = 1,
+        **kwargs,
+    ) -> requests.Response:
+        """HTTP request that auto-injects x-agent-pubkey/x-nonce/x-signature
+        headers on first try, and retries with fresh auth on 402."""
+        headers = kwargs.pop("headers", {}) or {}
+        attempt = 0
+        while True:
+            attempt += 1
+            merged = {**self.auth_headers(), **headers}
+            resp = self._session.request(
+                method, url, headers=merged, timeout=self.timeout, **kwargs
+            )
+            if resp.status_code != 402 or attempt > max_retries:
+                return resp
+            # 402 → caller hasn't reserved a Seat yet. Surface the challenge.
+            try:
+                challenge = resp.json()
+            except Exception:
+                challenge = {"raw": resp.text}
+            raise X402Error(
+                f"402 Payment Required after {attempt} attempt(s). "
+                f"Reserve a Seat first via reserve_seat_invoice(). "
+                f"Challenge: {challenge}"
+            )
+
+    # ── Aliases for ergonomics ────────────────────────────────────────────
+
+    get = lambda self, url, **kw: self.request("GET", url, **kw)
+    post = lambda self, url, **kw: self.request("POST", url, **kw)

aifinpay_agent-0.1.0a1/aifinpay/errors.py

@@ -0,0 +1,14 @@
+class AiFinPayError(Exception):
+    """Base class for all SDK errors."""
+
+
+class X402Error(AiFinPayError):
+    """Raised when the x402 challenge/response flow fails."""
+
+
+class FundingTimeoutError(AiFinPayError):
+    """Raised when polling for funding exceeds the timeout."""
+
+
+class SeatNotFoundError(AiFinPayError):
+    """Raised when the agent has no Seat PDA on-chain."""

aifinpay_agent-0.1.0a1/aifinpay_agent.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: aifinpay-agent
+Version: 0.1.0a1
+Summary: Non-custodial x402 payment client for autonomous AI agents on AiFinPay (Solana + Polygon)
+Author-email: "CoinSecurities (SECCO)" <contact@aifinpay.company>
+License: MIT
+Project-URL: Homepage, https://aifinpay.company
+Project-URL: Documentation, https://aifinpay.company/docs
+Project-URL: Repository, https://github.com/enot3615/oracle-financial-hub-59
+Project-URL: Issues, https://github.com/enot3615/oracle-financial-hub-59/issues
+Keywords: x402,ai-agent,solana,polygon,payments,non-custodial,ed25519
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyNaCl>=1.5
+Requires-Dist: base58>=2.1
+Requires-Dist: requests>=2.28
+
+# aifinpay-agent (Python)
+
+Non-custodial x402 payment client for autonomous AI agents on
+[AiFinPay](https://aifinpay.company).
+
+The Ed25519 keypair is generated locally and never leaves your process. The
+SDK only sends a one-time SHA-256 + Ed25519 signature in the `x-signature`
+header to authenticate against AiFinPay-protected endpoints.
+
+## Install
+
+```bash
+pip install aifinpay-agent
+```
+
+## Quick start
+
+```python
+from aifinpay import Agent
+
+# Generate a fresh keypair locally — never transmitted
+agent = Agent.new()
+print("Fund this address:", agent.address)
+print("Save this secret:", agent.secret_b58)  # store securely!
+
+# Wait until the wallet has at least $0.01 worth on-chain
+agent.wait_for_funding(min_usd_cents=1)
+
+# Request an invoice for a Seat (USDC on Solana)
+invoice = agent.reserve_seat_invoice(amount_usd=1.00, asset="USDC")
+print("Invoice:", invoice.raw)
+# Build + sign + submit the Solana transaction with @solana/web3.js, anchorpy,
+# or solana-py — the invoice contains program_id, treasury_vault, mints, etc.
+
+# Once the Seat is on-chain, any AiFinPay-gated endpoint just works:
+resp = agent.get("https://aifinpay.company/api/stats")
+print(resp.json())
+```
+
+## Loading an existing keypair
+
+```python
+# from solana-keygen JSON file
+agent = Agent.from_keypair_file("~/agent-wallet.json")
+
+# from base58 secret string
+agent = Agent.from_secret_b58("3RvZm7Gw...")
+```
+
+## How x402 auth works under the hood
+
+For every gated request the SDK:
+
+1. `GET /nonce` → receives a one-time UUID with 60s TTL
+2. computes `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`
+3. signs with Ed25519, base58-encodes the signature
+4. retries the original request with headers:
+   - `x-agent-pubkey: <base58 pubkey>`
+   - `x-nonce: <uuid>`
+   - `x-signature: <base58 sig>`
+
+The server verifies the signature, checks the agent has a live Seat PDA
+on-chain, and serves the resource.
+
+## Privacy
+
+- **The server never sees your private key.** Period.
+- Nonces are consumed on use; replay-resistant.
+- All transactions are public and on-chain — Solana + Polygon mainnet.
+
+## License
+
+MIT.

aifinpay_agent-0.1.0a1/aifinpay_agent.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+aifinpay/__init__.py
+aifinpay/client.py
+aifinpay/errors.py
+aifinpay_agent.egg-info/PKG-INFO
+aifinpay_agent.egg-info/SOURCES.txt
+aifinpay_agent.egg-info/dependency_links.txt
+aifinpay_agent.egg-info/requires.txt
+aifinpay_agent.egg-info/top_level.txt

aifinpay_agent-0.1.0a1/aifinpay_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aifinpay_agent-0.1.0a1/aifinpay_agent.egg-info/requires.txt

@@ -0,0 +1,3 @@
+PyNaCl>=1.5
+base58>=2.1
+requests>=2.28

aifinpay_agent-0.1.0a1/aifinpay_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+aifinpay

aifinpay_agent-0.1.0a1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aifinpay-agent"
+version = "0.1.0a1"
+description = "Non-custodial x402 payment client for autonomous AI agents on AiFinPay (Solana + Polygon)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "CoinSecurities (SECCO)", email = "contact@aifinpay.company" },
+]
+keywords = ["x402", "ai-agent", "solana", "polygon", "payments", "non-custodial", "ed25519"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "PyNaCl>=1.5",
+  "base58>=2.1",
+  "requests>=2.28",
+]
+
+[project.urls]
+Homepage = "https://aifinpay.company"
+Documentation = "https://aifinpay.company/docs"
+Repository = "https://github.com/enot3615/oracle-financial-hub-59"
+Issues = "https://github.com/enot3615/oracle-financial-hub-59/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["aifinpay*"]

aifinpay_agent-0.1.0a1/setup.cfg

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