smart402 0.1.0__tar.gz

smart402-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Roberto Moreno
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

smart402-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: smart402
+Version: 0.1.0
+Summary: Deterministic risk engine for AI agent payments via x402
+Author-email: Roberto Moreno <rob@smart402.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Falinkaz/smart402-python
+Project-URL: Documentation, https://github.com/Falinkaz/smart402-python/blob/main/API.md
+Project-URL: Repository, https://github.com/Falinkaz/smart402-python
+Project-URL: Issues, https://github.com/Falinkaz/smart402-python/issues
+Keywords: x402,ai-agents,payments,risk,stablecoin,blockchain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: x402
+Requires-Dist: x402[evm,httpx]<3,>=2.3.0; extra == "x402"
+Provides-Extra: all
+Requires-Dist: x402[evm,httpx]<3,>=2.3.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Dynamic: license-file
+
+# smart402 — Python SDK
+
+Deterministic policy engine for AI agent payments via [x402](https://x402.org).
+
+No LLM in the decision path. Every approve/deny traces to a rule your team configured — not a model's judgment call. A compromised agent cannot reason or prompt-inject its way past smart402.
+
+> **v0.1:** smart402 currently supports USDC transactions on Base (eip155:8453). Other tokens and chains are on the roadmap.
+
+## Install
+
+```bash
+pip install smart402
+```
+
+For x402 integration extras:
+
+```bash
+pip install "smart402[x402]"
+```
+
+Python 3.10+ required.
+
+## Before you start
+
+1. Sign up at https://smart402-dashboard.vercel.app
+2. Create an agent in the dashboard
+3. Configure at least one policy (e.g., daily budget of $10)
+4. Create an evaluate-scoped API key in Settings → API Keys
+5. Follow the Quick Start below.
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from smart402 import Smart402Client
+
+async def main():
+    client = Smart402Client(
+        api_key=os.environ["SMART402_AGENT_KEY"],
+        agent_id="my-agent-001",
+    )
+
+    result = await client.evaluate_payment(
+        amount="0.10",          # USDC amount as a decimal string. "0.10" = ten cents. The Python SDK expects pre-converted dollar decimals.
+        token="USDC",
+        network="eip155:8453",  # Base mainnet (CAIP-2)
+        pay_to="0x9dBA414637c611a16BEa6f0796BFcbcBdc410df8",
+    )
+
+    print(result.decision)           # "approve" or "deny"
+    print(result.triggered_rules)    # [] or ["counterparty_not_on_allowlist", ...]
+
+asyncio.run(main())
+```
+
+[Get an API key →](https://smart402-dashboard.vercel.app)
+
+**Synchronous usage:** `asyncio.run()` wraps any async call. A sync API is planned for v0.2.
+
+## x402 Integration
+
+If your agent uses the [x402 Python SDK](https://github.com/coinbase/x402), register smart402 as a lifecycle hook:
+
+```python
+from smart402 import smart402_hook
+from x402 import x402Client
+from x402.mechanisms.evm.exact import register_exact_evm_client
+from x402.mechanisms.evm.signers import EthAccountSigner
+from eth_account import Account
+
+account = Account.from_key(os.environ["EVM_PRIVATE_KEY"])
+signer = EthAccountSigner(account)
+
+client = x402Client()
+register_exact_evm_client(client, signer)
+
+# One line to add smart402 protection
+client.on_before_payment_creation(
+    smart402_hook(
+        api_key=os.environ["SMART402_AGENT_KEY"],
+        agent_id="my-agent-001",
+        agent_wallet_address=signer.address,
+    )
+)
+
+# Every payment the x402 client makes is now evaluated first
+```
+
+The hook fires before each payment is signed. If smart402 denies the payment, `AbortResult` is returned and the payment is not made.
+
+## Advanced Usage
+
+For full control over all request fields, use the Pydantic models directly:
+
+```python
+from smart402 import Smart402Client
+from smart402.models import EvaluateRequest, PaymentRequirementsPayload
+
+client = Smart402Client(
+    api_key=os.environ["SMART402_AGENT_KEY"],
+    agent_id="my-agent-001",
+)
+
+result = await client.evaluate(
+    EvaluateRequest(
+        agent_id=client.agent_id,  # set in the constructor above
+        agent_wallet_address="0x...",
+        payment_requirements=PaymentRequirementsPayload(
+            amount="0.10",
+            token="USDC",
+            network="eip155:8453",
+            pay_to="0x9dBA414637c611a16BEa6f0796BFcbcBdc410df8",
+        ),
+    )
+)
+```
+
+## Configuration
+
+**`Smart402Client(api_key, agent_id, ...)`**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | required | smart402 API key |
+| `agent_id` | required | Agent identifier (from dashboard) |
+| `base_url` | `https://streetsmart-api.fly.dev` | API base URL |
+
+**Amount format:** Pass `amount` as a decimal dollar string — `"0.10"` = ten cents. The Python SDK expects pre-converted dollar decimals. If you're reading the amount from an x402 `PaymentRequirements` object (which uses raw USDC units), convert it first: `str(int(raw_amount) / 1_000_000)`.
+
+**`smart402_hook(api_key, agent_id, ...)`**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | required | smart402 API key |
+| `agent_id` | required | Agent identifier (from dashboard) |
+| `smart402_url` | `https://streetsmart-api.fly.dev` | API base URL |
+| `fail_mode` | `"fail_open"` | Behavior when API is unreachable |
+| `agent_wallet_address` | `None` | Agent's public EVM address |
+| `wallet_provider` | `None` | e.g. `"coinbase"`, `"local_evm"` |
+| `agent_framework` | `None` | e.g. `"langchain"`, `"langgraph"` |
+
+## Fail-Open vs Fail-Closed
+
+```python
+# fail_open (default): if smart402 is unreachable, payment proceeds
+smart402_hook(api_key="...", agent_id="...", fail_mode="fail_open")
+
+# fail_closed: if smart402 is unreachable, payment is blocked
+smart402_hook(api_key="...", agent_id="...", fail_mode="fail_closed")
+```
+
+| Mode | When API is unreachable |
+|------|------------------------|
+| `fail_open` (default) | Warning logged, payment proceeds |
+| `fail_closed` | `AbortResult` returned to x402 — payment is not made |
+
+## Error Handling
+
+```python
+result = await client.evaluate_payment(
+    amount="0.10", token="USDC",
+    network="eip155:8453", pay_to="0x...",
+)
+if result.decision == "deny":
+    print("Blocked by:", result.triggered_rules)
+    print("Evaluation ID:", result.evaluation_id)
+```
+
+When using `smart402_hook()`, a denied payment returns `AbortResult` to the x402 client — the payment is not made and no exception is raised to your code. When calling `Smart402Client.evaluate()` directly, check `result.decision` — the client always returns the response, never raises on denial.
+
+`Smart402Denied` and `Smart402Unavailable` are not raised in v0.1.
+
+## What data leaves your machine
+
+The SDK sends to the smart402 API:
+- amount, token, network, recipient address
+- agent ID and wallet address (public, not private key)
+
+The SDK never sends:
+- Private keys, seed phrases, or wallet passwords
+- Signed transactions or raw transaction data
+- Wallet balances
+
+One HTTPS call to `POST /evaluate`. No telemetry, no analytics, no side-channel requests.
+Verify: the SDK is ~200 lines of code. Read it.
+
+Read the full trust model: [SECURITY.md](https://github.com/Falinkaz/smart402-python/blob/main/SECURITY.md)
+
+## Limits
+
+- Rate limit: 600 requests per minute per account
+- Typical latency: 10–50ms (p50), under 200ms (p99)
+- If the API is unreachable, `fail_open` (default) lets the payment proceed. `fail_closed` blocks it.
+- The SDK does not retry on failure — it returns the error immediately, keeping latency predictable and letting you own retry logic.
+- Default request timeout: 5 seconds (not configurable in v0.1)
+
+## API Reference
+
+Full endpoint documentation: [API.md](https://github.com/Falinkaz/smart402-python/blob/main/API.md)
+
+## License
+
+Apache 2.0 — see [LICENSE](https://github.com/Falinkaz/smart402-python/blob/main/LICENSE)

smart402-0.1.0/README.md

@@ -0,0 +1,204 @@
+# smart402 — Python SDK
+
+Deterministic policy engine for AI agent payments via [x402](https://x402.org).
+
+No LLM in the decision path. Every approve/deny traces to a rule your team configured — not a model's judgment call. A compromised agent cannot reason or prompt-inject its way past smart402.
+
+> **v0.1:** smart402 currently supports USDC transactions on Base (eip155:8453). Other tokens and chains are on the roadmap.
+
+## Install
+
+```bash
+pip install smart402
+```
+
+For x402 integration extras:
+
+```bash
+pip install "smart402[x402]"
+```
+
+Python 3.10+ required.
+
+## Before you start
+
+1. Sign up at https://smart402-dashboard.vercel.app
+2. Create an agent in the dashboard
+3. Configure at least one policy (e.g., daily budget of $10)
+4. Create an evaluate-scoped API key in Settings → API Keys
+5. Follow the Quick Start below.
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from smart402 import Smart402Client
+
+async def main():
+    client = Smart402Client(
+        api_key=os.environ["SMART402_AGENT_KEY"],
+        agent_id="my-agent-001",
+    )
+
+    result = await client.evaluate_payment(
+        amount="0.10",          # USDC amount as a decimal string. "0.10" = ten cents. The Python SDK expects pre-converted dollar decimals.
+        token="USDC",
+        network="eip155:8453",  # Base mainnet (CAIP-2)
+        pay_to="0x9dBA414637c611a16BEa6f0796BFcbcBdc410df8",
+    )
+
+    print(result.decision)           # "approve" or "deny"
+    print(result.triggered_rules)    # [] or ["counterparty_not_on_allowlist", ...]
+
+asyncio.run(main())
+```
+
+[Get an API key →](https://smart402-dashboard.vercel.app)
+
+**Synchronous usage:** `asyncio.run()` wraps any async call. A sync API is planned for v0.2.
+
+## x402 Integration
+
+If your agent uses the [x402 Python SDK](https://github.com/coinbase/x402), register smart402 as a lifecycle hook:
+
+```python
+from smart402 import smart402_hook
+from x402 import x402Client
+from x402.mechanisms.evm.exact import register_exact_evm_client
+from x402.mechanisms.evm.signers import EthAccountSigner
+from eth_account import Account
+
+account = Account.from_key(os.environ["EVM_PRIVATE_KEY"])
+signer = EthAccountSigner(account)
+
+client = x402Client()
+register_exact_evm_client(client, signer)
+
+# One line to add smart402 protection
+client.on_before_payment_creation(
+    smart402_hook(
+        api_key=os.environ["SMART402_AGENT_KEY"],
+        agent_id="my-agent-001",
+        agent_wallet_address=signer.address,
+    )
+)
+
+# Every payment the x402 client makes is now evaluated first
+```
+
+The hook fires before each payment is signed. If smart402 denies the payment, `AbortResult` is returned and the payment is not made.
+
+## Advanced Usage
+
+For full control over all request fields, use the Pydantic models directly:
+
+```python
+from smart402 import Smart402Client
+from smart402.models import EvaluateRequest, PaymentRequirementsPayload
+
+client = Smart402Client(
+    api_key=os.environ["SMART402_AGENT_KEY"],
+    agent_id="my-agent-001",
+)
+
+result = await client.evaluate(
+    EvaluateRequest(
+        agent_id=client.agent_id,  # set in the constructor above
+        agent_wallet_address="0x...",
+        payment_requirements=PaymentRequirementsPayload(
+            amount="0.10",
+            token="USDC",
+            network="eip155:8453",
+            pay_to="0x9dBA414637c611a16BEa6f0796BFcbcBdc410df8",
+        ),
+    )
+)
+```
+
+## Configuration
+
+**`Smart402Client(api_key, agent_id, ...)`**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | required | smart402 API key |
+| `agent_id` | required | Agent identifier (from dashboard) |
+| `base_url` | `https://streetsmart-api.fly.dev` | API base URL |
+
+**Amount format:** Pass `amount` as a decimal dollar string — `"0.10"` = ten cents. The Python SDK expects pre-converted dollar decimals. If you're reading the amount from an x402 `PaymentRequirements` object (which uses raw USDC units), convert it first: `str(int(raw_amount) / 1_000_000)`.
+
+**`smart402_hook(api_key, agent_id, ...)`**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | required | smart402 API key |
+| `agent_id` | required | Agent identifier (from dashboard) |
+| `smart402_url` | `https://streetsmart-api.fly.dev` | API base URL |
+| `fail_mode` | `"fail_open"` | Behavior when API is unreachable |
+| `agent_wallet_address` | `None` | Agent's public EVM address |
+| `wallet_provider` | `None` | e.g. `"coinbase"`, `"local_evm"` |
+| `agent_framework` | `None` | e.g. `"langchain"`, `"langgraph"` |
+
+## Fail-Open vs Fail-Closed
+
+```python
+# fail_open (default): if smart402 is unreachable, payment proceeds
+smart402_hook(api_key="...", agent_id="...", fail_mode="fail_open")
+
+# fail_closed: if smart402 is unreachable, payment is blocked
+smart402_hook(api_key="...", agent_id="...", fail_mode="fail_closed")
+```
+
+| Mode | When API is unreachable |
+|------|------------------------|
+| `fail_open` (default) | Warning logged, payment proceeds |
+| `fail_closed` | `AbortResult` returned to x402 — payment is not made |
+
+## Error Handling
+
+```python
+result = await client.evaluate_payment(
+    amount="0.10", token="USDC",
+    network="eip155:8453", pay_to="0x...",
+)
+if result.decision == "deny":
+    print("Blocked by:", result.triggered_rules)
+    print("Evaluation ID:", result.evaluation_id)
+```
+
+When using `smart402_hook()`, a denied payment returns `AbortResult` to the x402 client — the payment is not made and no exception is raised to your code. When calling `Smart402Client.evaluate()` directly, check `result.decision` — the client always returns the response, never raises on denial.
+
+`Smart402Denied` and `Smart402Unavailable` are not raised in v0.1.
+
+## What data leaves your machine
+
+The SDK sends to the smart402 API:
+- amount, token, network, recipient address
+- agent ID and wallet address (public, not private key)
+
+The SDK never sends:
+- Private keys, seed phrases, or wallet passwords
+- Signed transactions or raw transaction data
+- Wallet balances
+
+One HTTPS call to `POST /evaluate`. No telemetry, no analytics, no side-channel requests.
+Verify: the SDK is ~200 lines of code. Read it.
+
+Read the full trust model: [SECURITY.md](https://github.com/Falinkaz/smart402-python/blob/main/SECURITY.md)
+
+## Limits
+
+- Rate limit: 600 requests per minute per account
+- Typical latency: 10–50ms (p50), under 200ms (p99)
+- If the API is unreachable, `fail_open` (default) lets the payment proceed. `fail_closed` blocks it.
+- The SDK does not retry on failure — it returns the error immediately, keeping latency predictable and letting you own retry logic.
+- Default request timeout: 5 seconds (not configurable in v0.1)
+
+## API Reference
+
+Full endpoint documentation: [API.md](https://github.com/Falinkaz/smart402-python/blob/main/API.md)
+
+## License
+
+Apache 2.0 — see [LICENSE](https://github.com/Falinkaz/smart402-python/blob/main/LICENSE)

smart402-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smart402"
+version = "0.1.0"
+description = "Deterministic risk engine for AI agent payments via x402"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Roberto Moreno", email = "rob@smart402.com"},
+]
+keywords = ["x402", "ai-agents", "payments", "risk", "stablecoin", "blockchain"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+x402 = ["x402[evm,httpx]>=2.3.0,<3"]
+all = ["x402[evm,httpx]>=2.3.0,<3"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+]
+
+[project.urls]
+Homepage = "https://github.com/Falinkaz/smart402-python"
+Documentation = "https://github.com/Falinkaz/smart402-python/blob/main/API.md"
+Repository = "https://github.com/Falinkaz/smart402-python"
+Issues = "https://github.com/Falinkaz/smart402-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["smart402*"]

smart402-0.1.0/setup.cfg

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

smart402-0.1.0/smart402/__init__.py

@@ -0,0 +1,12 @@
+"""smart402 SDK — deterministic risk engine for AI agent payments via x402."""
+
+from .client import Smart402Client
+from .guard import Smart402Guard, smart402_hook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "smart402_hook",
+    "Smart402Guard",
+    "Smart402Client",
+]

smart402-0.1.0/smart402/client.py

@@ -0,0 +1,91 @@
+"""HTTP client for the smart402 API."""
+
+import logging
+from urllib.parse import urlparse
+
+import httpx
+
+from .models import EvaluateRequest, EvaluateResponse, PaymentRequirementsPayload
+
+logger = logging.getLogger("smart402")
+
+
+class Smart402Client:
+    """Async HTTP client that calls the smart402 evaluation API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        agent_id: str,
+        base_url: str = "https://streetsmart-api.fly.dev",
+    ):
+        self.api_key = api_key
+        self.agent_id = agent_id
+        self.base_url = base_url.rstrip("/")
+        self._warn_if_insecure()
+
+    def _warn_if_insecure(self) -> None:
+        parsed = urlparse(self.base_url)
+        if parsed.scheme == "http" and parsed.hostname not in (
+            "localhost",
+            "127.0.0.1",
+            "::1",
+        ):
+            logger.warning(
+                "⚠️  smart402 SDK is connecting over HTTP to %s. "
+                "API keys sent over HTTP are vulnerable to interception. "
+                "Use https:// for non-localhost connections.",
+                parsed.hostname,
+            )
+
+    async def evaluate(self, request: EvaluateRequest) -> EvaluateResponse:
+        """Call POST /evaluate and return the decision.
+
+        Args:
+            request: EvaluateRequest with agent info and payment requirements.
+
+        Returns:
+            EvaluateResponse with decision ("approve" or "deny").
+
+        Raises:
+            httpx.HTTPStatusError: On non-2xx responses.
+            httpx.TimeoutException: If request times out.
+        """
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.post(
+                f"{self.base_url}/evaluate",
+                json=request.model_dump(),
+                headers={"Authorization": f"Bearer {self.api_key}"},
+            )
+            response.raise_for_status()
+            return EvaluateResponse(**response.json())
+
+    async def evaluate_payment(
+        self,
+        amount: str,
+        token: str,
+        network: str,
+        pay_to: str,
+    ) -> EvaluateResponse:
+        """Convenience wrapper around evaluate() for simple one-payment calls.
+
+        Args:
+            amount: Dollar decimal string (e.g. "0.10" for $0.10 USDC).
+            token: Token symbol. smart402 v0.1 accepts "USDC" only.
+            network: CAIP-2 network identifier (e.g. "eip155:8453" for Base mainnet).
+            pay_to: Recipient wallet address.
+
+        Returns:
+            EvaluateResponse with decision ("approve" or "deny").
+        """
+        return await self.evaluate(
+            EvaluateRequest(
+                agent_id=self.agent_id,
+                payment_requirements=PaymentRequirementsPayload(
+                    amount=amount,
+                    token=token,
+                    network=network,
+                    pay_to=pay_to,
+                ),
+            )
+        )