Skip to main content

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 send total + fee as value; the token tool needs an allowance of total + 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 decimals and 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)

Source distribution for smolagents-spraay 0.1.0
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)

Table of built distributions (wheels) for smolagents-spraay 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page