aifinpay-gate 0.1.0__tar.gz

aifinpay_gate-0.1.0/LICENSE

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

aifinpay_gate-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: aifinpay-gate
+Version: 0.1.0
+Summary: Accept AIFP-1 payments from AI agents in a Python API — ASGI (FastAPI, Starlette) and WSGI (Flask, Django) middleware. Port of @aifinpay/gate.
+Author-email: "CoinSecurities (SECCO)" <contact@aifinpay.io>
+License-Expression: MIT
+Project-URL: Homepage, https://aifinpay.io
+Project-URL: Repository, https://github.com/AiFinPay/sdk
+Project-URL: Issues, https://github.com/AiFinPay/sdk/issues
+Keywords: ai-agents,agent-payments,http-402,paywall,fastapi,flask,asgi,wsgi,middleware,aifinpay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyNaCl>=1.5
+Provides-Extra: redis
+Requires-Dist: redis>=4.2; extra == "redis"
+Dynamic: license-file
+
+# aifinpay-gate (Python)
+
+Accept payments from AI agents in a Python API. When an agent calls a paid
+route without paying, the gate answers **HTTP 402** with everything it needs to
+buy a batch of calls; the agent settles on-chain from its own wallet (you
+receive 99%, AiFinPay 1%, non-custodial) and retries with an `AIFP-Receipt`.
+The gate verifies that receipt **locally** — an Ed25519 signature against the
+AiFinPay JWKS, no call to AiFinPay per request — and meters the batch.
+
+A port of [`@aifinpay/gate`](https://www.npmjs.com/package/@aifinpay/gate): the
+same 402 body, the same checks and the same refusal sentences, held to the Node
+package by recorded fixtures (`tests/test_parity.py`).
+
+```bash
+pip install aifinpay-gate            # PyNaCl is the only dependency
+pip install "aifinpay-gate[redis]"   # shared counters across processes
+```
+
+## Register
+
+```bash
+curl -s -X POST https://api.aifinpay.io/v1/merchants -H 'content-type: application/json' \
+  -d '{"name":"My API","pay_to":{"evm":"0xYourPayoutWallet"},"settlement_version":"1.4"}'
+```
+
+Keep `merchant_id` and the one-time `merchant_secret`, then claim the merchant
+at https://dash.aifinpay.io with the secret to see payments. One `pay_to.evm`
+receives on every EVM network.
+
+## FastAPI / Starlette (ASGI)
+
+```python
+from fastapi import FastAPI, Request
+from aifinpay_gate import AifpGateMiddleware, Gate, Route
+
+gate = Gate("mrch_…", routes=[
+    Route("/create", "premium", methods={"POST"}),   # $0.005 per call
+    Route("/api/*"),                                  # the section and everything under it
+])
+app = FastAPI()
+app.add_middleware(AifpGateMiddleware, gate=gate)
+
+@app.post("/create")
+async def create(request: Request):
+    paid = request.state.aifp      # {"agent", "receipt_id", "used", "remaining", ...}
+    return {"ok": True, "remaining": paid["remaining"]}
+```
+
+## Flask / Django (WSGI)
+
+```python
+from aifinpay_gate import AifpGateWSGI, Gate, Route
+
+app.wsgi_app = AifpGateWSGI(app.wsgi_app, Gate("mrch_…", routes=[Route("/api/*")]))
+# in a view: request.environ["aifp"]
+```
+
+Both adapters also serve `/.well-known/x402.json` so agents discover the paid
+routes before they hit one (`serve_discovery=False` to turn it off).
+
+## Any other framework
+
+```python
+from aifinpay_gate import Gate, SimpleRequest
+
+result = gate.decide(SimpleRequest(path, headers, method))
+if result is None:        # not a paid route
+    ...
+elif not result.ok:       # 402 / 403 / 503 — send result.status, result.headers, result.body as JSON
+    ...
+else:                     # paid: add result.headers to your response; result.aifp is the metering context
+    ...
+```
+
+## Routes
+
+`Route(pattern, tier="standard", weight=None, methods=None, paywall=True)`
+
+- `pattern` is exact, or ends in `/*` — `/api/*` covers `/api` and everything
+  under `/api/`. The longest matching pattern wins. This is the hosted
+  gateway's matcher; wildcards in the middle (`/backtest/*/bid`) are refused.
+- `tier`: `standard` $0.0005, `complex` $0.002, `premium` $0.005 per call
+  (weights 1, 4, 10 billing units). `weight` overrides the units per call.
+- `paywall=False` serves the route free and meters nothing.
+- Paths no route matches pass through untouched.
+
+`Gate(merchant_id, resource="/api/search", tier="complex")` is the single-mount
+form: every request handed to it is charged against that one resource.
+
+## Production: share the counters
+
+The default `MemoryStore` meters per process. Under gunicorn/uvicorn with
+several workers, or several pods, each gets a full copy of every batch — a
+200-unit batch serves up to 200 × workers calls. Use Redis:
+
+```python
+import redis
+from aifinpay_gate import Gate, RedisStore
+
+gate = Gate("mrch_…", routes=[...], store=RedisStore(redis.Redis.from_url(REDIS_URL)))
+```
+
+The store increments atomically and compares **after** the increment, so
+concurrent requests can never overspend a batch; the counter's TTL is set once
+and expires with the receipt.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `should_charge` | everyone pays | `known_ai_agent` for content sites: human browsers read free and never see a 402; self-identifying AI crawlers and anything speaking AIFP pay. A predicate that raises charges. |
+| `allow(ctx)` | — | Your veto after verification, before metering (a refused call costs nothing). Return `False` → 403. |
+| `on_store_error` | `"closed"` | `"open"` serves un-metered calls when the store is down (`AIFP-Meter: degraded`). |
+| `require_agent_match` | `False` | Refuse when `AIFP-Agent-Id` differs from the receipt subject (anti-accident, not anti-theft). |
+| `replay` | `"auto"` | Single-use receipts get a one-shot nonce check. |
+| `jwks` | fetched | Pin the key set and skip network I/O (redeploy on key rotation). |
+| `on_event(e)` | — | `402` / `serve` / `403` / `meter_error` events for your metrics. |
+| `refund_on_error` (adapters) | `False` | Give the units back when your handler answers 5xx. |
+
+## What it guarantees
+
+- Fails **closed**: if the JWKS cannot be reached, paid routes answer 503, never free.
+- Only EdDSA receipts from `https://api.aifinpay.io` with `aud` = your merchant id.
+- Only quota receipts are spendable; per-call billing receipts are refused.
+- An expired receipt gets a 402 (buy again), a wrong one a 403 with a reason.
+- Stricter than the Node gate in two places: a receipt without a numeric `exp`,
+  or without a usable `unit_quota`, is refused.
+
+Not included, on purpose: free allowances, daily caps and per-agent blocks live
+in the AiFinPay dashboard, so there is one source of truth for each rule.

aifinpay_gate-0.1.0/README.md

@@ -0,0 +1,130 @@
+# aifinpay-gate (Python)
+
+Accept payments from AI agents in a Python API. When an agent calls a paid
+route without paying, the gate answers **HTTP 402** with everything it needs to
+buy a batch of calls; the agent settles on-chain from its own wallet (you
+receive 99%, AiFinPay 1%, non-custodial) and retries with an `AIFP-Receipt`.
+The gate verifies that receipt **locally** — an Ed25519 signature against the
+AiFinPay JWKS, no call to AiFinPay per request — and meters the batch.
+
+A port of [`@aifinpay/gate`](https://www.npmjs.com/package/@aifinpay/gate): the
+same 402 body, the same checks and the same refusal sentences, held to the Node
+package by recorded fixtures (`tests/test_parity.py`).
+
+```bash
+pip install aifinpay-gate            # PyNaCl is the only dependency
+pip install "aifinpay-gate[redis]"   # shared counters across processes
+```
+
+## Register
+
+```bash
+curl -s -X POST https://api.aifinpay.io/v1/merchants -H 'content-type: application/json' \
+  -d '{"name":"My API","pay_to":{"evm":"0xYourPayoutWallet"},"settlement_version":"1.4"}'
+```
+
+Keep `merchant_id` and the one-time `merchant_secret`, then claim the merchant
+at https://dash.aifinpay.io with the secret to see payments. One `pay_to.evm`
+receives on every EVM network.
+
+## FastAPI / Starlette (ASGI)
+
+```python
+from fastapi import FastAPI, Request
+from aifinpay_gate import AifpGateMiddleware, Gate, Route
+
+gate = Gate("mrch_…", routes=[
+    Route("/create", "premium", methods={"POST"}),   # $0.005 per call
+    Route("/api/*"),                                  # the section and everything under it
+])
+app = FastAPI()
+app.add_middleware(AifpGateMiddleware, gate=gate)
+
+@app.post("/create")
+async def create(request: Request):
+    paid = request.state.aifp      # {"agent", "receipt_id", "used", "remaining", ...}
+    return {"ok": True, "remaining": paid["remaining"]}
+```
+
+## Flask / Django (WSGI)
+
+```python
+from aifinpay_gate import AifpGateWSGI, Gate, Route
+
+app.wsgi_app = AifpGateWSGI(app.wsgi_app, Gate("mrch_…", routes=[Route("/api/*")]))
+# in a view: request.environ["aifp"]
+```
+
+Both adapters also serve `/.well-known/x402.json` so agents discover the paid
+routes before they hit one (`serve_discovery=False` to turn it off).
+
+## Any other framework
+
+```python
+from aifinpay_gate import Gate, SimpleRequest
+
+result = gate.decide(SimpleRequest(path, headers, method))
+if result is None:        # not a paid route
+    ...
+elif not result.ok:       # 402 / 403 / 503 — send result.status, result.headers, result.body as JSON
+    ...
+else:                     # paid: add result.headers to your response; result.aifp is the metering context
+    ...
+```
+
+## Routes
+
+`Route(pattern, tier="standard", weight=None, methods=None, paywall=True)`
+
+- `pattern` is exact, or ends in `/*` — `/api/*` covers `/api` and everything
+  under `/api/`. The longest matching pattern wins. This is the hosted
+  gateway's matcher; wildcards in the middle (`/backtest/*/bid`) are refused.
+- `tier`: `standard` $0.0005, `complex` $0.002, `premium` $0.005 per call
+  (weights 1, 4, 10 billing units). `weight` overrides the units per call.
+- `paywall=False` serves the route free and meters nothing.
+- Paths no route matches pass through untouched.
+
+`Gate(merchant_id, resource="/api/search", tier="complex")` is the single-mount
+form: every request handed to it is charged against that one resource.
+
+## Production: share the counters
+
+The default `MemoryStore` meters per process. Under gunicorn/uvicorn with
+several workers, or several pods, each gets a full copy of every batch — a
+200-unit batch serves up to 200 × workers calls. Use Redis:
+
+```python
+import redis
+from aifinpay_gate import Gate, RedisStore
+
+gate = Gate("mrch_…", routes=[...], store=RedisStore(redis.Redis.from_url(REDIS_URL)))
+```
+
+The store increments atomically and compares **after** the increment, so
+concurrent requests can never overspend a batch; the counter's TTL is set once
+and expires with the receipt.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `should_charge` | everyone pays | `known_ai_agent` for content sites: human browsers read free and never see a 402; self-identifying AI crawlers and anything speaking AIFP pay. A predicate that raises charges. |
+| `allow(ctx)` | — | Your veto after verification, before metering (a refused call costs nothing). Return `False` → 403. |
+| `on_store_error` | `"closed"` | `"open"` serves un-metered calls when the store is down (`AIFP-Meter: degraded`). |
+| `require_agent_match` | `False` | Refuse when `AIFP-Agent-Id` differs from the receipt subject (anti-accident, not anti-theft). |
+| `replay` | `"auto"` | Single-use receipts get a one-shot nonce check. |
+| `jwks` | fetched | Pin the key set and skip network I/O (redeploy on key rotation). |
+| `on_event(e)` | — | `402` / `serve` / `403` / `meter_error` events for your metrics. |
+| `refund_on_error` (adapters) | `False` | Give the units back when your handler answers 5xx. |
+
+## What it guarantees
+
+- Fails **closed**: if the JWKS cannot be reached, paid routes answer 503, never free.
+- Only EdDSA receipts from `https://api.aifinpay.io` with `aud` = your merchant id.
+- Only quota receipts are spendable; per-call billing receipts are refused.
+- An expired receipt gets a 402 (buy again), a wrong one a 403 with a reason.
+- Stricter than the Node gate in two places: a receipt without a numeric `exp`,
+  or without a usable `unit_quota`, is refused.
+
+Not included, on purpose: free allowances, daily caps and per-agent blocks live
+in the AiFinPay dashboard, so there is one source of truth for each rule.

aifinpay_gate-0.1.0/aifinpay_gate/__init__.py

@@ -0,0 +1,36 @@
+"""AiFinPay gate for Python merchants — accept AIFP-1 payments from AI agents.
+
+A port of ``@aifinpay/gate``: the same 402 challenge, the same local EdDSA
+receipt verification against the AiFinPay JWKS, the same post-increment quota
+metering. See README.md.
+"""
+
+from .agents import AI_AGENT_UA_MARKERS, known_ai_agent
+from .asgi import AifpGateMiddleware
+from .challenge import build_challenge
+from .core import (
+    DETAIL_QUOTA_EXHAUSTED,
+    DETAIL_RECEIPT_EXPIRED,
+    DETAIL_VERIFY_FAILED,
+    HEADER_QUOTA_REMAINING,
+    Gate,
+    GateResult,
+    Route,
+    SimpleRequest,
+)
+from .discovery import build_discovery_document
+from .pricing import TIER_WEIGHTS, UNIT_PRICE_USD, min_requests_for_tier, unit_price_usd, weight_for_tier
+from .scope import pattern_covers, scope_covers
+from .stores import REDIS_INCRBY_SCRIPT, MemoryStore, RedisStore, StoreCapacityError
+from .verify import Verifier
+from .wsgi import AifpGateWSGI
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AI_AGENT_UA_MARKERS", "AifpGateMiddleware", "AifpGateWSGI", "DETAIL_QUOTA_EXHAUSTED", "DETAIL_RECEIPT_EXPIRED",
+    "DETAIL_VERIFY_FAILED", "Gate", "GateResult", "HEADER_QUOTA_REMAINING", "MemoryStore", "REDIS_INCRBY_SCRIPT",
+    "RedisStore", "Route", "SimpleRequest", "StoreCapacityError", "TIER_WEIGHTS", "UNIT_PRICE_USD", "Verifier",
+    "build_challenge", "build_discovery_document", "known_ai_agent", "min_requests_for_tier", "pattern_covers",
+    "scope_covers", "unit_price_usd", "weight_for_tier",
+]

aifinpay_gate-0.1.0/aifinpay_gate/agents.py

@@ -0,0 +1,30 @@
+"""Who is an AI agent — the default ``should_charge`` for content sites.
+
+A curated list of self-identifying crawlers plus one stronger signal: a
+request already speaking AIFP (AIFP-Receipt or AIFP-Agent-Id) is an agent by
+its own declaration. It is not stealth detection; a scraper with a browser
+User-Agent walks past it, as it walks past Cloudflare's classifier. Extend it:
+
+    should_charge=lambda req: known_ai_agent(req) or my_signal(req)
+"""
+
+AI_AGENT_UA_MARKERS = (
+    "gptbot", "oai-searchbot", "chatgpt-user",
+    "claudebot", "claude-web", "anthropic-ai",
+    "perplexitybot", "perplexity-user",
+    "ccbot", "bytespider", "google-extended", "applebot-extended",
+    "meta-externalagent", "facebookbot", "amazonbot",
+    "youbot", "diffbot", "timpibot", "omgilibot", "cohere-ai", "ai2bot", "mistralai",
+    "aifinpay-agent",
+    "headlesschrome", "phantomjs",
+)
+
+
+def known_ai_agent(req) -> bool:
+    # A paying agent must never be exempted by a human-looking User-Agent.
+    if req.header("AIFP-Receipt") or req.header("AIFP-Agent-Id"):
+        return True
+    ua = (req.header("user-agent") or "").lower()
+    if not ua:
+        return True  # no browser sends none; scripts do
+    return any(marker in ua for marker in AI_AGENT_UA_MARKERS)

aifinpay_gate-0.1.0/aifinpay_gate/asgi.py

@@ -0,0 +1,87 @@
+"""ASGI middleware — FastAPI, Starlette, Quart, Litestar, any ASGI app.
+
+    from aifinpay_gate import Gate, Route, AifpGateMiddleware
+    gate = Gate("mrch_…", routes=[Route("/create", "premium", methods={"POST"})])
+    app.add_middleware(AifpGateMiddleware, gate=gate)
+
+Paid calls reach the handler with the metering context in
+``request.state.aifp`` (Starlette) — i.e. ``scope["state"]["aifp"]``. A gate
+decision is always a response, never an exception: a 402 routed through an
+app's error handler would come out as a 500, and an agent cannot pay a 500.
+"""
+
+import asyncio
+import json
+from typing import Any, Dict, Optional
+
+from .core import Gate, GateResult
+from .discovery import DISCOVERY_PATH, build_discovery_document
+
+
+class _AsgiRequest:
+    def __init__(self, scope: Dict[str, Any]):
+        self.path = scope.get("path") or "/"
+        self.method = scope.get("method", "GET")
+        self._headers: Dict[str, str] = {}
+        for k, v in scope.get("headers") or []:
+            name = k.decode("latin-1").lower()
+            self._headers.setdefault(name, v.decode("latin-1"))
+
+    def header(self, name: str) -> Optional[str]:
+        return self._headers.get(name.lower())
+
+
+async def _send_json(send, status: int, headers: Dict[str, str], body: Any) -> None:
+    raw = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode()
+    hdrs = [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in headers.items() if k.lower() != "content-type"]
+    hdrs += [(b"content-type", b"application/json"), (b"content-length", str(len(raw)).encode())]
+    await send({"type": "http.response.start", "status": status, "headers": hdrs})
+    await send({"type": "http.response.body", "body": raw})
+
+
+class AifpGateMiddleware:
+    def __init__(self, app, gate: Gate, serve_discovery: bool = True, refund_on_error: bool = False):
+        self.app = app
+        self.gate = gate
+        self.serve_discovery = serve_discovery
+        self.refund_on_error = refund_on_error
+        self._discovery = build_discovery_document(gate.merchant_id, gate.discovery_resources(),
+                                                   gate.api_base or "https://api.aifinpay.io")
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            return await self.app(scope, receive, send)
+        req = _AsgiRequest(scope)
+        if self.serve_discovery and req.method == "GET" and req.path == DISCOVERY_PATH:
+            return await _send_json(send, 200, {"Cache-Control": "public, max-age=300"}, self._discovery)
+        # decide() may block on a JWKS fetch or a Redis round-trip; keep that
+        # off the event loop.
+        try:
+            result: Optional[GateResult] = await asyncio.get_running_loop().run_in_executor(
+                None, self.gate.decide, req
+            )
+        except Exception:  # noqa: BLE001 — a bug in this package, not a payment decision
+            if self.gate.on_store_error == "open":
+                return await self.app(scope, receive, send)
+            return await _send_json(send, 503, {}, {"error": "AIFP-503-METER",
+                                                    "detail": "payment gate unavailable — retry shortly"})
+        if result is None:
+            return await self.app(scope, receive, send)
+        if not result.ok:
+            return await _send_json(send, result.status, result.headers, result.body)
+
+        scope.setdefault("state", {})["aifp"] = result.aifp
+        extra = [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in result.headers.items()]
+        status_seen = {}
+
+        async def send_with_headers(message):
+            if message["type"] == "http.response.start":
+                status_seen["status"] = message.get("status", 200)
+                message = {**message, "headers": list(message.get("headers") or []) + extra}
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_with_headers)
+        finally:
+            if self.refund_on_error and status_seen.get("status", 500) >= 500:
+                self.gate.refund(result.aifp)

