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

[plagtech]

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]

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]

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.

Footnotes

1. 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]

Warning

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