feat(spraay): Add Spraay batch payment tools for Base by plagtech · Pull Request #95 · google/adk-python-community

plagtech · 2026-02-25T20:17:43Z

What

Adds Spraay batch payment tools to the ADK community tools collection, enabling any ADK agent to batch-send ETH or ERC-20 tokens to up to 200 recipients in a single transaction on Base.

Why

Batch payments are one of the most common onchain operations for DAOs, teams, and AI agents — payroll, airdrops, bounties, and reward distributions. Without batch support, agents must send individual transfers, which is slow and expensive. Spraay solves this with ~80% gas savings via a single contract call.

Tools Added

Tool	Description
`spraay_batch_eth`	Send equal ETH to multiple recipients
`spraay_batch_token`	Send equal ERC-20 tokens to multiple recipients
`spraay_batch_eth_variable`	Send variable ETH amounts per recipient
`spraay_batch_token_variable`	Send variable token amounts per recipient

Features

Up to 200 recipients per transaction
~80% gas savings vs individual transfers
Automatic token approval handling for ERC-20 transfers
0.3% protocol fee
Full input validation (address format, recipient limits, amount checks)
Comprehensive error handling with descriptive return values
Environment-based config (RPC URL, private key, contract address)

Usage

from google.adk.agents import Agent
from google.adk_community.tools.spraay import spraay_batch_eth, spraay_batch_token

agent = Agent(
    name="payment_agent",
    model="gemini-2.5-flash",
    tools=[spraay_batch_eth, spraay_batch_token],
)

Files

src/google/adk_community/tools/spraay/
├── __init__.py           # Public API exports
├── constants.py          # Contract addresses, ABI, chain config
└── spraay_tools.py       # Tool function implementations

tests/unittests/tools/spraay/
├── __init__.py
└── test_spraay_tools.py  # Unit tests

contributing/tools/spraay/
└── README.md             # Documentation and examples

Protocol

Contract: 0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC (Base Mainnet)
Website: spraay.app
Dependency: web3 (Python)

Testing

pytest tests/unittests/tools/spraay/ -v

Checklist

Followed CONTRIBUTING.md guidelines
Added unit tests
Added documentation (README.md)
Apache 2.0 license headers on all files
Tools follow ADK FunctionTool pattern (plain functions with type hints + docstrings)
No breaking changes to existing code

google-cla · 2026-02-25T20:17:54Z

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.

gemini-code-assist · 2026-02-25T20:18:01Z

Summary of Changes

Hello @plagtech, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request integrates the Spraay batch payment protocol into the Google ADK community tools, allowing AI agents to perform efficient and cost-effective batch transfers of ETH and ERC-20 tokens on the Base network. This functionality is crucial for common on-chain operations such as payroll, airdrops, and bounty distributions, offering substantial gas savings and simplifying complex multi-recipient transactions.

Highlights

New Batch Payment Tools: Introduced four new tools for batch ETH and ERC-20 token payments: spraay_batch_eth, spraay_batch_token, spraay_batch_eth_variable, and spraay_batch_token_variable.
Gas Efficiency: Enabled significant gas savings (~80%) for batch transactions on the Base network compared to individual transfers.
ERC-20 Token Handling: Implemented automatic token approval handling for ERC-20 transfers, streamlining the process for users.
Robustness and Validation: Incorporated full input validation for addresses and amounts, along with comprehensive error handling for reliable operation.
Configuration: Provided environment-based configuration options for RPC URL, private key, and contract address, enhancing flexibility.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

