smolagents-spraay
Spraay batch payment tools for smolagents. An agent can pay up to 200 recipients in a single transaction on Base through the Spraay batch contract.
| Tool | What it does | Contract function |
|---|---|---|
spraay_batch_send_eth |
Same ETH amount to every recipient | sprayEqual (token = zero address) |
spraay_batch_send_token |
Same ERC-20 amount (e.g. USDC) to every recipient | sprayEqual |
spraay_batch_send_eth_variable |
A different ETH amount per recipient | sprayETH |
Contract: 0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC on Base mainnet (chain 8453).
These tools move real funds. They sign transactions with the private key in
SPRAAY_PRIVATE_KEY. Use a dedicated wallet that holds only what you are willing to let an agent spend, and review what your agent is asked to do.
Install
pip install smolagents-spraay
Use
from smolagents import CodeAgent, InferenceClientModel
from smolagents_spraay import get_spraay_tools
agent = CodeAgent(tools=get_spraay_tools(), model=InferenceClientModel())
agent.run("Send 0.001 ETH to each of these addresses on Base: 0x..., 0x...")
Or call a tool directly:
from smolagents_spraay import SpraayBatchSendTokenTool
send = SpraayBatchSendTokenTool()
print(
send(
token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # USDC on Base
recipients=["0x...", "0x..."],
amount_each="25.5",
)
)
Configuration
| Variable | Required | Meaning |
|---|---|---|
SPRAAY_PRIVATE_KEY |
yes | Private key of the paying wallet |
SPRAAY_RPC_URL |
no | Base RPC endpoint. Default: https://mainnet.base.org |
Behaviour
- Fee. The protocol fee is read live from the contract's
feeBps()(currently 30 = 0.3%) and added on top of the total. ETH tools sendtotal + feeas value; the token tool needs an allowance oftotal + fee. - Approvals are exact. If the token allowance is too low, the tool approves exactly
total + fee, waits for that transaction to succeed, then sends the batch. It never sets an unlimited allowance. - Token decimals are read from the token contract. If you pass
decimalsand it disagrees with the chain, the tool refuses. - Amounts are decimal strings and are converted exactly. An amount with more decimal places than the asset supports is rejected, not rounded.
- Checks before sending. At most 200 recipients, every address validated (a mixed-case address with a wrong checksum is rejected as a likely typo), the RPC must report chain 8453, and gas is estimated before signing, so a batch that would revert fails before anything is broadcast.
- Return value. A status line with the Basescan link on success, or
Error: ....
Tests
pip install -e ".[dev]"
pytest # offline: validation, call building, Hub serialisation
pytest -m live # read-only checks against Base mainnet; no key, nothing is sent
The live suite confirms that every function in the bundled ABI exists in the deployed bytecode, and simulates the batch calls with eth_call.
Hugging Face Hub
Each tool class is self-contained, so it can be shared with Tool.push_to_hub and loaded with load_tool:
python scripts/push_to_hub.py --namespace <your-hf-username-or-org>
from smolagents import load_tool
send_eth = load_tool("<namespace>/spraay-batch-send-eth", trust_remote_code=True)
The script creates each Space as a static Space, which works on a free Hugging Face account, so the Spaces show a short info page instead of a Gradio demo. load_tool only needs tool.py and is unaffected.
Do not add a private key as a secret on the public Spaces this creates.
Development
src/smolagents_spraay/tools.py is generated. Hub tools must be self-contained classes, so the shared constants and helpers are stamped into each class from one template. Edit gen_tools.py, then run python gen_tools.py.
License
Apache-2.0
Metadata
Release files for smolagents-spraay 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| smolagents_spraay-0.1.0.tar.gz | 16.4 kB | Without provenance | Details for smolagents_spraay-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| smolagents_spraay-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for smolagents_spraay-0.1.0-py3-none-any.whl |
Total release size: 27.9 kB
Release files / smolagents_spraay-0.1.0.tar.gz
| Download URL | smolagents_spraay-0.1.0.tar.gz |
|---|---|
| Size | 16.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7076b96454a034410b9c7820e723c6d9b939d49187a655e1f0d3924504d4eb8b
|
|
BLAKE2b-256 checksum How to use checksums |
8274028dc1d365f833be221f53b48931a91414fb057999da6eb2c847708ee772
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / smolagents_spraay-0.1.0-py3-none-any.whl
| Download URL | smolagents_spraay-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeea715fd18f7ead4ebe2368fc7acf670cec5fbcc0606fd608a6f943207974a1
|
|
BLAKE2b-256 checksum How to use checksums |
8d4f0309dbbf88e240d2acbccb1f6faf19e340ce7a3b19ec0f56f4cd783539bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for smolagents-spraay 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.