x402aff 0.1.0__py3-none-any.whl

x402aff/__init__.py

@@ -0,0 +1,47 @@
+"""x402aff - builder-code affiliation for x402 sellers.
+
+Route each payment to a per-(seller, builder) 0xSplits split so the builder who
+drove it earns an enforced on-chain cut, with no ledger and no custody:
+
+    from x402aff import Affiliation
+
+    aff = Affiliation(app_code="bc_yourcode", seller_payout="0x…")
+
+    PaymentOption(..., pay_to=aff.pay_to)          # per-request split address
+    RouteConfig(..., extensions=aff.extensions)    # declares your `a`
+
+`Affiliation` is the whole integration; the submodules below are the pieces it
+sits on, importable directly if you need them (``from x402aff import payto``).
+
+Buyers stamping their own builder code want `BuilderCodeClientExtension` from
+``x402aff.buyer_client``; it is not re-exported here because it pulls in the
+x402 client SDK, which a seller does not need.
+
+Discovery (``monitor``, ``Affiliation.scan``/``pending``/``splits_payload``)
+needs the optional CDP extra: ``pip install 'x402aff[cdp]'``.
+"""
+from __future__ import annotations
+
+from .affiliation import Affiliation
+from .builder_code import (
+    AFFILIATION_MARKER,
+    declare_builder_code,
+    marked_service_codes,
+    normalize_service_codes,
+    parse_builder_code_suffix,
+)
+from .push_split import BUILDER_SHARE_BPS, USDC_BASE, predict_split_address
+from .resolver import BUILDER_CODES_REGISTRY
+
+__all__ = [
+    "Affiliation",
+    "AFFILIATION_MARKER",
+    "BUILDER_CODES_REGISTRY",
+    "BUILDER_SHARE_BPS",
+    "USDC_BASE",
+    "declare_builder_code",
+    "marked_service_codes",
+    "normalize_service_codes",
+    "parse_builder_code_suffix",
+    "predict_split_address",
+]

x402aff/affiliation.py

