agentscore-commerce 1.0.0__tar.gz

agentscore_commerce-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug Report
+about: Report a bug
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- Package version:
+- Python version:
+- OS:
+- Submodule used (`agentscore_commerce.identity.fastapi`, `.payment`, `.discovery`, etc.):

agentscore_commerce-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature Request
+about: Suggest an improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Describe the feature**
+A clear description of what you'd like.
+
+**Use case**
+Why is this needed? What problem does it solve?
+
+**Submodule**
+Which commerce submodule does this affect? (`identity.*`, `payment`, `discovery`, `challenge`, `stripe_multichain`, `api`)

agentscore_commerce-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## Summary
+
+<!-- What does this PR do? -->
+
+## Test plan
+
+<!-- How was this tested? -->

agentscore_commerce-1.0.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    labels: ["dependencies", "python"]
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "America/New_York"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    labels: ["dependencies", "ci"]
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "America/New_York"

agentscore_commerce-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: blacksmith-2vcpu-ubuntu-2404-arm
+    timeout-minutes: 10
+    steps:
+      - uses: useblacksmith/checkout@v1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/uv
+            ~/.local/share/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Type check (ty)
+        run: uv run ty check agentscore_commerce/
+
+      - name: Vulture
+        run: uv run vulture agentscore_commerce/ vulture_whitelist.py --min-confidence 80
+
+      - name: Tests
+        run: uv run pytest tests/ -v --cov=agentscore_commerce --cov-report=term-missing

agentscore_commerce-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set version from tag
+        run: sed -i "s/^version = .*/version = \"${GITHUB_REF_NAME#v}\"/" pyproject.toml
+
+      - run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        run: gh release create "$GITHUB_REF_NAME" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

agentscore_commerce-1.0.0/.github/workflows/security.yml

@@ -0,0 +1,49 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  osv-scan:
+    name: Dependency Scan
+    runs-on: blacksmith-2vcpu-ubuntu-2404-arm
+    timeout-minutes: 5
+    steps:
+      - uses: useblacksmith/checkout@v1
+
+      - name: Install osv-scanner
+        run: |
+          curl -fsSL https://github.com/google/osv-scanner/releases/download/v2.3.5/osv-scanner_linux_arm64 -o osv-scanner
+          chmod +x osv-scanner
+
+      - name: Scan dependencies
+        run: ./osv-scanner scan source --lockfile=uv.lock --format=table
+
+  pip-audit:
+    name: Python Audit
+    runs-on: blacksmith-2vcpu-ubuntu-2404-arm
+    timeout-minutes: 5
+    steps:
+      - uses: useblacksmith/checkout@v1
+      - uses: astral-sh/setup-uv@v8.1.0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Audit dependencies
+        run: |
+          uv export --format requirements-txt --no-hashes > requirements.txt
+          pip-audit -r requirements.txt --disable-pip --no-deps

agentscore_commerce-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.swp
+*.swo
+.DS_Store
+.coverage

agentscore_commerce-1.0.0/CLAUDE.md

