agents-u-cash 0.1.0__tar.gz

agents_u_cash-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: agents-u-cash
+Version: 0.1.0
+Summary: Zero-dependency Python client for the agents.u.cash 402 Online Protocol API — non-custodial agent payments (buy + sell).
+Author: U.CASH Pay
+License: MIT
+Project-URL: Homepage, https://agents.u.cash
+Project-URL: Repository, https://github.com/ageesen/pay-u-cash
+Keywords: agents.u.cash,x402,402,payments,crypto,non-custodial,ai-agents
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# agents-u-cash (Python)
+
+Zero-dependency Python client for the [agents.u.cash](https://agents.u.cash) API — the 402 Online Protocol for non-custodial agent payments. Works for **both sides** of the network: an agent selling (manage resources, watch settlements) and a buyer (fetch a 402 door, push-verify a payment).
+
+Uses only the standard library (`urllib`). No dependencies. Python 3.7+.
+
+## Install
+
+```bash
+pip install agents-u-cash
+```
+
+Or copy `agents_u_cash.py` — it has no dependencies.
+
+## Sell (as an agent)
+
+```python
+from agents_u_cash import AgentsUCash
+
+# Get an API key once (wallet-first; then top up >= $1 to activate):
+# key = AgentsUCash().signup(email="me@agent.dev", password="longpass")["api_key"]
+
+agent = AgentsUCash(api_key="...")
+agent.set_wallet("btc", "bc1q…")
+agent.set_webhook("https://my.bot/webhook")
+
+res = agent.create_resource(amount=0.05)               # priced resource
+acc = agent.create_challenge(res["res_id"])             # what a buyer pays
+# Share the payable link: https://agents.u.cash/r/{res_id}
+
+settled = agent.get_settlements()                       # your earnings log
+```
+
+## Buy (as a buyer)
+
+```python
+from agents_u_cash import AgentsUCash
+
+buyer = AgentsUCash()                                   # no key needed to buy
+door = buyer.view_door(res_id)                          # the 402 door (JSON)
+# 1. pick an entry, pay entry["payTo"] exactly entry["amount"] from your wallet (out of band)
+# 2. push-verify with the on-chain tx hash:
+result = buyer.verify(door["accepts"][0]["challengeId"], tx_hash)
+# -> {"settled": True} | {"status": "pending", "confirmations": n, "required": m}
+```
+
+A human-friendly payable page is also available: `buyer.view_door(res_id, html=True)` returns the HTML.
+
+## API
+
+| Method | Auth | Description |
+|---|---|---|
+| `signup(email, password, primary_wallet=None)` | — | Register; returns `api_key` |
+| `top_up(amount)` | key | Create a ≥$1 top-up checkout (activates the account) |
+| `get_agent()` | key | Account snapshot (balance, wallets, webhook, earnings summary) |
+| `set_webhook(url)` | key | Set the settlement webhook |
+| `set_wallet(asset, address)` | key | Set your receive address for an asset |
+| `set_stripe(secret_key, product_id, webhook_secret, publishable_key=None)` | key | Connect your Stripe account (card rail); verifies the key + product |
+| `get_stripe()` | key | Masked Stripe config + the webhook endpoint to register |
+| `clear_stripe()` | key | Disconnect your Stripe account |
+| `create_resource(amount, currency=None, accepted_assets=None, webhook_url=None)` | key | Create a priced resource |
+| `get_resources(res_id=None)` | key | List resources, or fetch one |
+| `create_challenge(res_id)` | key | Build the multi-coin `accepts[]` |
+| `verify(challenge_id, hash)` | key optional | Verify + settle (buyer-push: no key needed) |
+| `get_settlements()` | key | Earnings log |
+| `view_door(res_id, html=False)` | — | The public 402 door (JSON, or HTML) |
+
+All calls return the parsed `response` dict and raise `AgentsUCashError` on API errors (which carries `.code` and `.status`).
+
+## Error handling
+
+```python
+from agents_u_cash import AgentsUCash, AgentsUCashError
+
+try:
+    agent.create_resource(amount=0.05)
+except AgentsUCashError as e:
+    print(e.code, e.status, e)   # e.g. 'uxc_agent_not_activated' 402 ...
+```
+
+Non-custodial: the platform never holds funds — every `payTo` is the seller's own wallet, and this client never sees your wallet keys.

agents_u_cash-0.1.0/README.md

@@ -0,0 +1,81 @@
+# agents-u-cash (Python)
+
+Zero-dependency Python client for the [agents.u.cash](https://agents.u.cash) API — the 402 Online Protocol for non-custodial agent payments. Works for **both sides** of the network: an agent selling (manage resources, watch settlements) and a buyer (fetch a 402 door, push-verify a payment).
+
+Uses only the standard library (`urllib`). No dependencies. Python 3.7+.
+
+## Install
+
+```bash
+pip install agents-u-cash
+```
+
+Or copy `agents_u_cash.py` — it has no dependencies.
+
+## Sell (as an agent)
+
+```python
+from agents_u_cash import AgentsUCash
+
+# Get an API key once (wallet-first; then top up >= $1 to activate):
+# key = AgentsUCash().signup(email="me@agent.dev", password="longpass")["api_key"]
+
+agent = AgentsUCash(api_key="...")
+agent.set_wallet("btc", "bc1q…")
+agent.set_webhook("https://my.bot/webhook")
+
+res = agent.create_resource(amount=0.05)               # priced resource
+acc = agent.create_challenge(res["res_id"])             # what a buyer pays
+# Share the payable link: https://agents.u.cash/r/{res_id}
+
+settled = agent.get_settlements()                       # your earnings log
+```
+
+## Buy (as a buyer)
+
+```python
+from agents_u_cash import AgentsUCash
+
+buyer = AgentsUCash()                                   # no key needed to buy
+door = buyer.view_door(res_id)                          # the 402 door (JSON)
+# 1. pick an entry, pay entry["payTo"] exactly entry["amount"] from your wallet (out of band)
+# 2. push-verify with the on-chain tx hash:
+result = buyer.verify(door["accepts"][0]["challengeId"], tx_hash)
+# -> {"settled": True} | {"status": "pending", "confirmations": n, "required": m}
+```
+
+A human-friendly payable page is also available: `buyer.view_door(res_id, html=True)` returns the HTML.
+
+## API
+
+| Method | Auth | Description |
+|---|---|---|
+| `signup(email, password, primary_wallet=None)` | — | Register; returns `api_key` |
+| `top_up(amount)` | key | Create a ≥$1 top-up checkout (activates the account) |
+| `get_agent()` | key | Account snapshot (balance, wallets, webhook, earnings summary) |
+| `set_webhook(url)` | key | Set the settlement webhook |
+| `set_wallet(asset, address)` | key | Set your receive address for an asset |
+| `set_stripe(secret_key, product_id, webhook_secret, publishable_key=None)` | key | Connect your Stripe account (card rail); verifies the key + product |
+| `get_stripe()` | key | Masked Stripe config + the webhook endpoint to register |
+| `clear_stripe()` | key | Disconnect your Stripe account |
+| `create_resource(amount, currency=None, accepted_assets=None, webhook_url=None)` | key | Create a priced resource |
+| `get_resources(res_id=None)` | key | List resources, or fetch one |
+| `create_challenge(res_id)` | key | Build the multi-coin `accepts[]` |
+| `verify(challenge_id, hash)` | key optional | Verify + settle (buyer-push: no key needed) |
+| `get_settlements()` | key | Earnings log |
+| `view_door(res_id, html=False)` | — | The public 402 door (JSON, or HTML) |
+
+All calls return the parsed `response` dict and raise `AgentsUCashError` on API errors (which carries `.code` and `.status`).
+
+## Error handling
+
+```python
+from agents_u_cash import AgentsUCash, AgentsUCashError
+
+try:
+    agent.create_resource(amount=0.05)
+except AgentsUCashError as e:
+    print(e.code, e.status, e)   # e.g. 'uxc_agent_not_activated' 402 ...
+```
+
+Non-custodial: the platform never holds funds — every `payTo` is the seller's own wallet, and this client never sees your wallet keys.

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

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: agents-u-cash
+Version: 0.1.0
+Summary: Zero-dependency Python client for the agents.u.cash 402 Online Protocol API — non-custodial agent payments (buy + sell).
+Author: U.CASH Pay
+License: MIT
+Project-URL: Homepage, https://agents.u.cash
+Project-URL: Repository, https://github.com/ageesen/pay-u-cash
+Keywords: agents.u.cash,x402,402,payments,crypto,non-custodial,ai-agents
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# agents-u-cash (Python)
+
+Zero-dependency Python client for the [agents.u.cash](https://agents.u.cash) API — the 402 Online Protocol for non-custodial agent payments. Works for **both sides** of the network: an agent selling (manage resources, watch settlements) and a buyer (fetch a 402 door, push-verify a payment).
+
+Uses only the standard library (`urllib`). No dependencies. Python 3.7+.
+
+## Install
+
+```bash
+pip install agents-u-cash
+```
+
+Or copy `agents_u_cash.py` — it has no dependencies.
+
+## Sell (as an agent)
+
+```python
+from agents_u_cash import AgentsUCash
+
+# Get an API key once (wallet-first; then top up >= $1 to activate):
+# key = AgentsUCash().signup(email="me@agent.dev", password="longpass")["api_key"]
+
+agent = AgentsUCash(api_key="...")
+agent.set_wallet("btc", "bc1q…")
+agent.set_webhook("https://my.bot/webhook")
+
+res = agent.create_resource(amount=0.05)               # priced resource
+acc = agent.create_challenge(res["res_id"])             # what a buyer pays
+# Share the payable link: https://agents.u.cash/r/{res_id}
+
+settled = agent.get_settlements()                       # your earnings log
+```
+
+## Buy (as a buyer)
+
+```python
+from agents_u_cash import AgentsUCash
+
+buyer = AgentsUCash()                                   # no key needed to buy
+door = buyer.view_door(res_id)                          # the 402 door (JSON)
+# 1. pick an entry, pay entry["payTo"] exactly entry["amount"] from your wallet (out of band)
+# 2. push-verify with the on-chain tx hash:
+result = buyer.verify(door["accepts"][0]["challengeId"], tx_hash)
+# -> {"settled": True} | {"status": "pending", "confirmations": n, "required": m}
+```
+
+A human-friendly payable page is also available: `buyer.view_door(res_id, html=True)` returns the HTML.
+
+## API
+
+| Method | Auth | Description |
+|---|---|---|
+| `signup(email, password, primary_wallet=None)` | — | Register; returns `api_key` |
+| `top_up(amount)` | key | Create a ≥$1 top-up checkout (activates the account) |
+| `get_agent()` | key | Account snapshot (balance, wallets, webhook, earnings summary) |
+| `set_webhook(url)` | key | Set the settlement webhook |
+| `set_wallet(asset, address)` | key | Set your receive address for an asset |
+| `set_stripe(secret_key, product_id, webhook_secret, publishable_key=None)` | key | Connect your Stripe account (card rail); verifies the key + product |
+| `get_stripe()` | key | Masked Stripe config + the webhook endpoint to register |
+| `clear_stripe()` | key | Disconnect your Stripe account |
+| `create_resource(amount, currency=None, accepted_assets=None, webhook_url=None)` | key | Create a priced resource |
+| `get_resources(res_id=None)` | key | List resources, or fetch one |
+| `create_challenge(res_id)` | key | Build the multi-coin `accepts[]` |
+| `verify(challenge_id, hash)` | key optional | Verify + settle (buyer-push: no key needed) |
+| `get_settlements()` | key | Earnings log |
+| `view_door(res_id, html=False)` | — | The public 402 door (JSON, or HTML) |
+
+All calls return the parsed `response` dict and raise `AgentsUCashError` on API errors (which carries `.code` and `.status`).
+
+## Error handling
+
+```python
+from agents_u_cash import AgentsUCash, AgentsUCashError
+
+try:
+    agent.create_resource(amount=0.05)
+except AgentsUCashError as e:
+    print(e.code, e.status, e)   # e.g. 'uxc_agent_not_activated' 402 ...
+```
+
+Non-custodial: the platform never holds funds — every `payTo` is the seller's own wallet, and this client never sees your wallet keys.

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

@@ -0,0 +1,7 @@
+README.md
+agents_u_cash.py
+pyproject.toml
+agents_u_cash.egg-info/PKG-INFO
+agents_u_cash.egg-info/SOURCES.txt
+agents_u_cash.egg-info/dependency_links.txt
+agents_u_cash.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+agents_u_cash

agents_u_cash-0.1.0/agents_u_cash.py

@@ -0,0 +1,155 @@
+"""agents.u.cash Python client — the 402 Online Protocol API (non-custodial agent payments).
+
+Zero dependencies (stdlib ``urllib`` only; Python 3.7+). Works for both sides of the network: an
+agent SELLING (manage resources, watch settlements) and a BUYER (fetch a 402 door, push-verify a
+payment). See https://agents.u.cash.
+"""
+
+import json
+import urllib.request
+import urllib.error
+from urllib.parse import urlencode, quote
+
+DEFAULT_BASE_URL = "https://agents.u.cash"
+USER_AGENT = "agents-u-cash-python/0.1 (+https://agents.u.cash)"
+
+
+class AgentsUCashError(Exception):
+    """Raised on any non-success API response. Carries ``code`` and ``status``."""
+
+    def __init__(self, message, code=None, status=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class AgentsUCash:
+    """Client for the agents.u.cash API.
+
+    Most calls require an agent API key (from :meth:`signup`). The buyer-side calls
+    (:meth:`view_door` and the buyer form of :meth:`verify`) are public; a client constructed
+    without an api_key can call them.
+
+    Args:
+        api_key: Agent API key (required for seller/authenticated calls).
+        base_url: Override the API base URL.
+    """
+
+    def __init__(self, api_key="", base_url=DEFAULT_BASE_URL):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, method, path, body=None, query=None, auth=True):
+        url = self.base_url + path
+        if query:
+            url += "?" + urlencode(query)
+        headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        data = None
+        if auth and self.api_key:
+            headers["X-Api-Key"] = self.api_key
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                text = resp.read().decode("utf-8")
+                status = resp.status
+        except urllib.error.HTTPError as e:
+            text = e.read().decode("utf-8")
+            status = e.code
+        try:
+            payload = json.loads(text) if text else {}
+        except ValueError:
+            payload = {"success": False, "message": text}
+        if not payload or payload.get("success") is not True:
+            raise AgentsUCashError(
+                payload.get("message", "HTTP %s" % status),
+                code=payload.get("error_code", "http_error"),
+                status=status,
+            )
+        return payload["response"]
+
+    # ----- account -----
+    def signup(self, email, password, primary_wallet=None):
+        """Register an agent account. Wallet-first: returns the api_key immediately."""
+        body = {"email": email, "password": password}
+        if primary_wallet is not None:
+            body["primary_wallet"] = primary_wallet
+        return self._request("POST", "/v1/signup", body=body, auth=False)
+
+    def top_up(self, amount):
+        """Create a credit top-up checkout ($1 min; activates the account on confirmation)."""
+        return self._request("POST", "/v1/top-up", body={"amount": amount})
+
+    def get_agent(self):
+        """Account snapshot: activation, balance, wallets, webhook URL, earnings summary."""
+        return self._request("GET", "/v1/agent")
+
+    def set_webhook(self, webhook_url):
+        """Set the webhook URL notified on settlement."""
+        return self._request("POST", "/v1/agent", body={"webhook_url": webhook_url})
+
+    def set_wallet(self, asset, address):
+        """Set the agent's own receive address for an asset (where buyer funds land)."""
+        return self._request("POST", "/v1/wallets", body={"asset": asset, "address": address})
+
+    def set_stripe(self, secret_key, product_id, webhook_secret, publishable_key=None):
+        """Connect the agent's own Stripe account to enable card payments (the redirect rail)."""
+        body = {"secret_key": secret_key, "product_id": product_id, "webhook_secret": webhook_secret}
+        if publishable_key is not None:
+            body["publishable_key"] = publishable_key
+        return self._request("POST", "/v1/stripe", body=body)
+
+    def get_stripe(self):
+        """The masked Stripe config + the webhook endpoint URL to register in the Stripe dashboard."""
+        return self._request("GET", "/v1/stripe")
+
+    def clear_stripe(self):
+        """Disconnect the agent's Stripe account (disables card payments)."""
+        return self._request("POST", "/v1/stripe", body={"clear": 1})
+
+    # ----- resources (seller) -----
+    def create_resource(self, amount, currency=None, accepted_assets=None, webhook_url=None):
+        """Create a priced resource. Returns {res_id, amount, currency, accepted_assets}."""
+        body = {"amount": amount}
+        if currency is not None:
+            body["currency"] = currency
+        if accepted_assets is not None:
+            body["accepted_assets"] = accepted_assets
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        return self._request("POST", "/v1/resources", body=body)
+
+    def get_resources(self, res_id=None):
+        """List the agent's resources, or fetch one by res_id."""
+        return self._request("GET", "/v1/resources", query={"res_id": res_id} if res_id else None)
+
+    # ----- 402 payment flow -----
+    def create_challenge(self, res_id):
+        """Build the multi-coin accepts[] for a resource (the payable options)."""
+        return self._request("POST", "/v1/challenge", body={"res_id": res_id})
+
+    def verify(self, challenge_id, hash):
+        """Verify + settle a payment by on-chain tx hash.
+
+        Buyer-push: with no api_key on the client, the public challengeId authorizes the call
+        (settlement is still gated by on-chain confirmation).
+        """
+        return self._request(
+            "POST", "/v1/verify", body={"challengeId": challenge_id, "hash": hash}, auth=bool(self.api_key)
+        )
+
+    def get_settlements(self):
+        """The agent's earnings log (settled/underpaid resource payments)."""
+        return self._request("GET", "/v1/settlements")
+
+    # ----- buyer / public -----
+    def view_door(self, res_id, html=False):
+        """The public 402 door: price + multi-coin accepts[]. Pass html=True for the payable page."""
+        if html:
+            url = self.base_url + "/r/" + quote(res_id)
+            req = urllib.request.Request(url, headers={"Accept": "text/html", "User-Agent": USER_AGENT})
+            with urllib.request.urlopen(req) as resp:
+                return resp.read().decode("utf-8")
+        return self._request("GET", "/r/" + quote(res_id), auth=False)

agents_u_cash-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "agents-u-cash"
+version = "0.1.0"
+description = "Zero-dependency Python client for the agents.u.cash 402 Online Protocol API — non-custodial agent payments (buy + sell)."
+readme = "README.md"
+requires-python = ">=3.7"
+license = { text = "MIT" }
+authors = [{ name = "U.CASH Pay" }]
+keywords = ["agents.u.cash", "x402", "402", "payments", "crypto", "non-custodial", "ai-agents"]
+
+[project.urls]
+Homepage = "https://agents.u.cash"
+Repository = "https://github.com/ageesen/pay-u-cash"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["agents_u_cash"]

agents_u_cash-0.1.0/setup.cfg

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