contributing/tools/spraay/README.md
- Added comprehensive documentation for the Spraay batch payment tools, including installation, quick start, configuration, tool descriptions, protocol details, testing instructions, and license information.
src/google/adk_community/tools/spraay/init.py
- Added initialization file to export the new Spraay batch payment tools, making them accessible as part of the ADK community tools.
src/google/adk_community/tools/spraay/constants.py
- Added constants for the Spraay contract address, Base chain configuration, protocol fee, maximum recipients, ERC-20 max approval value, and relevant ABIs for both Spraay and ERC-20 contracts.
src/google/adk_community/tools/spraay/spraay_tools.py
- Implemented the core logic for the Spraay batch payment tools, including functions for sending equal and variable amounts of ETH and ERC-20 tokens.
- Added helper functions for Web3 connection, account retrieval, contract address management, recipient validation, and protocol fee calculation.
tests/unittests/tools/spraay/init.py
- Added initialization file for the Spraay unit test module.
tests/unittests/tools/spraay/test_spraay_tools.py
- Added unit tests for recipient address validation, fee calculation, and error handling within the Spraay batch payment tools, ensuring robustness and correctness.

Activity

The pull request introduces a new feature by adding Spraay batch payment tools for the Base network.
New files have been added for the tool's implementation, constants, public API, documentation, and unit tests.
The author, plagtech, has provided a detailed description covering the 'What', 'Why', 'Tools Added', 'Features', 'Usage', 'Files', 'Protocol', 'Testing', and a comprehensive 'Checklist' for the changes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist · 2026-02-25T20:19:41Z

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

plagtech · 2026-03-06T20:33:49Z

Update — March 2026

Spraay x402 Gateway has expanded significantly since this PR was opened:

62 paid endpoints across 8 categories (up from 6):

AI Chat (200+ models via OpenRouter)
Batch Payments (200 recipients/tx)
DeFi (Uniswap V3 swaps)
Price Oracle / Gas / FX
Cross-chain Bridge (11 chains)
Payroll, Invoicing, Escrow
Wallet Analytics, AI Inference
NEW: GPU/Compute — image gen, video, LLMs, audio via Replicate ($0.05/call)
NEW: Search/RAG — web search, content extraction, Q&A via Tavily ($0.01-$0.02/call)
Communication (email, SMS, webhooks, XMTP)
Infrastructure (RPC, IPFS, cron, logging)
Identity (KYC, auth/SSO)
Compliance (audit trail, tax)

63-tool MCP server on Smithery: @plagtech/spraay-x402-mcp
Developer docs: https://docs.spraay.app
Gateway: https://gateway.spraay.app

All endpoints are x402-native — agents pay USDC per request on Base. No API keys, no accounts.

The Search/RAG primitive is especially relevant for ADK agents — web search, content extraction, and Q&A are core agent actions, now available pay-per-call via x402.

DeanChensj · 2026-05-05T06:08:03Z

@gemini-cli /review

github-actions · 2026-05-05T06:08:12Z

🤖 Hi @DeanChensj, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

github-actions

Great work on adding the Spraay batch payment tools! This is a very useful addition for the ADK community.

I've added a few specific comments regarding:

Using decimal.Decimal instead of float for token amount calculations to avoid precision issues.
Adding a gas buffer to prevent 'out of gas' errors.
Verifying the Chain ID before sending transactions.

One additional suggestion:

Please add web3 as an optional dependency in pyproject.toml (e.g., spraay = ["web3"]) so users can install it easily.

Overall, the code is well-structured and documented. Once these minor points are addressed, it should be ready for merge.

…D check, web3 optional dep

plagtech · 2026-05-05T15:36:29Z

Addressed all review feedback:

Switched float → decimal.Decimal for token amount calculations
Added 10% gas buffer on all estimate_gas calls
Added chain ID verification before sending transactions
Added web3 as optional dependency in pyproject.toml

DeanChensj · 2026-05-05T16:46:29Z

@gemini-cli /review

github-actions · 2026-05-05T16:46:45Z

🤖 Hi @DeanChensj, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

…ests for CI

DeanChensj · 2026-05-05T17:25:58Z

Hi @plagtech , could you also address the failing tests?

plagtech · 2026-05-05T17:33:51Z

