solvapay-python 0.7.1__tar.gz → 0.8.0__tar.gz

solvapay_python-0.8.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,27 @@
+name: Bug Report
+description: Something broken in the SDK
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Please fill in the details below.
+  - type: input
+    id: version
+    attributes:
+      label: SDK version
+      placeholder: "0.8.0"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: What did you expect vs what actually happened?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal repro
+      description: Minimal Python snippet to reproduce
+      render: python

solvapay_python-0.8.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - Nice to have
+        - Blocking a use-case

solvapay_python-0.8.0/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,14 @@
+name: Question
+description: How do I...?
+labels: [question]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: What are you trying to do?
+    validations:
+      required: true
+  - type: textarea
+    id: tried
+    attributes:
+      label: What have you tried?

solvapay_python-0.8.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What
+
+<!-- Brief description of the change -->
+
+## Why
+
+<!-- Problem it solves or feature it adds -->
+
+## Checklist
+
+- [ ] Tests added / updated
+- [ ] `CHANGELOG.md` entry added
+- [ ] Layer DAG respected (`uv run lint-imports` passes)
+- [ ] If new public exports: `tools/api_baseline.json` updated
+- [ ] Docs updated (if public API changed)

{solvapay_python-0.7.1 → solvapay_python-0.8.0}/.github/workflows/ci.yml

@@ -20,5 +20,8 @@ jobs:
         run: uv python install ${{ matrix.python-version }}
       - run: uv sync --all-extras --dev
       - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
       - run: uv run mypy src
       - run: uv run pytest -v
+      - run: uv run python tools/api_diff.py
+      - run: uv run lint-imports --config tools/importlinter.cfg

