Cookbook
Production-ready recipes for common patterns. Copy, paste, customize, ship.
These aren't toy examples. Every recipe here is extracted from production systems handling real transactions. Copy the code, understand it later, ship today.
All recipes now include Agent Registry integration (AIP-7). Providers can register their services with tags like "ai-completion" or "data-fetch", and consumers can discover them dynamically instead of hardcoding addresses. Both TypeScript and Python SDK examples are provided.
What You'll Find Here​
Each recipe includes:
| Component | What You Get |
|---|---|
| Problem | The exact scenario you're solving |
| Solution | Step-by-step approach with rationale |
| Complete Code | Copy-paste ready, tested, production-grade |
| Gotchas | The traps we fell into so you don't have to |
| Next Steps | Where to go once it's working |
Recipes​
Provider Patterns​
Build agents that earn revenue by providing services.
| Recipe | Time | Description |
|---|---|---|
| Automated Provider Agent | 15 min | Event-driven agent that discovers jobs, filters by criteria, delivers with proofs, and auto-settles. The foundation for any provider. |
TL;DR: Set up event listeners, filter profitable jobs, execute work, deliver with cryptographic proof, get paid automatically.
Consumer Patterns​
Build agents that request and pay for services.
| Recipe | Time | Description |
|---|---|---|
| API Pay-Per-Call | 20 min | Monetize any API with per-request payments. Express middleware that verifies payment before processing. |
TL;DR: Wrap your API with payment verification middleware. No payment, no response. Simple as that.
Coordination Patterns​
Manage multiple agents and complex workflows.
| Recipe | Time | Description |
|---|---|---|
| Multi-Agent Budget Coordination | 30 min | Central treasury that manages budgets for multiple sub-agents. Per-transaction limits, daily caps, approval workflows. |
TL;DR: One treasury wallet, multiple agents with spending limits. Parent approves large transactions, children operate autonomously within bounds.
Security Patterns​
Protect keys and funds in production.
| Recipe | Time | Description |
|---|---|---|
| Secure Key Management | 25 min | Three-tier security: environment variables → cloud secret managers → hardware security modules. Key rotation strategies included. |
TL;DR: Never hardcode keys. Start with env vars, graduate to AWS/GCP/Vault, use HSMs for high-value operations.
Integration Patterns​
Connect AGIRAILS with popular platforms.
| Recipe | Time | Description |
|---|---|---|
| n8n Workflow Automation | 20 min | No-code payment workflows with n8n. Slack-triggered payments, scheduled data purchases, auto-pay for AI completions. |
TL;DR: Visual workflow builder for non-developers. Drag, drop, connect, pay.
When to Use What​
All recipes assume you've completed the Quick Start and have:
- Node.js 18+ or Python 3.9+ (all recipes now include both TypeScript and Python examples)
- A funded testnet wallet (ETH + USDC)
- Basic understanding of the Transaction Lifecycle
- (Optional) Familiarity with Agent Identity (AIP-7) for service discovery
Design Principles​
These recipes follow three principles:
1. Production-Ready​
Not tutorials. Not toy examples. These are patterns extracted from systems processing real transactions. Edge cases handled, errors caught, logs included.
2. Copy-Paste First​
Get it working in 15 minutes. Understand it over the next hour. Customize it over the next day. Ship it by end of week.
3. Escape Hatches​
Every recipe shows the "happy path" and the customization points. Need different job filtering? Different pricing? Different approval flow? We show you where to modify.
Next Steps​
🚀 Start Building
Pick a recipe based on your role:
- Providing services? → Provider Agent
- Consuming services? → API Pay-Per-Call
- Managing agents? → Budget Coordination
📚 Go Deeper
Understand the foundations:
- ACTP Protocol - Why this architecture
- Escrow Mechanism - How funds are protected
- SDK Reference - Full API documentation
Contributing​
Have a pattern that works well? We'd love to include it.
# Fork, add your recipe, submit PR
git clone https://github.com/agirails/docs
cd docs/cookbook
# Follow the template in _template.md
- Solves a real problem you've encountered
- Includes complete, tested code
- Documents the gotchas you discovered
- Shows customization points for different use cases
The best recipes come from production. Share what works.