@@ -0,0 +1,127 @@
+# agentscore-commerce
+
+Agent commerce SDK for Python. The full merchant-side toolkit: identity gating + payment helpers + 402 builders + discovery + Stripe multichain. One install, submodule imports per concern.
+
+Every helper lifts directly from working production code (`agentscore/martin-estate`) — extract from real consumers, not speculation.
+
+## Submodules
+
+| Submodule | What it is |
+|---|---|
+| `agentscore_commerce.identity.{fastapi,flask,django,aiohttp,sanic,middleware}` | Trust gate middleware (KYC, age, sanctions, jurisdiction) |
+| `agentscore_commerce.payment` | Networks/USDC/rails registries, paymentauth.org directive builders, `create_x402_server` (wraps official `x402[evm,svm]>=2.8` peer dep with v1+v2 dual-register + bazaar extension), `create_mppx_server` (wraps `pympp[server,tempo,stripe]>=0.6` peer dep with Tempo charge/session + Stripe SPT helpers), dispatch-by-network, signer extraction, WWW-Authenticate header, Settlement-Overrides header |
+| `agentscore_commerce.discovery` | Discovery probe, Bazaar wrapper, `/.well-known/mpp.json`, `llms.txt` builder, OpenAPI snippets, `NoindexNonDiscoveryMiddleware` ASGI middleware |
+| `agentscore_commerce.challenge` | 402-body builders: accepted_methods, identity_metadata, how_to_pay, agent_instructions, build_402_body, `build_validation_error` (4xx body builder) |
+| `agentscore_commerce.stripe_multichain` | Multichain PaymentIntent helper, deposit-address lookup, testnet simulator, mppx Stripe wrapper |
+| `agentscore_commerce.api` | Re-exports `AgentScore` from `agentscore` SDK |
+
+## Architecture
+
+Single Python package, hatchling-built, published to PyPI as `agentscore-commerce`. Per-framework identity adapters expose the same surface — `AgentScoreGate` (or `agentscore_gate(app, ...)` for Flask/Sanic), `capture_wallet`, `verify_wallet_signer_match`, `get_assess_data` — with network-aware address normalization (EVM lowercased, Solana base58 preserved verbatim).
+
+| Directory | Contents |
+|---|---|
+| `agentscore_commerce/identity/` | Per-framework gate adapters (fastapi, flask, django, aiohttp, sanic, middleware/ASGI), shared client, sessions, address normalization, signer extraction, response marshalling, types, cache |
+| `agentscore_commerce/payment/` | Payment-protocol helpers |
+| `agentscore_commerce/discovery/` | Discovery probe + machine-readable docs |
+| `agentscore_commerce/challenge/` | 402-body builders |
+| `agentscore_commerce/stripe_multichain/` | Stripe multichain PaymentIntent helpers |
+| `agentscore_commerce/api/` | `AgentScore` re-export |
+| `examples/` | Runnable single-file FastAPI apps for each common scenario |
+| `tests/` | pytest, one file per surface |
+
+Peer-dep pattern: payment/x402/mppx/stripe modules import lazily at runtime — vendors install only what they use via extras (`pip install agentscore-commerce[fastapi,stripe]` etc.). Underlying packages: `x402[evm,svm]`, `pympp[server,tempo,stripe]`, `stripe`. Missing peer dep raises a guiding `ImportError` with the install command.
+
+## Examples
+
+`examples/` contains full single-file FastAPI apps for the most common merchant scenarios — copy-paste templates, not frameworks:
+
+| Example | Scenario |
+|---|---|
+| `api_provider.py` | Per-call API billing on multiple rails: Tempo MPP + x402 (Base + Solana); no compliance gate |
+| `identity_only.py` | Compliance gate without payment (vendor handles their own) |
+| `multi_rail_merchant.py` | Full agent-commerce: identity + Tempo MPP + x402 + Stripe SPT |
+| `stripe_multichain_merchant.py` | Stripe-anchored multichain (PaymentIntent → tempo/base/solana deposit addresses) |
+| `variable_cost_merchant.py` | Pay-per-actual-usage on **two protocols**: x402 upto (Permit2 + Settlement-Overrides) AND MPP tempo session (channel + SSE + mid-stream vouchers) |
+| `compliance_merchant.py` | Regulated-goods merchant — full compliance gate + custom `on_denied` composing the denial helpers (`verification_agent_instructions`, `is_fixable_denial`, `build_signer_mismatch_body`, `build_contact_support_next_steps`, `denial_reason_to_body`/`denial_reason_status`) |
+| `per_product_policy_merchant.py` | Multi-product merchant where each row carries its own compliance policy. One product hard-gates KYC + age + state; another is anonymous; a third uses `enforcement="soft"` (request KYC but don't block sale). Demonstrates `PolicyBlock`, `build_gate_from_policy`, `run_gate_with_enforcement`, `shipping_country_allowed`, `shipping_state_allowed`. |
+
+## Identity model
+
+Two identity types: wallet (`X-Wallet-Address`) and operator-token (`X-Operator-Token`). Default checks operator-token first, then wallet. Address normalization is network-aware via `agentscore_commerce/identity/address.py`: EVM lowercased, Solana base58 preserved verbatim — used for cache keys, wallet→operator resolves, and signer-match comparisons.
+
+`DenialReason` codes (`missing_identity`, `identity_verification_required`, `token_expired`, `invalid_credential`, `wallet_signer_mismatch`, `wallet_auth_requires_wallet_signing`, `wallet_not_trusted`, `api_error`, `payment_required`) each carry a structured `agent_instructions` JSON block describing concrete recovery actions. See `agentscore_commerce/identity/_response.py` for the canned action copy.
+
+`create_session_on_missing` auto-mints a verification session when no identity is present and returns 403 with `verify_url` + poll instructions. `verify_wallet_signer_match` (per-adapter) compares the recovered signer against `linked_wallets[]` for cross-chain wallet-stack matching.
+
+Captured wallets: `capture_wallet(...)` is fire-and-forget — reads `operator_token` stashed during gating and POSTs to `/v1/credentials/wallets`. No-ops for wallet-authenticated requests.
+
+### Mount posture: gate-first vs gate-conditional
+
+`AgentScoreGate(...)` (or `agentscore_gate(app, ...)` on Flask/Sanic) is mounted directly when the route is AgentScore-only — every request runs identity + policy. To support **anonymous discovery by any spec-compliant x402 wallet** (Coinbase awal, Phantom, Solflare, …), wrap the gate so it fires only when a payment credential is attached:
+
+```python
+_gate = AgentScoreGate(api_key=..., require_kyc=True, ...)
+
+async def gate_on_settle(request: Request) -> None:
+    has_payment_header = bool(
+        request.headers.get("payment-signature")
+        or request.headers.get("x-payment")
+        or (request.headers.get("authorization") or "").startswith("Payment ")
+    )
+    if not has_payment_header:
+        return None
+    return await _gate(request)
+
+@app.post("/purchase", dependencies=[Depends(gate_on_settle)])
+async def purchase(...): ...
+```
+
+Anonymous POST flows through to the handler unauthenticated and gets a 402 with all rails + per-order pricing. Identity is verified at settle time on the retry leg (when the agent submits `X-Payment` / `Authorization: Payment`); `create_session_on_missing` still auto-mints a verification session there. The same wrap pattern works identically across all 6 framework adapters (fastapi, flask, django, aiohttp, sanic, middleware/ASGI). See `examples/multi_rail_merchant.py` and `examples/compliance_merchant.py`.
+
+### `compatible_clients` field on emitted 402s
+
+`build_agent_instructions` emits a `compatible_clients` field in the 402 body, derived automatically from `how_to_pay` — per-rail list of CLIs the AgentScore team has smoke-verified end-to-end. Vendors override with `BuildAgentInstructionsInput(compatible_clients={...})` to add their own tested clients. Set to an empty dict `{}` to suppress the default. Same data is published as `core/docs/integrations/x402-clients.mdx` for human-side rationale + per-rail commands.
+
+## Tooling
+
+- **uv** — package manager.
+- **ruff** — linting + formatting.
+- **ty** — type checker (Astral).
+- **vulture** — dead code detection.
+- **pytest** — tests.
+- **Lefthook** — pre-commit ruff, pre-push ty + vulture (parallel).
+
+```bash
+uv sync --all-extras
+uv run lefthook install   # one-time per clone — wires pre-commit + pre-push
+uv run ruff check .
+uv run ruff format .
+uv run ty check agentscore_commerce/
+uv run pytest tests/
+```
+
+## Workflow
+
+1. Create a branch
+2. Make changes
+3. Lefthook runs ruff on commit, ty + vulture on push
+4. Open a PR — CI runs automatically
+5. Merge (squash)
+
+## Rules
+
+- **No silent refactors**
+- **Never commit .env files or secrets**
+- **Use PRs** — never push directly to main
+- **Helpers are protocol translations + configurable opinions, not opinionated frameworks**
+- **Cross-language API parity** — keep the surface area identical between the node and python flavors so vendors switching languages have the same mental model
+
+## Releasing
+
+1. Update `version` in `pyproject.toml`
+2. Commit: `git commit -am "chore: bump to vX.Y.Z"`
+3. Tag: `git tag vX.Y.Z`
+4. Push: `git push && git push origin vX.Y.Z`
+
+The publish workflow runs on `ubuntu-latest` (required for PyPI trusted publishing), builds, publishes to PyPI via OIDC, and creates a GitHub Release.

agentscore_commerce-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at engineering@agentscore.sh. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

agentscore_commerce-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to AgentScore
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+1. Fork the repo and clone it locally
+2. Install dependencies (see README for tooling)
+3. Create a branch from `main`
+4. Make your changes
+5. Run linting and tests
+6. Open a pull request
+
+## Pull Requests
+
+- All PRs require 1 approval before merging
+- Squash merge to `main` is the standard
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new functionality
+- Make sure CI passes before requesting review
+
+## Reporting Issues
+
+Open an issue on GitHub with:
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, runtime version)
+
+## Code Style
+
+- **TypeScript repos**: ESLint handles formatting and style. Run `bun run lint` before committing.
+- **Python repos**: Ruff handles linting and formatting. Run `uv run ruff check .` and `uv run ruff format .` before committing.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

agentscore_commerce-1.0.0/LICENSE

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