@@ -0,0 +1,275 @@
+"""One object that is the whole integration - declare, payTo, distribute.
+
+The x402aff kit's pieces (`builder_code`, `payto`, `split`, `push_split`, `distribute`,
+`monitor`) each do one job well, but wiring an x402 route means importing several
+and hand-rolling a ``payTo`` callback. This folds all of that behind a single
+configured object so the integration is a couple of lines.
+
+    from x402aff import Affiliation
+
+    aff = Affiliation(app_code="bc_yourcode", seller_payout="0x…")
+
+    # ── the x402 route: two attributes, no boilerplate ──
+    PaymentOption(scheme="exact", price="$0.02", network="eip155:8453",
+                  pay_to=aff.pay_to)        # ← was a ~15-line DynamicPayTo function
+    RouteConfig(..., extensions=aff.extensions)   # declares your `a`
+
+    # ── framework-agnostic (Flask/Django/etc.) if you're not using the callback ──
+    addr = aff.pay_to_for(request.headers)   # sync → the split address (or your wallet)
+
+    # ── the payout side ──
+    for s in aff.pending():                  # splits holding distributable funds
+        print(s.builder_code, s.distributable_units)
+    calls, balance = aff.release("bc_alice") # deploy (first use) + distribute calldata
+
+``aff.pay_to`` is a drop-in x402 ``DynamicPayTo`` callback: it pulls the builder
+code off the request, resolves the per-pair split, and - like everything here -
+**never raises**; any failure falls back to the seller wallet (unsplit, never a
+failed payment). The same object accepts a headers mapping or a raw code, so it
+works outside the x402 SDK too.
+
+Import is dependency-light (only the request-path modules). The payout helpers
+(`pending`/`scan`) import `monitor` lazily, so you only need `cdp-sdk` if you
+actually use CDP-index discovery.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from . import distribute, payto, push_split, resolver, split
+from .builder_code import AFFILIATION_MARKER, declare_builder_code
+
+log = logging.getLogger("affiliation")
+
+__all__ = ["Affiliation"]
+
+
+class Affiliation:
+    """Configured entry point for one seller: declare ``a``, route ``payTo`` to
+    the per-builder split, and release funds.
+
+    Parameters
+    ----------
+    app_code
+        Your app / resource-server code (the ``a`` you declare on the route).
+    seller_payout
+        Where your 90% (and every unattributed payment) is paid.
+    builder_share_bps
+        The builder's cut in basis points (``1000`` = 10%). ``None`` uses
+        ``X402_BUILDER_SHARE_BPS`` / the x402aff kit default.
+    rpc_url
+        Base RPC for the address/balance reads. ``None`` uses ``X402_BASE_RPC`` /
+        the public endpoint (which rate-limits - set a paid one in production).
+    """
+
+    #: The request header a buyer's client sets to name its builder.
+    HEADER = payto.BUILDER_CODE_HEADER
+
+    def __init__(
+        self,
+        app_code: str,
+        seller_payout: str,
+        *,
+        builder_share_bps: Optional[int] = None,
+        rpc_url: Optional[str] = None,
+    ) -> None:
+        if not app_code:
+            raise ValueError("app_code is required (your `a` code)")
+        if not seller_payout:
+            raise ValueError("seller_payout is required")
+        self.app_code = app_code
+        self.seller_payout = seller_payout
+        self.builder_share_bps = builder_share_bps
+        self.rpc_url = rpc_url
+        # Effective share, resolved once so payTo and monitoring never disagree.
+        self._share = (
+            push_split.BUILDER_SHARE_BPS
+            if builder_share_bps is None
+            else builder_share_bps
+        )
+        self._extensions: Optional[dict] = None
+
+    # ── request path ─────────────────────────────────────────────────────────
+
+    @property
+    def extensions(self) -> dict:
+        """The route ``extensions`` that declare your app code ``a``.
+
+        Merge into any extensions you already advertise:
+        ``{**my_extensions, **aff.extensions}``.
+        """
+        if self._extensions is None:
+            self._extensions = declare_builder_code(self.app_code)
+        return self._extensions
+
+    async def pay_to(self, ctx) -> str:
+        """Drop-in x402 ``DynamicPayTo`` callback → the ``payTo`` for this request.
+
+        Pass as ``PaymentOption(pay_to=aff.pay_to)``. Reads ``X-Builder-Code`` off
+        the request context and returns the per-pair split address, or the seller
+        wallet when there's no/unknown/​unresolvable code.
+        """
+        return self.resolve(ctx).address
+
+    def pay_to_for(self, source=None, *, code: Optional[str] = None) -> str:
+        """Sync ``payTo`` for a request - for stacks where you set it yourself.
+
+        ``source`` may be an x402 request context, a headers mapping (Flask/
+        Starlette/dict), or a raw code string. Or pass ``code=`` directly.
+        """
+        return self.resolve(source, code=code).address
+
+    def resolve(self, source=None, *, code: Optional[str] = None) -> payto.PayTo:
+        """Full ``PayTo`` (address + why) for a request. Never raises.
+
+        Logs a warning if resolution *failed* (vs. simply finding no builder) -
+        a spike there means the RPC is rate-limiting and builders are silently
+        losing their cut.
+        """
+        if code is None:
+            code = self._code_from(source)
+        pt = payto.payto_for_request(
+            code,
+            seller_payout=self.seller_payout,
+            builder_share_bps=self.builder_share_bps,
+            rpc_url=self.rpc_url,
+        )
+        if pt.error:
+            log.warning("payTo resolve failed for %r, unsplit: %s", code, pt.error)
+        return pt
+
+    def _code_from(self, source) -> Optional[str]:
+        """Pull a normalized builder code out of whatever the framework hands us."""
+        if source is None:
+            return None
+        if isinstance(source, str):
+            return split.primary_code(source)
+        # x402 request context: ctx.adapter.get_header(name)
+        adapter = getattr(source, "adapter", None)
+        if adapter is not None and hasattr(adapter, "get_header"):
+            raw = adapter.get_header(self.HEADER)
+            return payto.builder_code_from_headers({self.HEADER: raw} if raw else {})
+        # headers-like mapping (has .get): Flask/Starlette request.headers, dict, …
+        if hasattr(source, "get"):
+            return payto.builder_code_from_headers(source)
+        return None
+
+    @staticmethod
+    def clear_cache() -> None:
+        """Drop the memoized code→split-address cache (after a share change, or
+        to retry a resolve that failed on a rate-limited RPC)."""
+        payto.clear_cache()
+
+    # ── payout path ──────────────────────────────────────────────────────────
+
+    def balance(self, code: str) -> int:
+        """USDC base units currently sitting in this builder's split (0 if none)."""
+        pt = self.resolve(code=code)
+        if not pt.attributed:
+            return 0
+        return distribute.split_balance_units(pt.address, rpc_url=self.rpc_url)
+
+    def release(self, code: str, *, distributor: Optional[str] = None):
+        """Build the release calls + live balance for one builder's split.
+
+        Returns ``(calls, balance_units)`` - submit each ``(target, data)`` from
+        any funded Base account (skip when balance is 0). Permissionless.
+        """
+        pt = self.resolve(code=code)
+        return distribute.distribute_plan(
+            pt.plan, rpc_url=self.rpc_url, distributor=distributor
+        )
+
+    def scan(self, *, days: int = 90):
+        """Every builder who paid you and their split's balance (fullest first).
+
+        Needs ``cdp-sdk`` - discovery uses CDP's attribution index (no local
+        ledger). Returns ``monitor.SplitStatus`` rows.
+        """
+        from . import monitor  # lazy: only this path needs cdp_sql / cdp-sdk
+
+        codes = monitor.discover_builder_codes(self.app_code, days=days)
+        rows = [self._status_for(c) for c in codes]
+        rows.sort(key=lambda s: s.balance_units, reverse=True)
+        return rows
+
+    def pending(self, *, days: int = 90):
+        """The subset of :meth:`scan` whose splits hold distributable funds."""
+        return [s for s in self.scan(days=days) if s.needs_distribution]
+
+    def _status_for(self, code: str):
+        """One builder's split status at THIS facade's share (keeps the predicted
+        address consistent with what :meth:`pay_to` advertises)."""
+        from . import monitor
+
+        info = resolver.resolve(code, rpc_url=self.rpc_url or push_split.BASE_RPC)
+        payout = info.get("payout_address") if info.get("registered") else None
+        if not payout:
+            return monitor.SplitStatus(code, None, None, False, 0)
+        plan = split.build_split_plan(
+            self.seller_payout, payout, builder_code=code, builder_share_bps=self._share
+        )
+        addr, deployed = push_split.predict_split_address(plan, rpc_url=self.rpc_url)
+        bal = distribute.split_balance_units(addr, rpc_url=self.rpc_url)
+        return monitor.SplitStatus(code, payout, addr, deployed, bal)
+
+    def splits_payload(self, *, days: int = 90) -> dict:
+        """The claims-dashboard payload — every per-builder split for this seller,
+        ready to serialize to JSON. One reusable call behind a ``/splits`` route.
+
+        Each row carries the split address, its codes + share, live balance,
+        deployed state, and a permissionless ``[deploy?, distribute]`` claim.
+        Discovery is by our app code ``a`` (CDP); the claim is reconstructed from
+        the seller wallet THIS facade holds, so even undeployed splits build with
+        no guessing. The shared marker and any unregistered/​unresolvable builder
+        code are skipped.
+
+        No per-split payment count: the query that would produce one 400s on
+        the CDP SQL API (queries.sql #5b). #5c has a cheap count-only alternative.
+
+        Needs ``cdp-sdk`` (discovery) + a Base RPC (balances). Returns a dict:
+        ``{"configured": True, "marker": ..., "count": N, "splits": [...]}``.
+        """
+        from . import monitor  # lazy: only this path needs cdp_sql / cdp-sdk
+
+        codes = [
+            c for c in monitor.discover_builder_codes(self.app_code, days=days)
+            if c != AFFILIATION_MARKER
+        ]
+        splits = []
+        for code in codes:
+            pt = self.resolve(code=code)
+            if not pt.attributed:  # unregistered builder / no split for this pair
+                continue
+            # resolve() is memoized, so release() reuses it (one set of reads/code).
+            calls, balance = self.release(code)
+            splits.append({
+                "payTo": pt.address,
+                "sellerCode": self.app_code,
+                "builderCode": code,
+                "builderShareBps": self._share,
+                "balanceUnits": str(balance),
+                # deployed = no deploy leg needed (the split contract already exists).
+                "deployed": not any(c.step == "deploy_split" for c in calls),
+                "claimable": len(calls) > 0,
+                "calls": [{"step": c.step, "target": c.target, "data": c.data} for c in calls],
+            })
+
+        splits.sort(key=lambda s: int(s["balanceUnits"]), reverse=True)
+        return {
+            "configured": True,
+            "marker": AFFILIATION_MARKER,
+            "count": len(splits),
+            "splits": splits,
+        }
+
+
+if __name__ == "__main__":
+    # Offline-ish demo: no code → falls straight back to the seller (no network).
+    aff = Affiliation(app_code="bc_demo", seller_payout="0x2222222222222222222222222222222222222222")
+    print("extensions :", aff.extensions)
+    print("no code    → payTo", aff.pay_to_for(None), "(seller, unsplit)")
+    print("header dict → payTo", aff.pay_to_for({Affiliation.HEADER: ""}), "(empty, unsplit)")
+    print("\nlive: aff.pay_to_for('leap_wallet') resolves the split; "
+          "aff.pending() lists what's owed; aff.release(code) builds the payout.")