aifinpay_gate-0.1.0/aifinpay_gate/challenge.py

@@ -0,0 +1,62 @@
+"""The 402 body, key for key what @aifinpay/gate and the hosted gateway emit.
+
+It is the only documentation an agent gets before any relationship exists, so
+it carries the whole purchase path. tests/test_parity.py compares it with the
+Node package's output, byte for byte."""
+
+from typing import Any, Dict, Optional
+
+from .pricing import PROTOCOL_FEE_BPS, min_requests_for_tier, unit_price_usd
+
+DEFAULT_API_BASE = "https://api.aifinpay.io"
+DEFAULT_DETAIL = "Payment Required — prepay a batch of requests and retry with the AIFP-Receipt header"
+
+
+def build_challenge(
+    merchant_id: str,
+    resource: str,
+    tier: str,
+    weight: int,
+    detail: Optional[str] = None,
+    scope: Optional[str] = None,
+    unit_price: Optional[str] = None,
+    min_requests: Optional[int] = None,
+    api_base: Optional[str] = None,
+) -> Dict[str, Any]:
+    # Absolute on purpose: this gate runs on the merchant's host, so a relative
+    # "/v1/quote" would send the agent to the merchant's own server.
+    api = (api_base or DEFAULT_API_BASE).rstrip("/")
+    scope = scope or "exact"
+    requests_ = min_requests if min_requests is not None else min_requests_for_tier(tier)
+    return {
+        "error": "AIFP-402",
+        "detail": detail or DEFAULT_DETAIL,
+        "protocol": "AIFP-1",
+        "documentation_url": "https://github.com/AiFinPay/sdk/blob/main/AGENT-FLOW.md",
+        "instructions_url": "https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay/SKILL.md",
+        "merchant_instructions_url":
+            "https://raw.githubusercontent.com/AiFinPay/skill/main/agent/skills/aifinpay-merchant/SKILL.md",
+        "merchant_id": merchant_id,
+        "resource": resource,
+        "tier": tier,
+        "unit_weight": weight,
+        "unit_price_usd": unit_price or unit_price_usd(tier),
+        "min_requests": requests_,
+        "scope": scope,
+        "protocol_fee_bps": PROTOCOL_FEE_BPS,
+        "no_minimum_fee": True,
+        "settlement_terms_from":
+            f"POST {api}/v1/quote — returns accepted_chains, accepted_assets, amount, order_id and expiry",
+        "how_to_pay": [
+            f'POST {api}/v1/quote {{"merchant_id":"{merchant_id}","resource":"{resource}","tier":"{tier}",'
+            f'"scope":"{scope}","requests":{requests_},"payer":"<your wallet address>"}} — payer is required; '
+            "raise requests to buy more than the minimum batch; check amount, scope, expiry and payer before paying",
+            "settle the quoted batch on-chain from your own wallet (order_id = quote_id)",
+            f"POST {api}/v1/pay {{quote_id, chain, asset, tx_ref, payment_authorization}} + Idempotency-Key header "
+            "-> quota receipt (wallet-signature-v1). Keep the quote until you hold the receipt; on a timeout retry "
+            "with the same key and tx_ref — never pay again",
+            "retry this request with header: AIFP-Receipt: <receipt JWT>",
+        ],
+        "no_wallet": "npx @aifinpay/mcp init — creates or selects a local wallet; read instructions_url for supported "
+                     "clients and payment availability. Wallet setup alone does not enable settlement.",
+    }