solvapay_python-0.8.0/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## 0.8.0 — 2026-05-23
+
+V1 architecture spine + AI-agent moat. 10 atomic commits establishing locked architecture invariants per HLD §V1.1–V1.19.
+
+### Added
+- **Transport Protocol kernel** (`solvapay._transport`): `Transport`/`AsyncTransport` Protocol shapes, `RequestSpec`/`ResponseSpec` frozen dataclasses, case-insensitive `Headers`, canonical middleware stack (`Redacting` → `Logging` → `IdempotencyHeader` → `ContextPropagating`), `default_stack()` recipe.
+- **Operations registry + resource-namespace API**: `OpSpec` + `RetrySafety` enum, `REGISTRY`, path interpolation with `urllib.parse.quote`. All clients gain eager namespace attrs: `sv.customers`, `sv.checkout`, `sv.limits`, `sv.purchases`, `sv.usage`, `sv.products`, `sv.plans`, `sv.merchant`.
+- **Paywall package** (`solvapay.paywall`): `Paywall`/`AsyncPaywall` split with type-narrowed construction, `PaywallRequired.checkout_mint_error`, `PayableToolMeta(_meta_version=1)`, `KwargsResolver`/`PositionalResolver`/`PydanticBodyResolver`, `@require`/`@require_async`/`@payable_tool` decorators.
+- **Webhook pipeline** (`solvapay.webhooks`): `WebhookPipeline` with two-knob config (`max_clock_skew_seconds`, `replay_ttl_seconds`), atomic `SeenEventCache.try_claim` (`threading.Lock`), `MultiSecretVerifier` interface, `WebhookEnvelope` dataclass.
+- **`solvapay.adapters.mcp`** (optional `solvapay[mcp]`): `@payable_tool` decorator + four schema flavors (`payable_tool_mcp_schema`, `payable_tool_openai_function`, `payable_tool_anthropic_tool`, `payable_tool_langchain_args_schema`), `register_payable_tool_fastmcp`.
+- **Stability manifest** (`solvapay._stability`): `stable(X)→X` identity decorator registers in `MANIFEST`; `experimental` emits once-per-process `RuntimeWarning`; `deprecated(removed_in=)`. CI gate: `tools/api_diff.py` fails on `@stable` symbol removal without prior `@deprecated`.
+- **Import-linter DAG gate**: `tools/importlinter.cfg` (3 contracts), `docs/architecture/layers.md`. CI fails on layer violation.
+- **LangChain adapter refactor** (`solvapay.adapters.langchain`): Protocol duck-typing — no hard `langchain_core` import at module level; absorbs 0.3→0.4 churn.
+- **Multi-framework demo** (`examples/multi-framework-paywall/`): one `@payable_tool`-decorated function runs across FastMCP, LangChain, and raw async — "one tool, three runtimes, one paywall."
+- **Governance scaffold**: `CODEOWNERS`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `CONTRIBUTING.md`, GitHub issue templates, PR template, `docs/rfcs/0001-spending-policy.md`.
+
+### Changed
+- **Flat methods deprecated**: `sv.ensure_customer()`, `sv.check_limits()`, etc. now emit `DeprecationWarning(stacklevel=2)` per call. Use `sv.customers.ensure()`, `sv.limits.check()`, etc. Flat shims removed in v2.0.
+- **`langchain-core` upper bound**: `langchain-core>=0.3,<0.4` now enforced in both dev and optional deps.
+- **`solvapay.langchain`** replaced by `solvapay.adapters.langchain`; old path is a deprecated shim.
+
+### Deprecated
+- `SolvaPayAPIError` — use `APIError`. Alias fires `DeprecationWarning`; removed in v2.0.
+- All flat client methods (`sv.ensure_customer`, `sv.check_limits`, etc.) — use resource-namespace API.
+
+## 0.7.2 — 2026-05-18
+
+Bug fixes and documentation update.
+
+### Fixed
+- **`paywall.require_async`**: `AsyncSolvaPay()` instantiated without a caller-supplied `client=` was not closed after the decorated function returned, leaking the underlying `httpx.AsyncClient` connection pool. Wrapped in `try/finally`; `await sv.aclose()` called when the decorator owns the client.
+- **`examples/fastmcp-paywall/pyproject.toml`**: dependency used wrong PyPI dist name (`solvapay`) and a stale `@v0.3.0` pin. Updated to `solvapay-python>=0.7.2`.
+- **`examples/langchain-paywall/pyproject.toml`**: same wrong dist name and stale `@v0.5.0` pin. Updated to `solvapay-python[langchain]>=0.7.2`.
+
+### Docs
+- **README** updated to v0.7.1 surface: `paywall_state.gate()`, error hierarchy, idempotency keys, admin ops table, marketplace example, roadmap entries for v0.7.0 and v0.7.1.
+
+### Internal
+- `tests/test_lifecycle.py` reformatted (ruff format compliance)
+
+## 0.7.1 — 2026-05-17
+
+Payments-grade hardening: structured errors, idempotency keys, py.typed, structured logging.
+
+### Added
+- **Structured error hierarchy** (`exceptions.py`): `APIError` base with `status_code`, `request_id`, `error_code`, `error_message`. Subclasses: `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RateLimitError` (429, adds `.retry_after`), `InvalidRequestError` (4xx), `APIServerError` (5xx), `APIConnectionError`, `APITimeoutError`. `SolvaPayAPIError` aliased to `APIError` for back-compat.
+- **Idempotency keys** on all mutating ops: `create_checkout_session`, `ensure_customer`, `track_usage`, `cancel_purchase`, `reactivate_purchase`, `create_product`, `clone_product`, `create_plan` all accept `idempotency_key: str | None = None`. Header casing: `Idempotency-Key` (matches TS SDK).
+- **`solvapay.idempotency.from_payload(*parts)`** — SHA256 of stable-serialized payload parts → 32-hex-char deterministic key.
+- **PEP 561 `py.typed` marker** — downstream mypy users no longer see `Any` on `solvapay.*` imports.
+- **Structured logging** at `solvapay.http` logger: INFO on success (method, path, status, request_id, duration_ms), WARNING on 4xx/5xx (adds body_excerpt ≤200 chars). Never calls `logging.basicConfig`. Optional `logger=` injection on `SolvaPay`/`AsyncSolvaPay` constructors for `loguru`/`structlog`.
+- **Secret redaction**: `Authorization` header never appears in logs. Verified by `tests/test_redaction.py`.
+- **pyproject classifiers**: `Development Status :: 4 - Beta`, `Framework :: AsyncIO`, `Topic :: Office/Business :: Financial`, `Typing :: Typed`.
+
+### Internal
+- User-Agent bumped to `solvapay-python/0.7.1`
+- 142 tests (up from 125), `mypy --strict` clean, `ruff` clean
+
+## 0.7.0 — 2026-05-17
+
+Real-API alignment after testing against the SolvaPay sandbox revealed wire-format mismatches.
+
+### Fixed
+- **`Customer.customer_ref`** now accepts `reference` (real API) in addition to `customerRef` via `validation_alias=AliasChoices(...)`.
+- **`ensure_customer()`** reads `reference` from API response; falls back to `customerRef`. Raises if neither present.
+- **`BalanceResponse`** rewritten: `credits`, `display_currency`, `credits_per_minor_unit`, `display_exchange_rate`; `balance` and `currency` kept as computed properties.
+
+### Added
+- **`paywall_state.gate()`** — one-call enrichment helper (limits + checkout URL + plan via `get_customer`).
+- **`paywall.require` / `require_async`**: auto-mints checkout URL when `LimitResponse.checkout_url is None`.
+- **`examples/marketplace/`** — Streamlit demo with 4 paywalled AI agents (Google Gemini) against real SolvaPay sandbox.
+
+### Internal
+- User-Agent `solvapay-python/0.7.0`. 125 tests (up from 121). `mypy --strict` clean.
+
+## 0.6.0
+- Admin endpoints (products, plans, merchant config). GitHub Actions trusted-publish to PyPI.
+
+## 0.5.0
+- `paywall_state` classifier (ACTIVATION_REQUIRED / TOPUP_REQUIRED / UPGRADE_REQUIRED). LangChain `monetize_tool`.
+
+## 0.4.0
+- Full async client. 5 lifecycle operations. 13 typed webhook event classes.
+
+## 0.3.0
+- FastMCP example: AI agent with two paywalled tools.
+
+## 0.2.0
+- `@paywall.require` decorator. FastAPI webhook router.
+
+## 0.1.0
+- Sync client, HMAC-SHA256 webhook verification, Pydantic v2 models, CI on 3 Python versions.

solvapay_python-0.8.0/CODEOWNERS

@@ -0,0 +1 @@
+* @dhruv-sanan

solvapay_python-0.8.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone.
+
+## Our Standards
+
+**Positive behavior:**
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+**Unacceptable behavior:**
+- Harassment, trolling, or personal attacks
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Community leaders may remove, edit, or reject contributions that violate this Code of Conduct.
+Report issues to `dhruv.sanan@greyorange.com`.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

solvapay_python-0.8.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+## Local development
+
+```bash
+git clone https://github.com/dhruv-sanan/solvapay-python
+cd solvapay-python
+uv sync --all-extras --dev
+```
+
+## Running checks
+
+```bash
+uv run ruff check src tests        # lint
+uv run ruff format --check src tests  # format gate
+uv run mypy src                    # type check
+uv run pytest -v                   # tests
+uv run python tools/api_diff.py    # stability manifest gate
+uv run lint-imports --config tools/importlinter.cfg  # layer DAG gate
+```
+
+## Layer DAG rules
+
+The SDK has a strict layer hierarchy — see [docs/architecture/layers.md](docs/architecture/layers.md).
+
+**Hard rules:**
+- `_transport` must not import `client`, `paywall`, `adapters`, or `operations`
+- `operations` must not import `paywall` or `adapters`
+- `client` must not import `adapters` or `experimental`
+
+CI fails on violations via `import-linter`.
+
+## PR checklist
+
+- [ ] Tests added for new behavior
+- [ ] `CHANGELOG.md` updated
+- [ ] `docs/` updated if public API changed
+- [ ] Layer DAG respected (`uv run lint-imports` passes)
+- [ ] Stability manifest updated if new public exports added
+
+## Commit style
+
+[Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add AsyncPaywall class
+fix(webhooks): set replay_ttl_seconds default correctly
+refactor: extract _transport package
+docs: update README with MCP quickstart
+```
+
+## Adding a new resource namespace
+
+1. Add `OpSpec` entries to `src/solvapay/operations/_registry.py`
+2. Create `src/solvapay/operations/<resource>.py` with sync + async methods
+3. Wire namespace attr in `SolvaPay.__init__` and `AsyncSolvaPay.__init__`
+4. Add deprecated flat shim in `client.py` / `_async_client.py`
+5. Tests in `tests/operations/`

solvapay_python-0.8.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: solvapay-python
+Version: 0.8.0
+Summary: Community Python SDK for SolvaPay (agent-native payment rails)
+Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
+Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
+Project-URL: Official TS SDK, https://github.com/solvapay/solvapay-sdk
+Author: Dhruv Sanan
+License: MIT
+License-File: LICENSE
+Keywords: agents,fintech,mcp,payments,solvapay
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic<2.13,>=2.6
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<0.4,>=0.3; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: fastmcp<0.5,>=0.4; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# solvapay-python
+
+Community Python SDK for [SolvaPay](https://solvapay.com) — agentic payment rails.  
+`pip install solvapay-python` · Python 3.10+ · Fully typed (py.typed) · [PyPI](https://pypi.org/project/solvapay-python/)
+
+[![CI](https://github.com/dhruv-sanan/solvapay-python/actions/workflows/ci.yml/badge.svg)](https://github.com/dhruv-sanan/solvapay-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/solvapay-python.svg)](https://pypi.org/project/solvapay-python/)
+
+---
+
+## One tool. Three runtimes. One paywall.
+
+`@payable_tool` stamps a function with payment metadata once. Any framework reads it — no per-framework wiring.
+
+```python
+# Define once
+from solvapay.adapters.mcp import payable_tool
+
+@payable_tool(product="prd_search")
+def web_search(*, customer_ref: str, query: str) -> list[str]:
+    """Search the web."""
+    return do_real_search(query)
+```
+
+```python
+# Run on MCP (Claude Desktop / Claude Code)
+from solvapay.adapters.mcp import register_payable_tool_fastmcp
+from fastmcp import FastMCP
+
+mcp = FastMCP("My App")
+register_payable_tool_fastmcp(mcp, web_search)
+mcp.run()
+```
+
+```python
+# Run on LangChain
+from solvapay.adapters.langchain import monetize_tool
+
+paid = monetize_tool(web_search, product="prd_search")
+# Blocked callers get {"paywall_required": True, "checkout_url": "..."}
+```
+
+```python
+# Run raw async
+async with AsyncSolvaPay() as sv:
+    limits = await sv.limits.acheck(customer_ref="cus_123", product_ref="prd_search")
+    if limits.within_limits:
+        result = await web_search(customer_ref="cus_123", query="hello")
+```
+
+`pip install 'solvapay-python[mcp]'` · `pip install 'solvapay-python[langchain]'`
+
+---
+
+## Quickstart
+
+```bash
+pip install solvapay-python
+export SOLVAPAY_SECRET_KEY=sk_...
+```
+
+```python
+from solvapay import SolvaPay
+
+sv = SolvaPay()
+
+# Ensure customer exists
+customer_ref = sv.customers.ensure("user_alice")
+
+# Create checkout session
+session = sv.checkout.create_session(customer_ref=customer_ref, product_ref="prd_0QKI8NHF")
+print(session.checkout_url)
+
+# Check limits and track usage
+limits = sv.limits.check(customer_ref=customer_ref, product_ref="prd_0QKI8NHF")
+if limits.within_limits:
+    sv.usage.track(
+        customer_ref=customer_ref,
+        product_ref="prd_0QKI8NHF",
+        meter_name="requests",
+        units=1.0,
+        idempotency_key="req_abc123",   # idempotent — safe to retry
+    )
+```
+
+---
+
+## Stable API
+
+| Namespace | Sync | Async |
+|-----------|------|-------|
+| `sv.customers` | `ensure`, `get`, `update`, `balance` | `aensure`, `aget`, `aupdate`, `abalance` |
+| `sv.checkout` | `create_session` | `acreate_session` |
+| `sv.limits` | `check` | `acheck` |
+| `sv.purchases` | `cancel`, `reactivate` | `acancel`, `areactivate` |
+| `sv.usage` | `track` | `atrack` |
+| `sv.products` | `list`, `get`, `create`, `delete`, `clone` | `a` prefix on each |
+| `sv.plans` | `list`, `create`, `update`, `delete` | `a` prefix on each |
+| `sv.merchant` | `get`, `get_platform_config` | `aget`, `aget_platform_config` |
+
+---
+
+## Idempotency
+
+All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys from request content:
+
+```python
+from solvapay.idempotency import from_payload
+
+key = from_payload("track_usage", customer_ref, product_ref, "requests", units)
+sv.usage.track(..., idempotency_key=key)   # retry-safe
+```
+
+Retried POSTs **must reuse the same key**. Key should change only when the logical request changes.
+
+---
+
+## Errors and retries
+
+```python
+from solvapay import (
+    AuthenticationError, PermissionError, NotFoundError,
+    RateLimitError, InvalidRequestError, APIServerError,
+    APIConnectionError, APITimeoutError, SolvaPayError,
+)
+
+try:
+    sv.customers.ensure("cus_123")
+except AuthenticationError:
+    ...  # 401 — bad key
+except RateLimitError as e:
+    ...  # 429 — retry after e.retry_after seconds
+except APIConnectionError:
+    ...  # network failure
+except APITimeoutError:
+    ...  # request timed out (default 30s)
+except SolvaPayError as e:
+    ...  # catch-all
+```
+
+No built-in retries by design. Layer `tenacity` manually. `solvapay[retry]` RetryTransport ships in v0.9.
+
+---
+
+## Webhooks
+
+```python
+import os
+from solvapay.webhooks import WebhookPipeline
+
+pipeline = WebhookPipeline(
+    [os.environ["SOLVAPAY_WEBHOOK_SECRET"]],
+    max_clock_skew_seconds=300,
+    replay_ttl_seconds=600,
+)
+
+envelope = pipeline.process(body=request.body, signature=request.headers["sv-signature"])
+```
+
+**Typed events** — discriminated union over 13 event types:
+
+```python
+from solvapay import WebhookEvent, PurchaseCreated, PaymentSucceeded
+from pydantic import TypeAdapter
+
+event = TypeAdapter(WebhookEvent).validate_python(envelope.event)
+
+match event:
+    case PurchaseCreated():
+        print(f"New purchase: {event.data['purchaseRef']}")
+    case PaymentSucceeded():
+        print(f"Payment: {event.data['amount']}")
+```
+
+---
+
+## Paywall decorator
+
+```python
+from solvapay.paywall import require, PaywallRequired
+
+@require(product="prd_0QKI8NHF", client=sv)
+def run_query(*, customer_ref: str, query: str) -> str:
+    return expensive_query(query)
+
+try:
+    result = run_query(customer_ref="cus_123", query="hello")
+except PaywallRequired as e:
+    print(f"Upgrade at: {e.checkout_url}")
+    if e.checkout_mint_error:
+        print(f"Could not auto-mint checkout URL: {e.checkout_mint_error}")
+```
+
+Async version: `@require_async`. For MCP/LangChain: `@payable_tool` (see above).
+
+---
+
+## Async
+
+`AsyncSolvaPay` is the supported async pattern. Always use `async with` — it guarantees `aclose()`:
+
+```python
+from solvapay import AsyncSolvaPay
+
+async with AsyncSolvaPay() as sv:
+    customer_ref = await sv.customers.aensure("user_alice")
+    limits = await sv.limits.acheck(customer_ref=customer_ref, product_ref="prd_0QKI8NHF")
+    if limits.within_limits:
+        await sv.usage.atrack(
+            customer_ref=customer_ref,
+            product_ref="prd_0QKI8NHF",
+            meter_name="requests",
+            units=1.0,
+        )
+```
+
+---
+
+## Migrating from v0.7.x
+
+Flat methods still work but emit `DeprecationWarning`. Removed in v2.0.
+
+| v0.7.x | v0.8+ |
+|--------|-------|
+| `sv.ensure_customer(ref)` | `sv.customers.ensure(ref)` |
+| `sv.get_customer(ref)` | `sv.customers.get(ref)` |
+| `sv.check_limits(...)` | `sv.limits.check(...)` |
+| `sv.track_usage(...)` | `sv.usage.track(...)` |
+| `sv.create_checkout_session(...)` | `sv.checkout.create_session(...)` |
+| `sv.cancel_purchase(ref)` | `sv.purchases.cancel(ref)` |
+| `sv.reactivate_purchase(ref)` | `sv.purchases.reactivate(ref)` |
+| `sv.get_customer_balance(ref)` | `sv.customers.balance(ref)` |
+| `sv.list_products()` | `sv.products.list()` |
+| `sv.create_plan(prd, ...)` | `sv.plans.create(prd, ...)` |
+| `sv.get_merchant()` | `sv.merchant.get()` |
+
+---
+
+## Installation
+
+```bash
+pip install solvapay-python                   # core
+pip install 'solvapay-python[mcp]'            # + FastMCP adapter (FastMCP ≥0.4)
+pip install 'solvapay-python[langchain]'      # + LangChain adapter (langchain-core ≥0.3)
+pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
+```
+
+## Environment variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SOLVAPAY_SECRET_KEY` | Yes | — |
+| `SOLVAPAY_API_BASE_URL` | No | `https://api.solvapay.com` |
+| `SOLVAPAY_WEBHOOK_SECRET` | For webhooks | — |
+
+---
+
+## Examples
+
+| Path | What |
+|------|------|
+| `examples/multi-framework-paywall/` | One `@payable_tool` → FastMCP + LangChain + raw async |
+| `examples/marketplace/` | Streamlit AI-agent marketplace — real SolvaPay sandbox + Gemini LLM |
+| `examples/fastmcp-paywall/` | FastMCP server gated by `@paywall.require` |
+| `examples/langchain-paywall/` | LangChain agent with `monetize_tool` |
+
+---
+
+## Roadmap
+
+| Version | Theme |
+|---------|-------|
+| v0.8 ✅ | V1 architecture spine — Transport kernel, OpSpec registry, paywall/webhook packages, `@payable_tool`, stability manifest, layer DAG CI gate |
+| v0.9 | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, contract tests, lint automation, doc site (MkDocs Material), supply-chain hygiene |
+| v1.0 | Gated on founder signal — OpenAPI-generated models, full secret rotation, production hardening |
+
+---
+
+## Status
+
+**v0.8.0** — V1 architecture spine + AI-agent moat. `mypy --strict` clean (43 files). 261 tests. 89% line coverage.  
+Community SDK, not official. Proposal: [solvapay/solvapay-sdk#187](https://github.com/solvapay/solvapay-sdk/issues/187).