x402aff/builder_code.py

@@ -0,0 +1,185 @@
+"""Base Builder Code (ERC-8021 Schema 2) helpers for x402 - declare & decode.
+
+This is the one framework-agnostic, reusable piece of the whole affiliation
+system. It does two jobs and has no web framework or database dependency:
+
+  1. declare_builder_code(app_code)  - build the extension dict you attach to
+     your paid x402 route so every payment is stamped with YOUR app code ("a").
+  2. parse_builder_code_suffix(calldata) - decode the ERC-8021 suffix the
+     facilitator appended to a settlement transaction, so you can read back the
+     authoritative on-chain codes (most importantly "w", the facilitator wallet
+     code, which only exists after settlement).
+
+Plus two normalizers used to sanitize codes read off the wire before they touch
+a database.
+
+Why hand-rolled? The x402 *Python* SDK ships no builder-code module (TS/Go
+only), so the resource server has to build the declaration and decode the suffix
+itself. On TypeScript you'd use `@x402/extensions/builder-code` instead.
+
+Spec:  https://github.com/x402-foundation/x402/blob/main/specs/extensions/builder_code.md
+CDP:   https://docs.cdp.coinbase.com/x402/core-concepts/builder-codes
+
+The only third-party dependency is `cbor2`, and only for parse_builder_code_suffix
+(the on-chain decode path). Declaring a code needs no dependencies at all.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# Extension key, matching the x402 TS SDK (@x402/extensions/builder-code).
+BUILDER_CODE_KEY = "builder-code"
+
+# Every builder code (a / w / s) is 1-32 lowercase letters, digits, underscores.
+BUILDER_CODE_PATTERN = r"^[a-z0-9_]{1,32}$"
+
+# The SHARED marker code the kit's buyer extension appends as a SECOND `s` on
+# every payment, so kit-routed payments self-identify on-chain. Because it is the
+# same code across all kit installs, ONE query discovers every kit payment
+# ecosystem-wide - `WHERE builder_code = <marker>` in base.transaction_attributions
+# - with no split-address reconstruction, and it catches even UNDEPLOYED splits
+# (the marker is written at settle time, not at deploy). It rides alongside the
+# real builder code; the split always pays the PRIMARY (first) code, so the marker
+# never changes a payout, and it needs no registration (it is stamped and indexed
+# even when unregistered). It is HARDCODED and identical across every kit install -
+# that shared constant is exactly what makes one query discover them all, so it is
+# deliberately not configurable.
+AFFILIATION_MARKER = "x402aff"
+
+# ERC-8021 Schema 2 trailer (16 bytes) that closes every attribution suffix.
+# Read from the END of the settlement calldata, the suffix is laid out as:
+#   [cbor_data][suffix_data_length (2 bytes, big-endian)][schema_id = 0x02][marker (16 bytes)]
+ERC_8021_MARKER = bytes.fromhex("80218021802180218021802180218021")
+_SCHEMA_2_ID = 2
+
+# JSON Schema for the three ERC-8021 Schema 2 fields. Rides in the base64'd 402
+# header, so it is kept minimal.
+BUILDER_CODE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "a": {"type": "string", "pattern": BUILDER_CODE_PATTERN},  # app code (yours)
+        "w": {"type": "string", "pattern": BUILDER_CODE_PATTERN},  # facilitator wallet code
+        "s": {                                                     # service/referer code(s)
+            "type": "array",
+            "items": {"type": "string", "pattern": BUILDER_CODE_PATTERN},
+        },
+    },
+    "additionalProperties": False,
+}
+
+
+def normalize_builder_code(code: Any) -> str | None:
+    """Return ``code`` trimmed if it's a single valid builder code, else None.
+
+    Use it to sanitize a code read back off the wire (your declared ``a``, a
+    facilitator ``w``) before storing it. Never raises.
+    """
+    if not isinstance(code, str):
+        return None
+    code = code.strip()
+    return code if re.match(BUILDER_CODE_PATTERN, code) else None
+
+
+def normalize_service_codes(raw: Any) -> str | None:
+    """Normalize a submitted ``s`` field to a comma-joined string of codes.
+
+    The buyer's client extension sends ``s`` as a list (one entry per layered
+    client), but it can also arrive as a bare string. Returns the valid,
+    de-duplicated codes joined by ``,`` (order preserved), or None when empty -
+    ready to drop in a single TEXT/VARCHAR column. Invalid entries are dropped.
+    """
+    if raw is None:
+        return None
+    items = raw if isinstance(raw, (list, tuple)) else [raw]
+    valid: list[str] = []
+    for item in items:
+        code = normalize_builder_code(item)
+        if code and code not in valid:
+            valid.append(code)
+    return ",".join(valid) or None
+
+
+def marked_service_codes(code: str) -> list[str]:
+    """The buyer-side ``s`` codes to attach: your real builder ``code``, plus the
+    shared kit marker as a second entry.
+
+    ``buyer_client.BuilderCodeClientExtension`` applies this for you; reach for
+    this directly when you stamp ``s`` yourself - a different x402 client, the
+    official builder-code extension, or a hand-built extensions dict::
+
+        {"builder-code": {"info": {"s": marked_service_codes("bc_yourcode")}}}
+
+    The marker is dropped when it would duplicate ``code``. The split always pays
+    the PRIMARY (first) code, so this never changes a payout - it only makes the
+    payment discoverable (see queries.sql #5). Mirrors the TS
+    ``markedServiceCodes``.
+    """
+    return [code, AFFILIATION_MARKER] if AFFILIATION_MARKER != code else [code]
+
+
+def declare_builder_code(app_code: str) -> dict[str, Any]:
+    """Build the builder-code extension dict for your x402 route's `extensions`.
+
+    Returns ``{"builder-code": {"info": {"a": <app_code>}, "schema": ...}}``,
+    ready to merge into the route config you pass to the x402 middleware. This is
+    all it takes to declare your app code - the facilitator does the rest at
+    settlement. Raises ValueError if ``app_code`` is malformed.
+    """
+    code = (app_code or "").strip()
+    if not re.match(BUILDER_CODE_PATTERN, code):
+        raise ValueError(
+            f"builder code {code!r} must match {BUILDER_CODE_PATTERN} "
+            "(1-32 lowercase letters, digits, underscores)"
+        )
+    return {BUILDER_CODE_KEY: {"info": {"a": code}, "schema": BUILDER_CODE_SCHEMA}}
+
+
+def parse_builder_code_suffix(calldata: Any) -> dict[str, Any] | None:
+    """Decode the ERC-8021 Schema 2 builder-code suffix from settlement calldata.
+
+    The reverse of what the facilitator appends at settle time (the Python
+    equivalent of TS ``parseBuilderCodeSuffixFromCalldata``). Returns a dict with
+    whichever of ``a`` / ``w`` / ``s`` are present, or ``None`` when there is no
+    valid Schema 2 suffix - so it's safe to call on ANY transaction. Use it to
+    read the authoritative on-chain attribution off a settle tx - ``a`` / ``s``
+    and above all ``w`` (the facilitator wallet code), which only exists
+    post-settle.
+
+    ``calldata`` may be a hex string (``0x...``) or raw ``bytes``. Never raises.
+    """
+    try:
+        if isinstance(calldata, str):
+            data = bytes.fromhex(calldata[2:] if calldata.startswith("0x") else calldata)
+        else:
+            data = bytes(calldata)
+    except (ValueError, TypeError):
+        return None
+
+    # Need at least cbor(0+) + length(2) + schema(1) + marker(16); the marker and
+    # schema byte gate out any non-attributed transaction.
+    if len(data) < 19 or data[-16:] != ERC_8021_MARKER or data[-17] != _SCHEMA_2_ID:
+        return None
+
+    cbor_len = int.from_bytes(data[-19:-17], "big")
+    start = len(data) - 19 - cbor_len
+    if start < 0:
+        return None
+
+    # cbor2 is only needed on this decode path - import it lazily so declaring a
+    # code stays dependency-free.
+    try:
+        import cbor2
+
+        decoded = cbor2.loads(data[start : len(data) - 19])
+    except Exception:
+        return None
+
+    if not isinstance(decoded, dict):
+        return None
+    out: dict[str, Any] = {}
+    for key in ("a", "w", "s"):
+        val = decoded.get(key)
+        if val not in (None, "", []):
+            out[key] = val
+    return out or None

x402aff/buyer_client.py

@@ -0,0 +1,77 @@
+"""Buyer side: how a builder attaches their code to EARN on the runs they drive.
+
+This is the ONLY thing a builder (an app/agent that pays you on behalf of its
+users) has to do to get attributed and paid. They register a tiny client
+extension on the x402 client they pay with, and every payment then carries their
+code as ``s`` (the referer). No contract changes; the facilitator writes it
+on-chain at settlement.
+
+Get a code (format ^[a-z0-9_]{1,32}$) at base.dev → Settings → Builder Codes,
+then register the payout wallet you want the share sent to.
+
+--------------------------------------------------------------------------------
+Python - the x402 Python SDK has no builder-code module, but its client takes
+generic extensions and the resource server declares the "builder-code" key in
+its 402, so this matching extension fires and tags the code as `s`:
+
+Every payment also carries a fixed, SHARED kit marker as a second `s` (see
+`builder_code.AFFILIATION_MARKER`) so kit-routed payments self-identify on-chain:
+discovery across all sellers is then one query, `WHERE builder_code = <marker>`,
+with no reconstruction and undeployed splits included. The marker never affects a
+payout (the split pays the primary code, i.e. yours) and is hardcoded and shared
+across every install - not configurable, so kit payments always stay discoverable.
+"""
+from __future__ import annotations
+
+from .builder_code import marked_service_codes
+
+
+class BuilderCodeClientExtension:
+    """Stamp every payment from this client with your builder code as ``s``.
+
+    A hardcoded, shared kit marker (:data:`builder_code.AFFILIATION_MARKER`,
+    ``x402aff``) rides along as a SECOND ``s`` code so kit-routed payments are
+    discoverable on-chain with one query (``WHERE builder_code = 'x402aff'``). It
+    never changes a payout - the split always pays the PRIMARY (first) code, i.e.
+    *your* ``code`` - and is deliberately not configurable, so every kit payment
+    stays discoverable ecosystem-wide.
+    """
+
+    key = "builder-code"
+
+    def __init__(self, code: str):
+        self.code = code
+
+    def enrich_payment_payload(self, payload, payment_required):
+        # Always append the shared, hardcoded marker as a second `s` (never a
+        # duplicate of the real code), so the payment self-identifies on-chain.
+        codes = marked_service_codes(self.code)
+        exts = dict(payload.extensions or {})
+        exts["builder-code"] = {"info": {"s": codes}}
+        return payload.model_copy(update={"extensions": exts})
+
+
+# Usage - on the same x402ClientSync() you registered the payment scheme on:
+#
+#   client.register_extension(BuilderCodeClientExtension("bc_yourcode"))
+#   client.fetch("https://api.example.com/run", ...)   # now carries your code
+#
+# --------------------------------------------------------------------------------
+# TypeScript - use the official extension instead (npm install @x402/extensions):
+#
+#   import { x402Client } from "@x402/fetch";
+#   import { registerExactEvmScheme } from "@x402/evm/exact/client";
+#   import { BuilderCodeClientExtension } from "@x402/extensions/builder-code";
+#   import { privateKeyToAccount } from "viem/accounts";
+#
+#   const client = new x402Client();
+#   registerExactEvmScheme(client, {
+#     signer: privateKeyToAccount(process.env.X402_BUYER_PRIVATE_KEY),
+#   });
+#   client.registerExtension(new BuilderCodeClientExtension("bc_yourcode"));
+#   // every client.fetch(...) payment now carries your code as `s`
+#
+# --------------------------------------------------------------------------------
+# Verify (after a real Base-mainnet settlement): take the settle tx hash (from the
+# PAYMENT-RESPONSE header) and paste it into buildercode-checker.vercel.app - you
+# should see the resource server's `a`, the CDP facilitator's `w`, and your `s`.

x402aff/cdp_sql.py

@@ -0,0 +1,98 @@
+"""Thin client for the CDP SQL API - query Coinbase's decoded on-chain tables.
+
+This is the alternative to hitting a raw Base RPC and hand-parsing calldata: CDP
+already decodes builder-code attribution into queryable tables, so you can just
+ask SQL for it. See monitor.py for the affiliation use, and queries.sql for
+copy-paste queries you can run right now in the no-auth SQL Playground.
+
+  Endpoint : POST https://api.cdp.coinbase.com/platform/v2/data/query/run
+  Auth     : Authorization: Bearer <JWT>   (CDP API-key JWT, ~2 min expiry)
+  Body     : {"sql": "...", "cache": {"maxAgeMs": <int>}}
+  Response : {"result": [ {col: val, ...}, ... ], "schema": {...}}
+  Dialect  : ClickHouse (CoinbaSeQL). Read-only SELECT. Max 10k-char query,
+             50k-row result, 30s timeout.  https://docs.cdp.coinbase.com/data/sql-api
+
+No API key needed to explore: the SQL Playground at
+https://portal.cdp.coinbase.com/onchain-tools/sql-api runs the same queries in
+the browser. Only the programmatic path below needs a JWT.
+"""
+from __future__ import annotations
+
+import os
+
+import requests
+
+SQL_API_URL = "https://api.cdp.coinbase.com/platform/v2/data/query/run"
+_HOST = "api.cdp.coinbase.com"
+_PATH = "/platform/v2/data/query/run"
+
+
+def _bearer_token() -> str:
+    """Get a Bearer JWT for the SQL API.
+
+    Two ways, in order:
+      1. CDP_API_KEY_ID + CDP_API_KEY_SECRET set → mint a fresh JWT with the CDP
+         SDK (`pip install cdp-sdk`). This is the production path; JWTs expire in
+         ~2 min, so mint one per call.
+      2. CDP_JWT set → use it verbatim (handy for a quick test: generate one in
+         the portal or via the SDK and export it).
+
+    Get keys at https://portal.cdp.coinbase.com/api-keys.
+    """
+    key_id = os.environ.get("CDP_API_KEY_ID")
+    key_secret = os.environ.get("CDP_API_KEY_SECRET")
+    if key_id and key_secret:
+        # Exact helper from the CDP docs (docs.cdp.coinbase.com JWT authentication).
+        from cdp.auth.utils.jwt import JwtOptions, generate_jwt
+
+        return generate_jwt(JwtOptions(
+            api_key_id=key_id,
+            api_key_secret=key_secret,
+            request_method="POST",
+            request_host=_HOST,
+            request_path=_PATH,
+            expires_in=120,
+        ))
+    token = os.environ.get("CDP_JWT")
+    if token:
+        return token
+    raise RuntimeError(
+        "No CDP credentials. Set CDP_API_KEY_ID + CDP_API_KEY_SECRET (needs "
+        "`pip install cdp-sdk`), or set CDP_JWT to a pre-generated token. "
+        "Or just paste the SQL into the no-auth Playground (see queries.sql)."
+    )
+
+
+def run_query(sql: str, *, max_age_ms: int = 5000, timeout: float = 35.0) -> list[dict]:
+    """Run a read-only SQL query and return the rows (the ``result`` array).
+
+    ``max_age_ms`` lets the API serve a cached result when an identical query ran
+    within that window (up to 900_000ms / 15m) - cheaper for repeated scans (monitor.py).
+    """
+    resp = requests.post(
+        SQL_API_URL,
+        headers={
+            "Authorization": f"Bearer {_bearer_token()}",
+            "Content-Type": "application/json",
+        },
+        json={"sql": sql, "cache": {"maxAgeMs": max_age_ms}},
+        timeout=timeout,
+    )
+    # Surface the API's error BODY, not just the status - a 400 here is almost
+    # always a SQL error the body explains (raise_for_status drops it).
+    if not resp.ok:
+        raise RuntimeError(f"CDP SQL {resp.status_code}: {(resp.text or '')[:600]}")
+    return resp.json().get("result", [])
+
+
+def sql_in_list(values) -> str:
+    """Render a Python iterable of strings as a ClickHouse IN (...) list.
+
+    Values here are tx hashes (0x + 64 hex) or builder codes ([a-z0-9_]) - both
+    already constrained to safe characters - but we still hard-filter to those
+    charsets so nothing but a hash/code can reach the query string.
+    """
+    import re
+
+    safe = [v for v in values if isinstance(v, str) and re.match(r"^[0-9a-zA-Z_x]+$", v)]
+    return ", ".join("'" + v + "'" for v in safe)