Skip to content

Commit 78a812e

Browse files
plagtechplagtech
committed
feat(spraay): add Spraay batch payment tools for Base
1 parent 0d10dd9 commit 78a812e

6 files changed

Lines changed: 1026 additions & 0 deletions

File tree

‎contributing/tools/spraay/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Spraay Batch Payment Tools for Google ADK
2+
3+
[Spraay](https://spraay.app) enables AI agents to batch-send ETH or ERC-20 tokens to up to 200 recipients in a single transaction on [Base](https://base.org), with ~80% gas savings compared to individual transfers.
4+
5+
## Overview
6+
7+
These tools allow any Google ADK agent to execute batch cryptocurrency payments on Base. Common use cases include:
8+
9+
- **Payroll**: Pay team members in ETH or stablecoins in one transaction
10+
- **Airdrops**: Distribute tokens to community members efficiently
11+
- **Bounties**: Send rewards to multiple contributors at once
12+
- **Revenue sharing**: Split payments across stakeholders
13+
14+
## Installation
15+
16+
```bash
17+
pip install google-adk-community web3
18+
```
19+
20+
## Quick Start
21+
22+
```python
23+
from google.adk.agents import Agent
24+
from google.adk_community.tools.spraay import (
25+
spraay_batch_eth,
26+
spraay_batch_token,
27+
spraay_batch_eth_variable,
28+
spraay_batch_token_variable,
29+
)
30+
31+
agent = Agent(
32+
name="payment_agent",
33+
model="gemini-2.5-flash",
34+
instruction="""You are a payment assistant that helps users send
35+
batch cryptocurrency payments on Base using Spraay. Always confirm
36+
recipient addresses and amounts before executing transactions.""",
37+
tools=[
38+
spraay_batch_eth,
39+
spraay_batch_token,
40+
spraay_batch_eth_variable,
41+
spraay_batch_token_variable,
42+
],
43+
)
44+
```
45+
46+
## Configuration
47+
48+
Set the following environment variables:
49+
50+
| Variable | Required | Description |
51+
|---|---|---|
52+
| `SPRAAY_PRIVATE_KEY` | Yes | Private key of the sending wallet |
53+
| `SPRAAY_RPC_URL` | No | Base RPC endpoint (default: `https://mainnet.base.org`) |
54+
| `SPRAAY_CONTRACT_ADDRESS` | No | Override Spraay contract address |
55+
56+
```bash
57+
export SPRAAY_PRIVATE_KEY="0x..."
58+
```
59+
60+
## Tools
61+
62+
### `spraay_batch_eth`
63+
64+
Send equal amounts of ETH to multiple recipients.
65+
66+
```python
67+
# Example: Send 0.01 ETH to 3 recipients
68+
result = spraay_batch_eth(
69+
recipients=["0xAddr1...", "0xAddr2...", "0xAddr3..."],
70+
amount_per_recipient_eth="0.01",
71+
)
72+
```
73+
74+
### `spraay_batch_token`
75+
76+
Send equal amounts of an ERC-20 token to multiple recipients. Handles token approval automatically.
77+
78+
```python
79+
# Example: Send 100 USDC to 3 recipients
80+
USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
81+
result = spraay_batch_token(
82+
token_address=USDC_BASE,
83+
recipients=["0xAddr1...", "0xAddr2...", "0xAddr3..."],
84+
amount_per_recipient="100",
85+
token_decimals=6, # USDC uses 6 decimals
86+
)
87+
```
88+
89+
### `spraay_batch_eth_variable`
90+
91+
Send different ETH amounts to each recipient.
92+
93+
```python
94+
# Example: Send variable amounts to 3 recipients
95+
result = spraay_batch_eth_variable(
96+
recipients=["0xAddr1...", "0xAddr2...", "0xAddr3..."],
97+
amounts_eth=["0.1", "0.25", "0.05"],
98+
)
99+
```
100+
101+
### `spraay_batch_token_variable`
102+
103+
Send different token amounts to each recipient.
104+
105+
```python
106+
# Example: Send variable USDC amounts to 3 recipients
107+
result = spraay_batch_token_variable(
108+
token_address=USDC_BASE,
109+
recipients=["0xAddr1...", "0xAddr2...", "0xAddr3..."],
110+
amounts=["100", "250.5", "75"],
111+
token_decimals=6,
112+
)
113+
```
114+
115+
## Protocol Details
116+
117+
- **Contract**: `0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC` on Base Mainnet
118+
- **Max recipients**: 200 per transaction
119+
- **Fee**: 0.3% protocol fee
120+
- **Gas savings**: ~80% compared to individual transfers
121+
- **Token support**: Any ERC-20 token on Base
122+
- **Website**: [spraay.app](https://spraay.app)
123+
- **Source**: [github.com/plagtech](https://github.com/plagtech)
124+
125+
## Running Tests
126+
127+
```bash
128+
pytest tests/unittests/tools/spraay/ -v
129+
```
130+
131+
## License
132+
133+
Apache 2.0 - See [LICENSE](../../LICENSE) for details.

‎src/google/adk_community/tools/spraay/__init__.py‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Spraay batch payment tools for Google ADK agents.
16+
17+
Spraay (https://spraay.app) enables AI agents to batch-send ETH or ERC-20
18+
tokens to up to 200 recipients in a single transaction on Base, with ~80%
19+
gas savings compared to individual transfers.
20+
21+
Tools:
22+
spraay_batch_eth: Send equal ETH to multiple recipients.
23+
spraay_batch_token: Send equal ERC-20 tokens to multiple recipients.
24+
spraay_batch_eth_variable: Send variable ETH amounts per recipient.
25+
spraay_batch_token_variable: Send variable token amounts per recipient.
26+
27+
Usage:
28+
from google.adk_community.tools.spraay import (
29+
spraay_batch_eth,
30+
spraay_batch_token,
31+
spraay_batch_eth_variable,
32+
spraay_batch_token_variable,
33+
)
34+
from google.adk.agents import Agent
35+
36+
agent = Agent(
37+
name="payment_agent",
38+
model="gemini-2.5-flash",
39+
tools=[
40+
spraay_batch_eth,
41+
spraay_batch_token,
42+
spraay_batch_eth_variable,
43+
spraay_batch_token_variable,
44+
],
45+
)
46+
"""
47+
48+
from google.adk_community.tools.spraay.spraay_tools import (
49+
spraay_batch_eth,
50+
spraay_batch_eth_variable,
51+
spraay_batch_token,
52+
spraay_batch_token_variable,
53+
)
54+
55+
__all__ = [
56+
"spraay_batch_eth",
57+
"spraay_batch_token",
58+
"spraay_batch_eth_variable",
59+
"spraay_batch_token_variable",
60+
]

‎src/google/adk_community/tools/spraay/constants.py‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Copyright 2025 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Constants for Spraay batch payment tools."""
16+
17+
# Spraay contract on Base Mainnet
18+
SPRAAY_CONTRACT_ADDRESS = "0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC"
19+
20+
# Base Mainnet chain configuration
21+
BASE_CHAIN_ID = 8453
22+
BASE_RPC_URL = "https://mainnet.base.org"
23+
24+
# Protocol fee: 0.3%
25+
SPRAAY_FEE_BPS = 30 # basis points
26+
27+
# Maximum recipients per transaction
28+
MAX_RECIPIENTS = 200
29+
30+
# ERC-20 max approval
31+
MAX_UINT256 = 2**256 - 1
32+
33+
# Spraay contract ABI (relevant functions only)
34+
SPRAAY_ABI = [
35+
{
36+
"inputs": [
37+
{"internalType": "address[]", "name": "_recipients", "type": "address[]"},
38+
{"internalType": "uint256", "name": "_amount", "type": "uint256"},
39+
],
40+
"name": "spraayETH",
41+
"outputs": [],
42+
"stateMutability": "payable",
43+
"type": "function",
44+
},
45+
{
46+
"inputs": [
47+
{"internalType": "address", "name": "_token", "type": "address"},
48+
{"internalType": "address[]", "name": "_recipients", "type": "address[]"},
49+
{"internalType": "uint256", "name": "_amount", "type": "uint256"},
50+
],
51+
"name": "spraayToken",
52+
"outputs": [],
53+
"stateMutability": "nonpayable",
54+
"type": "function",
55+
},
56+
{
57+
"inputs": [
58+
{"internalType": "address[]", "name": "_recipients", "type": "address[]"},
59+
{"internalType": "uint256[]", "name": "_amounts", "type": "uint256[]"},
60+
],
61+
"name": "spraayETHVariable",
62+
"outputs": [],
63+
"stateMutability": "payable",
64+
"type": "function",
65+
},
66+
{
67+
"inputs": [
68+
{"internalType": "address", "name": "_token", "type": "address"},
69+
{"internalType": "address[]", "name": "_recipients", "type": "address[]"},
70+
{"internalType": "uint256[]", "name": "_amounts", "type": "uint256[]"},
71+
],
72+
"name": "spraayTokenVariable",
73+
"outputs": [],
74+
"stateMutability": "nonpayable",
75+
"type": "function",
76+
},
77+
]
78+
79+
# ERC-20 approve ABI
80+
ERC20_APPROVE_ABI = [
81+
{
82+
"inputs": [
83+
{"internalType": "address", "name": "spender", "type": "address"},
84+
{"internalType": "uint256", "name": "amount", "type": "uint256"},
85+
],
86+
"name": "approve",
87+
"outputs": [{"internalType": "bool", "name": "", "type": "bool"}],
88+
"stateMutability": "nonpayable",
89+
"type": "function",
90+
},
91+
{
92+
"inputs": [
93+
{"internalType": "address", "name": "owner", "type": "address"},
94+
{"internalType": "address", "name": "spender", "type": "address"},
95+
],
96+
"name": "allowance",
97+
"outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
98+
"stateMutability": "view",
99+
"type": "function",
100+
},
101+
]

0 commit comments

Comments
 (0)