Just pushed a fix — updated the tests to properly mock web3 and account for the new chain ID check. CI should be green on this commit.

plagtech · 2026-05-05T17:40:05Z

Pushed test fixes — all mocks now properly cover web3 imports so tests pass without web3 installed in CI. Also moved validation checks before the web3 import in _validate_recipients so empty list / max recipients checks work independently.
Note: the test_session_state_management failure in test_redis_session_service.py is a pre-existing issue in the repo, not related to this PR.

DeanChensj · 2026-05-05T19:00:40Z

FAILED tests/unittests/tools/spraay/test_spraay_tools.py::TestValidateRecipients::test_invalid_address - ImportError: web3 is required for Spraay tools. Install with: pip install web3
FAILED tests/unittests/tools/spraay/test_spraay_tools.py::TestValidateRecipients::test_valid_addresses - ImportError: web3 is required for Spraay tools. Install with: pip install web3

It seems these tests still depend on web3 library.

plagtech · 2026-05-05T19:47:35Z

FAILED tests/unittests/tools/spraay/test_spraay_tools.py::TestValidateRecipients::test_invalid_address - ImportError: web3 is required for Spraay tools. Install with: pip install web3
FAILED tests/unittests/tools/spraay/test_spraay_tools.py::TestValidateRecipients::test_valid_addresses - ImportError: web3 is required for Spraay tools. Install with: pip install web3

It seems these tests still depend on web3 library.

Fixed — test_valid_addresses and test_invalid_address now mock the web3 module at the import level using patch.dict(sys.modules) so they no longer depend on web3 being installed. Just pushed the update.

github-actions · 2026-05-05T20:26:02Z

🤖 Hi @DeanChensj, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

github-actions

Excellent work on these tools! The implementation is robust, follows ADK patterns, and properly handles common pitfalls in on-chain transactions (gas buffers, chain ID verification, precision with Decimal).

The author has proactively addressed all previous feedback. The code is well-structured and the documentation is comprehensive.

One minor suggestion: while the 10% gas buffer is a good default, for very large batch transactions or highly volatile gas environments, making this buffer configurable via an environment variable could be a useful future enhancement.

Overall, this is a high-quality contribution.

feat(spraay): add Spraay batch payment tools for Base

78a812e

plagtech mentioned this pull request Feb 25, 2026

docs: Add Spraay batch payment tools to third-party catalog google/adk-docs#1344

Closed

5 tasks

github-actions Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py

fix: address review feedback - Decimal precision, gas buffer, chain I…

435f4ff

…D check, web3 optional dep

github-actions Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py

Comment thread src/google/adk_community/tools/spraay/spraay_tools.py Outdated

fix: extract chain ID helper, wrap web3 import in _get_account, fix t…

b965b42

…ests for CI

fix: ensure tests pass without web3 installed in CI

f13f4ee

fix: properly mock web3 imports in tests for CI without web3

a917ed3

github-actions Bot approved these changes May 5, 2026

View reviewed changes

DeanChensj approved these changes May 5, 2026

View reviewed changes

DeanChensj merged commit 8172fd3 into google:main May 5, 2026
8 of 13 checks passed

Conversation

plagtech commented Feb 25, 2026

What

Why

Tools Added

Features

Usage

Files

Protocol

Testing

Checklist

Uh oh!

google-cla Bot commented Feb 25, 2026

Uh oh!

gemini-code-assist Bot commented Feb 25, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot commented Feb 25, 2026

Uh oh!

plagtech commented Mar 6, 2026

Update — March 2026

Uh oh!

DeanChensj commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

plagtech commented May 5, 2026

Uh oh!

DeanChensj commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DeanChensj commented May 5, 2026

Uh oh!

plagtech commented May 5, 2026

Uh oh!

plagtech commented May 5, 2026

Uh oh!

DeanChensj commented May 5, 2026

Uh oh!

plagtech commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants