feat(x402): EIP-3009 "exact" signing helper for agent payments

[yakimoto]

What

Adds wave.x402 — the EIP-3009 "exact" scheme signing helper so a non-JS agent can pay a WAVE x402 facilitator (gateway.wave.online). It signs a USDC TransferWithAuthorization as EIP-712 typed data and builds the X-Payment header — the same flow the TS @wave-av/agent-money helper provides. Closes the last open piece of the facilitator GTM (#110) for Python.

from wave.x402 import sign_exact_authorization, encode_exact_payment_header
payload = sign_exact_authorization(
    private_key=PAYER_KEY, network="base",
    to=req["payTo"], value=req["maxAmountRequired"],
    valid_before=int(time.time()) + 600,
)
resp = httpx.get(url, headers={"X-Payment": encode_exact_payment_header("base", payload)})

Byte-for-byte compatible with the facilitator

The WAVE facilitator's /verify recovers the payer from this exact EIP-712 hash. To guarantee the Python signer matches the reference viem stack, this PR commits a canonical cross-language conformance vector (tests/fixtures/x402_exact_vector.json) — a fixed key + fixed nonce → exact signature + header, generated from viem — and asserts byte-identity in tests/test_x402.py.

Verified locally against viem for both networks:

network	signature
base	0xbb7a2113…a66c9171c
base-sepolia	0x2e8a2041…b0b7dedb01c

…and the base64 X-Payment header matches exactly. This vector is intended to be the shared fixture every future port (Go/Rust/Ruby) reproduces.

Changes

• wave/x402.py — NETWORKS (base + base-sepolia USDC EIP-712 domains: mainnet "USD Coin" vs Sepolia "USDC", both version "2"), random_nonce, get_network_config, sign_exact_authorization, encode_exact_payment_header. eth-account is lazy-imported, so importing the module is dependency-free; calling sign_* without the extra raises a clear ImportError.
• pyproject.toml — [project.optional-dependencies] x402 = ["eth-account>=0.10.0"].
• tests/ — the conformance fixture + 9 tests (sig/header byte-identity ×2 networks, payer derivation, int→string coercion, nonce format, from-mismatch + unsupported-network guards).
• wave/__init__.py — exports sign_exact_authorization + encode_exact_payment_header.

Notes

• The test key is the universally-published Hardhat account ci(F6): govern this public mirror — foundation-gate + CODEOWNERS #1 key (the same one already used in wave-gateway tests) — not a secret, never for real funds.
• Verification: 9/9 pytest ([x402,dev] extras), ruff check clean. (test_version/test_api_count in test_sdk_exports.py already fail on main — version drift 2.1.0 vs 2.0.0 and a Wave-class attr count — unrelated to this PR and not run in CI's ruff-only lint workflow.)

🤖 Generated with Claude Code

---

Note

Medium Risk
New payment-signing path handles private keys and must match facilitator EIP-712 bytes exactly; mistakes would break verification but scope is isolated to optional client signing, not server auth.

Overview
Adds client-side x402 "exact" payments for Python agents: a new wave.x402 module signs USDC EIP-3009 TransferWithAuthorization (EIP-712) and builds the base64 X-Payment header for the WAVE facilitator, mirroring @wave-av/agent-money for base and base-sepolia.

Signing is gated behind optional pip install "wave-sdk[x402]" (eth-account); the module imports without that extra and sign_exact_authorization raises a clear ImportError when signing is attempted. sign_exact_authorization and encode_exact_payment_header are re-exported from wave.

Conformance is locked with tests/fixtures/x402_exact_vector.json (fixed key/nonce → signature + header) and tests/test_x402.py asserts byte-identical output for both networks, plus guards for payer derivation, nonce format, and invalid network/from mismatches.

^{Reviewed by Cursor Bugbot for commit 4f99f8b. Configure here.}

---

Summary by cubic

Adds wave.x402 — an EIP-3009 “exact” signing helper to let non-JS agents pay the WAVE x402 facilitator by signing USDC TransferWithAuthorization and building the X-Payment header. Byte-for-byte compatible with WAVE’s reference TypeScript x402 signer for base and base-sepolia. Docs updated to remove private repo references.

• New Features

  • sign_exact_authorization produces an EIP-712 signature bound to the payer wallet.
  • encode_exact_payment_header builds the base64 X-Payment envelope.
  • random_nonce and get_network_config helpers; networks: base, base-sepolia.
  • Added a shared conformance vector and tests asserting exact signature/header matches.

• Dependencies

  • Optional extra: x402 = ["eth-account>=0.10.0"]. Install with: pip install "wave-sdk[x402]".

^{Written for commit edd663b. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: edd663b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Review limit reached

@yakimoto, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 7 minutes and 45 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2314ad60-54ee-4627-9d5a-dacc6a4c516e

📥 Commits

Reviewing files that changed from the base of the PR and between 2b6a6ee and edd663b.

📒 Files selected for processing (5)

• pyproject.toml
• tests/fixtures/x402_exact_vector.json
• tests/test_x402.py
• wave/__init__.py
• wave/x402.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/x402-exact-signing

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/x402-exact-signing

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	eth-account@​0.13.7

View full report

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Agent as Python Agent
    participant SDK as wave.x402
    participant Account as eth_account (optional)
    participant Facilitator as WAVE Facilitator (gateway.wave.online)
    participant USDC as USDC Contract (chain)

    Note over Agent,Facilitator: NEW: EIP-3009 "exact" scheme payment flow

    Agent->>SDK: sign_exact_authorization(private_key, network, to, value, valid_before)
    SDK->>SDK: Lazy import eth_account
    alt eth_account not installed
        SDK-->>Agent: Raise ImportError with install hint
    end
    SDK->>SDK: Resolve network config (base/base-sepolia)
    alt Unsupported network
        SDK-->>Agent: Raise ValueError
    end
    SDK->>SDK: Derive payer address from private key
    alt from_address mismatch
        SDK-->>Agent: Raise ValueError
    end
    SDK->>SDK: Generate or validate nonce (0x + 64 hex)
    SDK->>Account: encode_typed_data(domain, message_types, message_data)
    Account-->>SDK: Signable message hash
    SDK->>Account: sign_message(signable)
    Account-->>SDK: ECDSA signature (0x + 130 hex chars)
    SDK-->>Agent: { signature, authorization: { from, to, value, validAfter, validBefore, nonce } }

    Agent->>Agent: Call encode_exact_payment_header(network, payload)
    Agent->>SDK: encode_exact_payment_header(network, payload)
    SDK->>SDK: Build envelope: { x402Version: 1, scheme: "exact", network, payload }
    SDK->>SDK: base64(JSON.stringify(envelope))
    SDK-->>Agent: Base64-encoded X-Payment header string

    Agent->>Facilitator: GET resource_url (X-Payment: <base64 header>)
    Facilitator->>Facilitator: Decode header, verify EIP-712 signature
    Facilitator->>USDC: TransferWithAuthorization (on-chain pull)
    USDC-->>Facilitator: Transfer confirmed
    Facilitator-->>Agent: Resource access granted

    Note over Agent,Facilitator: Canonical conformance vectors (test suite)
    Agent->>SDK: sign_exact_authorization with fixed key/nonce
    SDK-->>Agent: Signature + header
    Agent->>Agent: Assert byte-identical to vector.json

Loading

_{Re-trigger cubic}