Add A2A x402 adapter

[kingzzoov-ctrl]

Summary

Implements a dependency-free switchboard.adapters.a2a_x402 bridge for issue #29.

The adapter converts Switchboard payment envelopes to/from the standalone Google A2A x402 JSON metadata flow:

• to_a2a_request(offer: PaymentOffer) -> dict
  • emits an A2A message/send body with x402.payment.status: payment-required
  • includes an x402.payment.required response with PaymentRequirements
  • maps known Switchboard chain IDs to x402 networks (base, base-sepolia, sepolia, ethereum) and unknown chain IDs to eip155:<id>
• from_a2a_response(payload: dict) -> PaymentProof
  • accepts full JSON-RPC request bodies, A2A message objects, metadata dicts, or raw PaymentPayload objects
  • extracts payer, amount, nonce, network/chain ID, and transaction/signature reference into a Switchboard PaymentProof
• Adds docs/adapters/a2a-x402.md with an end-to-end usage example and supported network mapping
• Adds focused pytest coverage for request generation, response parsing, malformed payloads, network mapping, and transaction-reference precedence

Validation

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest tests/test_a2a_x402_adapter.py tests/test_x402_middleware.py -q
.venv/bin/python -m ruff check switchboard/adapters/a2a_x402.py tests/test_a2a_x402_adapter.py switchboard/x402_middleware.py
git diff --check

Result:

25 passed
All checks passed!

I also ran the full test suite with .venv/bin/python -m pytest -q: this branch has 64 passed, 1 skipped, and 6 failures in tests/test_nonce_manager.py. Those nonce-manager failures are outside the adapter scope and are not touched by this PR.

Note

While adding the adapter tests, importing switchboard.x402_middleware in an environment without optional aiohttp exposed an existing import-time annotation issue. I moved the optional dependency check to _get_session() so dataclasses and pure adapters can be imported without aiohttp, while actual HTTP usage still raises the same actionable ImportError.

Closes #29

[abhicris]

Welcome to kcolbchain, @kingzzoov-ctrl — glad you're here. 🌱

Here's what happens from this PR:

1. Our automated review looks for obvious issues (tests, secrets, size) within a couple of hours.
2. If it's clean and CI passes, we merge without back-and-forth.
3. If we need changes, we'll leave a specific comment — not a generic nit. Push another commit and we re-review.

While you wait:

• Run the repo's tests locally (see the repo README.md).
• Keep the PR scoped to one concern — bigger PRs land slower.
• Don't commit tokens or .env contents.

What happens after your first merge

• You're listed on https://kcolbchain.com/contributors/ (opt-out anytime via data/contributors-optout.txt).
• At 2+ merged PRs you're a Regular; at 5+ you're a Fellow — Fellows are the pool we invite first for paid research, partner-org gigs, and grant-funded work. Details: https://kcolbchain.com/docs/org-contribution-policy.html
• Looking for what to pick up next? https://kcolbchain.com/invitations/ lists open help-wanted / good-first-issue across every kcolbchain repo.

Thanks for writing the code. We're building this to last.

[abhicris]

🤖 Audit verdict: safe

Adapter adds A2A x402 protocol support through pure data transformation with no external dependencies, network calls, credential leakage, or malicious wallet/address manipulation.

Audited by the kcolbchain PR pipeline. See pipeline docs.

[abhicris]

Merged — thank you, @kingzzoov-ctrl. Your first kcolbchain contribution is in. 🎉

A few things that unlocked with this merge:

• You'll appear on https://kcolbchain.com/contributors/ on the next daily rebuild. Opt out anytime via data/contributors-optout.txt on the website repo.
• You're now a Newcomer in the ladder. At 2 merged PRs you're a Regular; at 5+ you're a Fellow — that's the pool we invite first for paid research, partner-org engagements, and grant milestones. Full policy: https://kcolbchain.com/docs/org-contribution-policy.html
• Looking for the next thing to pick up? https://kcolbchain.com/invitations/ is the live list of open help-wanted / good-first-issue across every kcolbchain repo, refreshed daily.

If you want to stay in the loop on what we're shipping: https://kcolbchain.com/ROADMAP.md