Skip to content

feat: Add Spraay batch payment tools example#1997

Open
plagtech wants to merge 1 commit intohuggingface:mainfrom
plagtech:feat/add-spraay-batch-payments-example
Open

feat: Add Spraay batch payment tools example#1997
plagtech wants to merge 1 commit intohuggingface:mainfrom
plagtech:feat/add-spraay-batch-payments-example

Conversation

@plagtech
Copy link
Copy Markdown

Spraay Batch Payment Tools

Adds an example demonstrating how to use the @tool decorator to create blockchain payment tools for smolagents.

What this example shows

  • Using the @tool decorator for real smart contract interactions
  • web3.py integration for Base L2 blockchain
  • 3 payment tools: equal ETH, equal token, variable ETH
  • Automatic ERC-20 token approval handling
  • CodeAgent with payment-specific tools

Use case

Batch payments for payroll, airdrops, DAO distributions, and grants. Up to 200 recipients per transaction with ~80% gas savings.

Dependencies

smolagents, web3

Contract: 0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC (Base mainnet)

@plagtech
Copy link
Copy Markdown
Author

plagtech commented Mar 6, 2026

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.

@up2itnow0822
Copy link
Copy Markdown

Batch payments are a great use case — especially for agents that need to distribute rewards or settle multiple micro-transactions from a single workflow.

One architectural consideration: the x402 protocol (HTTP 402 Payment Required) is emerging as the standard for agent-to-service payments, with Coinbase, Stripe, and Cloudflare all shipping implementations. It handles the single-call payment flow natively.

For batch scenarios like this, you'd want a SpendingPolicy layer that enforces per-batch and per-period caps — otherwise an agent loop can drain funds fast.

There's an open PR that implements the core x402 payment primitive for smolagents with built-in spend governance: #2123. The batch settlement pattern you're describing could compose nicely on top of that foundation.

Happy to discuss architecture if useful.

@plagtech
Copy link
Copy Markdown
Author

Batch payments are a great use case — especially for agents that need to distribute rewards or settle multiple micro-transactions from a single workflow.

One architectural consideration: the x402 protocol (HTTP 402 Payment Required) is emerging as the standard for agent-to-service payments, with Coinbase, Stripe, and Cloudflare all shipping implementations. It handles the single-call payment flow natively.

For batch scenarios like this, you'd want a SpendingPolicy layer that enforces per-batch and per-period caps — otherwise an agent loop can drain funds fast.

There's an open PR that implements the core x402 payment primitive for smolagents with built-in spend governance: #2123. The batch settlement pattern you're describing could compose nicely on top of that foundation.

Happy to discuss architecture if useful.

Thanks for the feedback. Looked at #2123 — the SpendingPolicy pattern aligns with what we enforce on the infrastructure side.

Spraay's Agent Wallet system handles spend limits on-chain via session keys on Base mainnet, so the policy enforcement happens at the contract level rather than in application code. The batch payment tools in this PR are the execution layer — multi-recipient settlement across ERC-20 tokens and native ETH through a single contract call.

These are different layers solving different problems. SpendingPolicy handles agent-side trust guardrails. Spraay handles on-chain batch execution, gas optimization, and multi-token settlement. An agent framework can use either or both depending on the use case.

Re: the x402 point — Spraay's gateway is already x402-native. The batch endpoint sits behind x402 payment middleware, so agents pay per-call to access it. That's how the protocol is designed to work.

docs.spraay.app | gateway.spraay.app

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants