singit 0.1.0__tar.gz

singit-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+
+# Node
+node_modules/
+
+# Local virtual environments
+.venv/
+venv/
+env/
+payment-executor/.venv/
+
+# Secrets and local runtime config
+# Ledger key ring ciphertext. The encrypted master key is still the master
+# key: anyone who has it and WALLET_PASS has every managed wallet.
+*.enc
+.env
+*.env
+!*.env.example
+payment-executor/.env
+sign402-gateway/.bitrefill-api-key
+.env.wallet-*
+!.env.wallet-*.example
+
+# Demo runtime artifacts
+.demo-logs/
+.ledger-live/
+.graph-live/
+# Runtime data retained at its historical path; includes SQLite sidecar files.
+/demo-dashboard/
+
+# Generated presentation scratch workspace
+outputs/
+output/
+tmp/
+SingIt-backgrounds.zip
+SingIt-presentation-assets/
+
+# Generated x402 survey exports; keep handwritten notes and patches visible.
+/out/*.csv
+/out/x402-services-live.md
+
+# Local brainstorming sessions and preview server state
+/.superpowers/
+
+# Local tooling and duplicated/scratch workspaces
+.tools/
+tools/*
+# …except the Ledger approval signer, which is part of the product rather than
+# scratch: the local client signs a gateway operation on the owner's device.
+!tools/ledger-approve/
+x402HackBerlin/
+.worktrees/
+
+# Draft writing artifacts
+Sign402 X Longform Post.md
+
+# Local editor files
+.vscode/
+.idea/
+/.codex/
+
+# …but not its installed dependencies.
+tools/ledger-approve/node_modules/
+
+# Solana runtime state (wallets and payment journals)
+.local/

singit-0.1.0/LICENSE

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

singit-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: singit
+Version: 0.1.0
+Summary: SingIt SDK: x402 payment and client-side spending allowance for SingIt Ask.
+Project-URL: Homepage, https://singitai.app/developers/
+Project-URL: Repository, https://github.com/bubon-ik/SingItAI
+Project-URL: Source, https://github.com/bubon-ik/SingItAI/tree/main/sdk/python
+Project-URL: Issues, https://github.com/bubon-ik/SingItAI/issues
+Author-email: SingIt <contact@singitai.app>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,base,singit,solana,usdc,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: x402[evm]<3,>=2.25.0
+Provides-Extra: svm
+Requires-Dist: x402[svm]<3,>=2.25.0; extra == 'svm'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'test'
+Description-Content-Type: text/markdown
+
+# singit
+
+x402 payment and client-side spending allowance for [SingIt Ask](../../singit-ask), in a few
+lines. Limits are checked in your process before signing. The separate AgentAllowance
+contract covers only the SingIt app's own agent; it does not protect other agents.
+
+## Install
+
+```bash
+pip install singit          # Base / Base Sepolia (EVM): upto + exact
+pip install singit[svm]      # adds Solana: exact only (see "What isn't supported yet")
+```
+
+## Base
+
+```python
+import os
+from singit import SingIt
+
+singit = SingIt(
+    evm_private_key=os.environ["AGENT_PRIVATE_KEY"],  # or evm_account=an eth_account LocalAccount
+    network="base",
+    max_per_call_usd=0.01,
+    max_per_day_usd=1,
+)
+
+answer = singit.chat(messages=[{"role": "user", "content": "Hello"}])
+print(answer["choices"][0]["message"]["content"], answer["payment"])
+```
+
+## Solana (exact only)
+
+```python
+import os
+from singit import SingIt
+
+singit = SingIt(
+    solana_signer=solana_signer,  # an x402[svm] ClientSvmSigner; requires `pip install singit[svm]`
+    network="solana",
+    max_per_call_usd=0.01,
+    max_per_day_usd=1,
+)
+
+answer = singit.chat(messages=[{"role": "user", "content": "Hello"}], scheme="exact")
+```
+
+## Base Sepolia (testnet)
+
+SingIt has no testnet deployment, so there is no pinned `pay_to` to default to: pass one
+explicitly (e.g. your own test merchant, or a facilitator's own test receiver).
+
+```python
+singit = SingIt(
+    evm_private_key=os.environ["AGENT_PRIVATE_KEY"], network="base-sepolia",
+    pay_to=os.environ["TEST_MERCHANT_PAY_TO"],  # required: no SingIt deployment to pin a default against
+    max_per_call_usd=0.01, max_per_day_usd=1,
+)
+```
+
+## Guards
+
+Every call pins the merchant's offer before signing anything, the same way
+`singit-ask/src/metered-buyer.mjs` and `solana-buyer.mjs` do for the service's own buyers:
+
+- **Network/asset/payTo.** The offer's `network`, `asset` and `payTo` must exactly match this
+  `SingIt` instance's configured network (the built-in pin for `base`/`solana`, or the `pay_to`
+  you pass for `base-sepolia`). A merchant offering a different asset or recipient is refused
+  before anything is signed.
+- **Per-call ceiling (`max_per_call_usd`).** The offer's atomic amount must be at or below
+  `max_per_call_usd` converted to micro-USDC. A costlier offer is refused.
+- **Per-day ceiling (`max_per_day_usd`).** An in-memory counter per client instance and per UTC day.
+  Reserved at the offer's worst-case ceiling before signing, settled down to the actual billed
+  amount for `upto` only. `exact` always counts the full offer amount. **Not durable**: it resets on restart and is not shared across processes —
+  it is a client-side allowance guard, not a ledger. For the SingIt app agent’s separate on-chain limit, see
+  `allowance()` below.
+- **Settlement receipt.** The `payment-response` header's network and payer are checked against
+  the request; a mismatch is treated as unresolved rather than returned as a success.
+
+This SDK does **not** wait for on-chain confirmation of the settlement transaction;
+`payment["txHash"]` is returned as reported by the merchant's `payment-response` header for the
+caller to check independently if needed.
+
+## API
+
+- `SingIt(...)` — `evm_private_key | evm_account` (EVM; `evm_account` is any `eth_account`
+  `LocalAccount`), `solana_signer` (an `x402[svm]` signer, for `network="solana"`), `network`,
+  `base_url` (default `https://ask.singitai.app`), `app_base_url` (default
+  `https://app.singitai.app`), `pay_to`, `rpc_url`, `max_per_call_usd`, `max_per_day_usd` (both
+  required).
+- `chat(model=None, messages=..., max_tokens=None, scheme="upto", route="completions")` —
+  OpenAI-shaped chat completion. `scheme="upto"` (default) pays only the actual answer cost, up
+  to the offered ceiling, on EVM networks; `"exact"` pays that ceiling flat and is the only
+  scheme supported on Solana (see below). `route="completions"` (default) calls
+  `POST /v1/chat/completions`, live today. `route="per-model"` calls `POST /v1/chat/{model}`
+  (SI-62), live; `model` is then required.
+- `wallet_report(address, days=None, api_key=None)` — `GET {app_base_url}/v1/wallet/{address}/reconciliation`
+  (SI-67). The report is private: `api_key` must be a SingIt API key of the account that signs in
+  with `address`; without one the server answers 401, and the SDK says so.
+- `pricing()` — `GET {base_url}/pricing.json` (SI-68), live.
+- `allowance(address, **kwargs)` — `wallet_report(address, **kwargs)["allowance"]`: the on-chain
+  spending limit set in the SingIt app, with what has been spent/remains today.
+
+## What isn't supported yet
+
+- **Solana `upto` is not supported.** The official `x402` Python package (2.25.0) ships an EVM
+  `upto` client (`x402.mechanisms.evm.upto.client.UptoEvmScheme`) but has no Solana equivalent —
+  only `x402.mechanisms.svm.exact.client.ExactSvmScheme`. This corrects an earlier assumption
+  that Python might lack EVM `upto` too: it does not, Base/Base Sepolia support both schemes.
+  Solana support here is `exact` only, and calling `chat(scheme="upto", network="solana")` raises
+  clearly rather than silently falling back.
+- No on-chain confirmation of the settlement transaction.
+- The Solana `exact` client in the official package resolves a blockhash over a live RPC call
+  during payload construction, so it cannot be exercised fully offline; this SDK's own test suite
+  therefore only covers Solana at the offer-selection/guard level (see `tests/test_solana_offer.py`).
+- `base-sepolia` is useful for integration-testing against a merchant you control; SingIt itself
+  has no testnet deployment to pay.
+
+Framework fetch adapters are currently available only in the TypeScript SDK.

singit-0.1.0/README.md

@@ -0,0 +1,118 @@
+# singit
+
+x402 payment and client-side spending allowance for [SingIt Ask](../../singit-ask), in a few
+lines. Limits are checked in your process before signing. The separate AgentAllowance
+contract covers only the SingIt app's own agent; it does not protect other agents.
+
+## Install
+
+```bash
+pip install singit          # Base / Base Sepolia (EVM): upto + exact
+pip install singit[svm]      # adds Solana: exact only (see "What isn't supported yet")
+```
+
+## Base
+
+```python
+import os
+from singit import SingIt
+
+singit = SingIt(
+    evm_private_key=os.environ["AGENT_PRIVATE_KEY"],  # or evm_account=an eth_account LocalAccount
+    network="base",
+    max_per_call_usd=0.01,
+    max_per_day_usd=1,
+)
+
+answer = singit.chat(messages=[{"role": "user", "content": "Hello"}])
+print(answer["choices"][0]["message"]["content"], answer["payment"])
+```
+
+## Solana (exact only)
+
+```python
+import os
+from singit import SingIt
+
+singit = SingIt(
+    solana_signer=solana_signer,  # an x402[svm] ClientSvmSigner; requires `pip install singit[svm]`
+    network="solana",
+    max_per_call_usd=0.01,
+    max_per_day_usd=1,
+)
+
+answer = singit.chat(messages=[{"role": "user", "content": "Hello"}], scheme="exact")
+```
+
+## Base Sepolia (testnet)
+
+SingIt has no testnet deployment, so there is no pinned `pay_to` to default to: pass one
+explicitly (e.g. your own test merchant, or a facilitator's own test receiver).
+
+```python
+singit = SingIt(
+    evm_private_key=os.environ["AGENT_PRIVATE_KEY"], network="base-sepolia",
+    pay_to=os.environ["TEST_MERCHANT_PAY_TO"],  # required: no SingIt deployment to pin a default against
+    max_per_call_usd=0.01, max_per_day_usd=1,
+)
+```
+
+## Guards
+
+Every call pins the merchant's offer before signing anything, the same way
+`singit-ask/src/metered-buyer.mjs` and `solana-buyer.mjs` do for the service's own buyers:
+
+- **Network/asset/payTo.** The offer's `network`, `asset` and `payTo` must exactly match this
+  `SingIt` instance's configured network (the built-in pin for `base`/`solana`, or the `pay_to`
+  you pass for `base-sepolia`). A merchant offering a different asset or recipient is refused
+  before anything is signed.
+- **Per-call ceiling (`max_per_call_usd`).** The offer's atomic amount must be at or below
+  `max_per_call_usd` converted to micro-USDC. A costlier offer is refused.
+- **Per-day ceiling (`max_per_day_usd`).** An in-memory counter per client instance and per UTC day.
+  Reserved at the offer's worst-case ceiling before signing, settled down to the actual billed
+  amount for `upto` only. `exact` always counts the full offer amount. **Not durable**: it resets on restart and is not shared across processes —
+  it is a client-side allowance guard, not a ledger. For the SingIt app agent’s separate on-chain limit, see
+  `allowance()` below.
+- **Settlement receipt.** The `payment-response` header's network and payer are checked against
+  the request; a mismatch is treated as unresolved rather than returned as a success.
+
+This SDK does **not** wait for on-chain confirmation of the settlement transaction;
+`payment["txHash"]` is returned as reported by the merchant's `payment-response` header for the
+caller to check independently if needed.
+
+## API
+
+- `SingIt(...)` — `evm_private_key | evm_account` (EVM; `evm_account` is any `eth_account`
+  `LocalAccount`), `solana_signer` (an `x402[svm]` signer, for `network="solana"`), `network`,
+  `base_url` (default `https://ask.singitai.app`), `app_base_url` (default
+  `https://app.singitai.app`), `pay_to`, `rpc_url`, `max_per_call_usd`, `max_per_day_usd` (both
+  required).
+- `chat(model=None, messages=..., max_tokens=None, scheme="upto", route="completions")` —
+  OpenAI-shaped chat completion. `scheme="upto"` (default) pays only the actual answer cost, up
+  to the offered ceiling, on EVM networks; `"exact"` pays that ceiling flat and is the only
+  scheme supported on Solana (see below). `route="completions"` (default) calls
+  `POST /v1/chat/completions`, live today. `route="per-model"` calls `POST /v1/chat/{model}`
+  (SI-62), live; `model` is then required.
+- `wallet_report(address, days=None, api_key=None)` — `GET {app_base_url}/v1/wallet/{address}/reconciliation`
+  (SI-67). The report is private: `api_key` must be a SingIt API key of the account that signs in
+  with `address`; without one the server answers 401, and the SDK says so.
+- `pricing()` — `GET {base_url}/pricing.json` (SI-68), live.
+- `allowance(address, **kwargs)` — `wallet_report(address, **kwargs)["allowance"]`: the on-chain
+  spending limit set in the SingIt app, with what has been spent/remains today.
+
+## What isn't supported yet
+
+- **Solana `upto` is not supported.** The official `x402` Python package (2.25.0) ships an EVM
+  `upto` client (`x402.mechanisms.evm.upto.client.UptoEvmScheme`) but has no Solana equivalent —
+  only `x402.mechanisms.svm.exact.client.ExactSvmScheme`. This corrects an earlier assumption
+  that Python might lack EVM `upto` too: it does not, Base/Base Sepolia support both schemes.
+  Solana support here is `exact` only, and calling `chat(scheme="upto", network="solana")` raises
+  clearly rather than silently falling back.
+- No on-chain confirmation of the settlement transaction.
+- The Solana `exact` client in the official package resolves a blockhash over a live RPC call
+  during payload construction, so it cannot be exercised fully offline; this SDK's own test suite
+  therefore only covers Solana at the offer-selection/guard level (see `tests/test_solana_offer.py`).
+- `base-sepolia` is useful for integration-testing against a merchant you control; SingIt itself
+  has no testnet deployment to pay.
+
+Framework fetch adapters are currently available only in the TypeScript SDK.

singit-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "singit"
+version = "0.1.0"
+description = "SingIt SDK: x402 payment and client-side spending allowance for SingIt Ask."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "SingIt", email = "contact@singitai.app"}]
+keywords = ["singit", "x402", "usdc", "base", "solana", "ai-agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "x402[evm]>=2.25.0,<3",
+]
+
+[project.optional-dependencies]
+# Solana exact-scheme payments. The official x402 package has no Solana upto client yet (see README).
+svm = [
+  "x402[svm]>=2.25.0,<3",
+]
+test = [
+  "pytest>=8",
+  "tomli>=2; python_version < '3.11'",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/singit"]
+
+[project.urls]
+Homepage = "https://singitai.app/developers/"
+Repository = "https://github.com/bubon-ik/SingItAI"
+Source = "https://github.com/bubon-ik/SingItAI/tree/main/sdk/python"
+Issues = "https://github.com/bubon-ik/SingItAI/issues"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/singit", "README.md", "LICENSE", "pyproject.toml"]

singit-0.1.0/src/singit/__init__.py

@@ -0,0 +1,5 @@
+from .client import SingIt
+from .guards import DailyLimiter, SingItPaymentError, select_offer
+from .pins import NETWORKS
+
+__all__ = ["SingIt", "SingItPaymentError", "DailyLimiter", "select_offer", "NETWORKS"]

singit-0.1.0/src/singit/client.py

@@ -0,0 +1,256 @@
+"""SingIt: x402 payment and client-side spending allowance for SingIt Ask, in a few lines::
+
+    singit = SingIt(evm_private_key=..., network="base", max_per_call_usd=0.01, max_per_day_usd=1)
+    answer = singit.chat(messages=[{"role": "user", "content": "Hello"}])
+
+Every payment is checked against a pinned network/asset/payTo and a per-call and per-day USDC
+ceiling before anything is signed; see guards.py. Nothing here ever raises a configured ceiling.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .guards import DailyLimiter, SingItPaymentError, decode_header, encode_header, is_atomic_amount, select_offer, usd_to_atomic
+from .pins import DEFAULT_APP_BASE_URL, DEFAULT_BASE_URL, NETWORKS, ROUTE, per_model_route
+
+
+def _post_json(url: str, body: bytes, headers: dict, timeout: float = 90.0):
+    request = urllib.request.Request(url, data=body, headers={"Content-Type": "application/json", **headers}, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 (merchant URL is caller-configured)
+            return response.status, response.headers, response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, error.headers, error.read()
+
+
+def _get_json(url: str, timeout: float = 30.0, headers: dict | None = None):
+    request = urllib.request.Request(url, method="GET", headers=headers or {})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310
+            return response.status, response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, error.read()
+
+
+def _required_model(model: str | None) -> str:
+    if not model:
+        raise SingItPaymentError('model is required when route is "per-model".')
+    return model
+
+
+def _payer_from_payload(payload: dict) -> str | None:
+    inner = payload.get("payload") or {}
+    auth = inner.get("permit2Authorization") or inner.get("authorization")
+    if auth:
+        return auth.get("from")
+    return inner.get("from")
+
+
+def _same_payer(family: str, a: object, b: object) -> bool:
+    if not isinstance(a, str) or not isinstance(b, str):
+        return False
+    return a.lower() == b.lower() if family == "evm" else a == b
+
+
+class SingIt:
+    def __init__(
+        self,
+        *,
+        evm_private_key: str | None = None,
+        evm_account: object | None = None,
+        solana_signer: object | None = None,
+        network: str,
+        base_url: str = DEFAULT_BASE_URL,
+        app_base_url: str = DEFAULT_APP_BASE_URL,
+        pay_to: str | None = None,
+        rpc_url: str | None = None,
+        max_per_call_usd: float | None = None,
+        max_per_day_usd: float | None = None,
+    ):
+        pin = NETWORKS.get(network)
+        if pin is None:
+            raise SingItPaymentError(f'Unknown network "{network}". Use "base", "base-sepolia" or "solana".')
+        if pin.pay_to is None and not pay_to:
+            raise SingItPaymentError(f"SingIt has no deployment on {network}; pass pay_to explicitly (see README).")
+        if max_per_call_usd is None or max_per_day_usd is None:
+            raise SingItPaymentError("max_per_call_usd and max_per_day_usd are required: this SDK never pays without a ceiling.")
+        self.network = network
+        self.pin = pin
+        self.base_url = base_url.rstrip("/")
+        self.app_base_url = app_base_url.rstrip("/")
+        self.pay_to = pay_to or pin.pay_to
+        self.rpc_url = rpc_url or pin.default_rpc_url
+        self.max_per_call_atomic = usd_to_atomic(max_per_call_usd)
+        self.limiter = DailyLimiter(usd_to_atomic(max_per_day_usd))
+        self._evm_account = None
+        if pin.family == "evm":
+            if evm_account is not None:
+                self._evm_account = evm_account
+            elif evm_private_key is not None:
+                from eth_account import Account
+
+                self._evm_account = Account.from_key(evm_private_key)
+            else:
+                raise SingItPaymentError("Pass evm_private_key or evm_account to pay on an EVM network.")
+        self._solana_signer = solana_signer
+
+    def _sign(self, scheme: str, offer: dict, extensions: dict | None) -> dict:
+        from x402.schemas import PaymentRequirements
+
+        requirements = PaymentRequirements.model_validate(offer)
+        if self.pin.family == "evm":
+            if scheme == "upto":
+                from x402.mechanisms.evm.upto.client import UptoEvmScheme as Scheme
+            else:
+                from x402.mechanisms.evm.exact.client import ExactEvmScheme as Scheme
+            inner = Scheme(self._evm_account).create_payment_payload(requirements, extensions=extensions)
+            payload_extensions = inner.pop("__extensions", None)
+            payload = {"x402Version": 2, "accepted": offer, "payload": inner}
+            if payload_extensions:
+                payload["extensions"] = payload_extensions
+            return payload
+        # Solana: the official x402 Python package has no `upto` SVM client yet (see README).
+        if scheme != "exact":
+            raise SingItPaymentError("The official x402 Python package has no Solana `upto` client yet; use scheme='exact'.")
+        if not self._solana_signer:
+            raise SingItPaymentError("Pass solana_signer (and install singit[svm]) to pay on Solana.")
+        from x402.mechanisms.svm.exact.client import ExactSvmScheme
+
+        inner = ExactSvmScheme(self._solana_signer, rpc_url=self.rpc_url).create_payment_payload(requirements)
+        return {"x402Version": 2, "accepted": offer, "payload": inner}
+
+    def chat(
+        self,
+        *,
+        model: str | None = None,
+        messages: list[dict],
+        max_tokens: int | None = None,
+        scheme: str = "upto",
+        route: str = "completions",
+    ) -> dict:
+        """One OpenAI-shaped chat completion, paid over x402.
+
+        `route="per-model"` calls POST /v1/chat/{model} (SI-62), which is live;
+        the default calls POST /v1/chat/completions, which is live today.
+        """
+        if not messages:
+            raise SingItPaymentError("messages must be a non-empty list.")
+        if scheme not in ("upto", "exact"):
+            raise SingItPaymentError('scheme must be "upto" or "exact".')
+        if route not in ("completions", "per-model"):
+            raise SingItPaymentError('route must be "completions" or "per-model".')
+        path = per_model_route(_required_model(model)) if route == "per-model" else ROUTE
+        url = f"{self.base_url}{path}"
+        body = {"messages": messages, "stream": False}
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if model and route == "completions":
+            body["model"] = model
+        encoded = json.dumps(body).encode("utf-8")
+
+        status, headers, raw = _post_json(url, encoded, {})
+        if status != 402:
+            if status >= 400:
+                raise SingItPaymentError(f"Request failed with HTTP {status}: {raw[:300]!r}")
+            return {**json.loads(raw), "payment": None}
+
+        header = headers.get("payment-required")
+        if not header:
+            raise SingItPaymentError("Got HTTP 402 with no PAYMENT-REQUIRED header.")
+        challenge = decode_header(header)
+        offer = select_offer(
+            challenge,
+            scheme=scheme,
+            network_id=self.pin.caip,
+            family=self.pin.family,
+            asset=self.pin.asset,
+            pay_to=self.pay_to,
+            max_cap_atomic=self.max_per_call_atomic,
+            resource_url=url,
+        )
+
+        release = self.limiter.reserve(offer["amount"])
+        try:
+            payload = self._sign(scheme, offer, challenge.get("extensions"))
+        except Exception:
+            release()
+            raise
+
+        # Once a signed payment has left, only a 402 (payment refused) proves nothing settled. A dropped connection,
+        # another status or an unreadable invoice may still have settled, so the worst-case reservation stays
+        # counted against today's cap (Codex review).
+        try:
+            status, headers, raw = _post_json(url, encoded, {"PAYMENT-SIGNATURE": encode_header(payload)})
+        except Exception as error:
+            raise SingItPaymentError(
+                f"The paid request failed after the payment was sent ({error}); it was not repeated and its "
+                "ceiling stays counted against the daily cap.") from error
+        if status == 402:
+            release()
+            raise SingItPaymentError("The merchant refused the payment (HTTP 402); nothing was paid and it was not repeated.")
+        if status != 200:
+            raise SingItPaymentError(
+                f"Paid request returned HTTP {status}; it was not repeated, and its ceiling stays counted against "
+                "the daily cap in case it settled.")
+        try:
+            result = json.loads(raw)
+        except ValueError:
+            result = {}
+        total_atomic = ((result or {}).get("billing") or {}).get("totalAtomic")
+        if (not is_atomic_amount(total_atomic) or int(total_atomic) > int(offer["amount"])
+                or (scheme == "exact" and int(total_atomic) != int(offer["amount"]))):
+            raise SingItPaymentError("The invoice does not match the offered ceiling; treating the payment as unresolved "
+                                     "(its ceiling stays counted against the daily cap).")
+
+        receipt_header = headers.get("payment-response")
+        receipt = decode_header(receipt_header) if receipt_header else None
+        payer = _payer_from_payload(payload)
+        if receipt and (
+            receipt.get("network") != self.pin.caip
+            or (payer and receipt.get("payer") and not _same_payer(self.pin.family, receipt["payer"], payer))
+        ):
+            raise SingItPaymentError("The settlement receipt does not match this request; treating the payment as unresolved.")
+
+        if scheme == "upto":
+            self.limiter.settle(release, total_atomic, offer["amount"])
+
+        payment_info = {"scheme": scheme, "network": self.network, "amountAtomic": total_atomic}
+        if receipt and receipt.get("transaction"):
+            payment_info["txHash"] = receipt["transaction"]
+        return {**result, "payment": payment_info}
+
+    def wallet_report(self, address: str, *, days: int | None = None, api_key: str | None = None) -> dict:
+        """GET /v1/wallet/{address}/reconciliation on app_base_url (SI-67). The report is private: pass an
+        API key (sk_singit_...) of the SingIt account that signs in with `address`."""
+        qs = f"?days={days}" if days is not None else ""
+        url = f"{self.app_base_url}/v1/wallet/{urllib.parse.quote(address)}/reconciliation{qs}"
+        status, raw = _get_json(url, headers={"Authorization": f"Bearer {api_key}"} if api_key else None)
+        if status in (401, 403):
+            raise SingItPaymentError(
+                f"The wallet report is private (HTTP {status}): pass api_key, a SingIt API key of the account "
+                "that signs in with this wallet."
+            )
+        if status >= 400:
+            raise SingItPaymentError(
+                f"Wallet reconciliation is not available (HTTP {status})."
+            )
+        return json.loads(raw)
+
+    def pricing(self) -> dict:
+        """GET /pricing.json on base_url (SI-68; live)."""
+        url = f"{self.base_url}/pricing.json"
+        status, raw = _get_json(url)
+        if status >= 400:
+            raise SingItPaymentError(
+                f"pricing.json is not available (HTTP {status})."
+            )
+        return json.loads(raw)
+
+    def allowance(self, address: str, **kwargs) -> object:
+        """The on-chain spending limit set in the SingIt app for `address`, with today's spent/remaining."""
+        report = self.wallet_report(address, **kwargs)
+        return report.get("allowance") if isinstance(report, dict) else None

singit-0.1.0/src/singit/guards.py

@@ -0,0 +1,144 @@
+"""Client-side allowance guards: pin the merchant's offer (network, asset, payTo) before signing,
+cap a single call, and cap a rolling day of calls. Modeled on singit-ask's own buyers
+(src/metered-buyer.mjs, src/solana-buyer.mjs): same idea, generalized to any x402 merchant.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from datetime import datetime, timezone
+
+_ATOMIC_RE = re.compile(r"^[1-9][0-9]{0,27}$")
+
+
+class SingItPaymentError(Exception):
+    pass
+
+
+def is_atomic_amount(value: object) -> bool:
+    return isinstance(value, str) and bool(_ATOMIC_RE.match(value))
+
+
+def _same_evm_address(a: object, b: object) -> bool:
+    return isinstance(a, str) and isinstance(b, str) and a.lower() == b.lower()
+
+
+def _same_svm_address(a: object, b: object) -> bool:
+    return isinstance(a, str) and isinstance(b, str) and a == b
+
+
+def decode_header(value: str) -> dict:
+    try:
+        return json.loads(base64.b64decode(value).decode("utf-8"))
+    except Exception as error:
+        raise SingItPaymentError("The payment header could not be decoded.") from error
+
+
+def encode_header(value: dict) -> str:
+    return base64.b64encode(json.dumps(value).encode("utf-8")).decode("ascii")
+
+
+def select_offer(
+    challenge: dict,
+    *,
+    scheme: str,
+    network_id: str,
+    family: str,
+    asset: str,
+    pay_to: str,
+    max_cap_atomic: str,
+    resource_url: str | None = None,
+) -> dict:
+    """Picks the single offer matching scheme+network, then refuses to sign unless its asset
+    and payTo are exactly the ones this SingIt instance was configured to pay, and its amount is
+    within the per-call ceiling. Nothing here ever raises the ceiling: a merchant asking for more
+    than `max_cap_atomic` is refused, never renegotiated.
+    """
+    if not challenge or challenge.get("x402Version") != 2:
+        raise SingItPaymentError("Unexpected x402 version in the payment challenge.")
+    if resource_url and (challenge.get("resource") or {}).get("url") != resource_url:
+        raise SingItPaymentError("The challenge names a different resource than the one called.")
+    offers = [a for a in (challenge.get("accepts") or []) if a.get("scheme") == scheme and a.get("network") == network_id]
+    if len(offers) != 1:
+        raise SingItPaymentError(f"Expected exactly one {scheme} offer on {network_id}; got {len(offers)}.")
+    offer = offers[0]
+    same_address = _same_evm_address if family == "evm" else _same_svm_address
+    if not same_address(offer.get("asset"), asset):
+        raise SingItPaymentError(f"Unexpected payment asset ({offer.get('asset')}); refusing to sign.")
+    if not same_address(offer.get("payTo"), pay_to):
+        raise SingItPaymentError(f"Unexpected payee ({offer.get('payTo')}); refusing to sign.")
+    amount = offer.get("amount")
+    if not is_atomic_amount(amount) or not is_atomic_amount(max_cap_atomic) or int(amount) > int(max_cap_atomic):
+        raise SingItPaymentError(f"Offer amount {amount} exceeds the configured per-call ceiling ({max_cap_atomic}).")
+    timeout = offer.get("maxTimeoutSeconds")
+    if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout < 1 or timeout > 600:
+        raise SingItPaymentError("Unexpected payment timeout window in the offer.")
+    if family == "evm" and offer.get("scheme") == "upto":
+        facilitator = (offer.get("extra") or {}).get("facilitatorAddress", "")
+        if not re.match(r"^0x[0-9a-fA-F]{40}$", facilitator or "") or re.match(r"^0x0{40}$", facilitator, re.IGNORECASE):
+            raise SingItPaymentError("The offer has no usable facilitator address for the upto scheme.")
+    return offer
+
+
+class DailyLimiter:
+    """A simple, in-memory, per-UTC-day spend counter. Not durable (lost on restart) and not
+    shared across processes: a client-side allowance guard, not a ledger. Checked against the
+    offer's worst-case amount before signing, then adjusted down to the amount actually billed
+    afterwards, so an `upto` request that settles for less than its ceiling frees the unused
+    headroom immediately.
+    """
+
+    def __init__(self, cap_atomic: str):
+        self.cap_atomic = int(cap_atomic)
+        self._day: str | None = None
+        self._spent_atomic = 0
+
+    def _roll_if_needed(self) -> None:
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        if today != self._day:
+            self._day = today
+            self._spent_atomic = 0
+
+    def remaining_atomic(self) -> int:
+        self._roll_if_needed()
+        return max(self.cap_atomic - self._spent_atomic, 0)
+
+    def reserve(self, worst_case_atomic: str):
+        self._roll_if_needed()
+        amount = int(worst_case_atomic)
+        if self._spent_atomic + amount > self.cap_atomic:
+            raise SingItPaymentError(
+                f"Daily spend cap reached: {self._spent_atomic} already spent today, "
+                f"{amount} more would exceed {self.cap_atomic} micro-USDC."
+            )
+        self._spent_atomic += amount
+        # A release only ever touches the day it was reserved on: a request spanning UTC midnight must not take
+        # yesterday's reservation off today's counter (Codex review).
+        day = self._day
+        state = {"done": False}
+
+        def release():
+            if state["done"]:
+                return
+            state["done"] = True
+            self._roll_if_needed()
+            if self._day == day:
+                self._spent_atomic -= amount
+
+        release.day = day
+        return release
+
+    def settle(self, release, actual_atomic: str | None, worst_case_atomic: str) -> None:
+        self._roll_if_needed()
+        if getattr(release, "day", self._day) != self._day:
+            return  # yesterday's spend; today's counter starts clean
+        release()
+        self._spent_atomic += int(actual_atomic if actual_atomic is not None else worst_case_atomic)
+
+
+def usd_to_atomic(usd: float) -> str:
+    if not isinstance(usd, (int, float)) or isinstance(usd, bool) or usd < 0:
+        raise SingItPaymentError("max_per_call_usd/max_per_day_usd must be a non-negative number.")
+    return str(round(usd * 1_000_000))

singit-0.1.0/src/singit/pins.py

@@ -0,0 +1,56 @@
+"""Pinned, per-network expectations an x402 offer must match before the SDK signs anything.
+
+Base and Solana values are the live SingIt Ask addresses (singit-ask/src/pricing.mjs).
+Base Sepolia has no SingIt deployment: its USDC address is the well-known testnet asset, and
+`pay_to` is never pinned here -- the caller must pass one explicitly (SingIt(pay_to=...)).
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NetworkPin:
+    caip: str
+    family: str  # "evm" | "svm"
+    asset: str
+    pay_to: str | None
+    asset_name: str = "USDC"
+    asset_version: str = "2"
+    default_rpc_url: str | None = None
+
+
+NETWORKS: dict[str, NetworkPin] = {
+    "base": NetworkPin(
+        caip="eip155:8453",
+        family="evm",
+        asset="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        pay_to="0xC23d1Dc0f5fCe1abfFB051e06cB93f0329968B4e",
+        asset_name="USD Coin",
+        asset_version="2",
+        default_rpc_url="https://mainnet.base.org",
+    ),
+    "base-sepolia": NetworkPin(
+        caip="eip155:84532",
+        family="evm",
+        asset="0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        pay_to=None,
+        asset_name="USDC",
+        asset_version="2",
+        default_rpc_url="https://sepolia.base.org",
+    ),
+    "solana": NetworkPin(
+        caip="solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        family="svm",
+        asset="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+        pay_to="4an2sqamWWhny9mjLsMtGXCDXakeNtg6vSLq4QvhdmQu",
+        default_rpc_url="https://api.mainnet-beta.solana.com",
+    ),
+}
+
+DEFAULT_BASE_URL = "https://ask.singitai.app"
+DEFAULT_APP_BASE_URL = "https://app.singitai.app"
+ROUTE = "/v1/chat/completions"
+
+
+def per_model_route(model: str) -> str:
+    return f"/v1/chat/{model}"