feat(tools): add AgentPay x402 payment tools for ADK agents

[up2itnow0822]

Closes #107

Summary

• Adds AgentPay x402 payment tools for Google ADK agents
• Standalone package: agentpay-mcp on npm (patent pending)
• SDK: agentwallet-sdk
• Tools: fetch_paid_api, get_wallet_info, check_spend_limit, send_payment

Note: This PR was previously submitted to google/adk-python (PR #4937) and redirected here by reviewer @rohityan who recommended releasing as a standalone package.

What is AgentPay / x402?

x402 is an open protocol that revives HTTP's original 402 Payment Required status code for machine-to-machine micropayments. When an agent hits a paid API, the server returns HTTP 402 with payment details. The agent's wallet pays automatically on-chain and retries — zero manual intervention.

AgentPay is a non-custodial smart contract wallet system for AI agents:

• Wallet ownership represented by an NFT (no custodian holds funds)
• On-chain spend limits (per-transaction + daily) enforced by smart contract
• Runs on Base (live); multi-chain coming
• Patent pending

Tools Added

Tool	Description
fetch_paid_api	Fetch a URL; auto-pay any x402 HTTP 402 challenge and retry
get_wallet_info	Wallet address, USDC balance, spend limits, remaining allowance
check_spend_limit	Pre-check whether a payment is within on-chain limits
send_payment	Send USDC directly to an address within spend policy

Usage

from google.adk.agents import Agent
from google.adk_community.tools.agentpay import (
    fetch_paid_api,
    get_wallet_info,
    check_spend_limit,
    send_payment,
)

agent = Agent(
    model="gemini-2.0-flash",
    name="payment_agent",
    description="Agent that pays for API access autonomously via x402",
    tools=[fetch_paid_api, get_wallet_info, check_spend_limit, send_payment],
)

Requirements

npm install -g agentpay-mcp   # Node.js >= 18
export AGENTPAY_PRIVATE_KEY="0x..."

Implementation Notes

• Tools call the agentpay-mcp MCP server via stdio subprocess (standard MCP transport)
• No custodian; private key stays in the agent's environment
• Spend limits enforced on-chain before any transaction is signed
• Graceful errors when MCP server not installed or AGENTPAY_PRIVATE_KEY not set

Testing Plan

Unit tests mock subprocess.run and shutil.which to avoid requiring Node.js or a real wallet. Tests cover:

1. Missing AGENTPAY_PRIVATE_KEY → clear error for all 4 tools
2. Invalid inputs (zero/negative amounts, bad address format)
3. MCP server not installed (both binary and npx absent)
4. Subprocess exits non-zero → error propagated
5. Subprocess timeout (60s)
6. No tool response from MCP (only init response received)
7. JSON-RPC error response from MCP
8. Happy-path success for all 4 tools with well-formed MCP responses
9. fetch_paid_api with and without x402 payment
10. check_spend_limit — allowed and blocked cases
11. Module import / __all__ completeness

Pytest Results

============================= test session starts ==============================
platform darwin -- Python 3.12.9, pytest-9.0.2
collected 27 items

tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMissingPrivateKey::test_fetch_paid_api_missing_key PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMissingPrivateKey::test_get_wallet_info_missing_key PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMissingPrivateKey::test_check_spend_limit_missing_key PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMissingPrivateKey::test_send_payment_missing_key PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestInputValidation::test_check_spend_limit_zero_amount PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestInputValidation::test_check_spend_limit_negative_amount PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestInputValidation::test_send_payment_zero_amount PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestInputValidation::test_send_payment_negative_amount PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestInputValidation::test_send_payment_invalid_recipient PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestInputValidation::test_send_payment_empty_recipient PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMcpServerNotFound::test_fetch_paid_api_no_mcp PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMcpServerNotFound::test_get_wallet_info_no_mcp PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMcpServerNotFound::test_check_spend_limit_no_mcp PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMcpServerNotFound::test_send_payment_no_mcp PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestSubprocessFailure::test_fetch_paid_api_subprocess_error PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestSubprocessFailure::test_timeout PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestSubprocessFailure::test_no_response_from_mcp PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestMcpProtocolError::test_rpc_error_propagated PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_fetch_paid_api_success_no_payment PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_fetch_paid_api_success_with_payment PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_get_wallet_info_success PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_check_spend_limit_allowed PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_check_spend_limit_blocked PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_send_payment_success PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestHappyPath::test_fetch_paid_api_passes_method_and_headers PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestModuleImports::test_import_all_tools PASSED
tests/unittests/tools/agentpay/test_agentpay_tools.py::TestModuleImports::test_all_symbols_in_dunder_all PASSED

======================== 27 passed in 6.37s ========================

Links

• agentpay-mcp on npm
• agentwallet-sdk on npm
• x402 Protocol
• ADK Integrations page
• CLA signed

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[up2itnow0822]

CLA has been signed at https://cla.developers.google.com/ — please re-run the CLA check.