StreamPay

• 

  System Architecture

• 

  Component Architecture

• 

  Stream Lifecycle State Machine

• 

  CI Pipeline

• 

  StreamPay SkillMD

• 

  Skill API

• 

  Demo Run

Inspiration

AI agents are hiring each other — for inference, compute, bandwidth, advisory sessions. But the existing Nanda Town payments layer only does one-shot transfers. You either pre-pay a flat amount (overbilling) or transfer nothing. Real-world metered billing needs streaming: pay per tick, stop anytime, never overpay.

What it does

StreamPay lets AI agents open rate-limited payment streams that drain one tick at a time, capped at a max total. Either party can close the stream instantly. Every operation is idempotent — retry the same call, get the same result. 7 adversarial validators prove the money adds up at all times. A live REST API serves it to any agent that can make HTTP calls.

How we built it

Phase 1 — Hardened the Nanda Town streaming payments plugin with idempotency-keyed mutations, typed errors, audit trails, and 18 Hypothesis property tests proving conservation and rate enforcement hold for arbitrary inputs.

Phase 2 — Wrapped the validated semantics in a FastAPI service hosted on Render, wrote a SKILL.md agents can read to discover and call the API, and registered it in the Nanda Town skills registry.

Challenges we ran into

The default in-memory transport in Nanda Town delivers at zero latency, which means network partition testing required careful trace analysis rather than real-time observation. Hypothesis property tests deadlocked early due to async event loop conflicts inside pytest-asyncio — solved by making the property helper fully async rather than using run_until_complete.

Accomplishments that we're proud of

18 Hypothesis property tests caught bugs that example-based tests never would — like a double-billing edge case when repeating the same tick, and a conservation violation when max_total exactly equals rate_per_tick. The Render service auto-deployed on push and registered in the skills registry via API call, all without touching a UI. The full build pipeline (ruff, pyright, pytest) passes 972 tests with zero type errors.

What we learned

Idempotency is not a nice-to-have — it's the difference between a ledger that silently corrupts on retry and one that shrugs off network problems. Stripe's API design patterns (typed errors, idempotency keys, audit trails) map directly to agent-to-agent payments and make the code more self-documenting than comments ever could.

What's next for StreamPay

Real Stripe integration — streams backed by actual payment intents. WebSocket push for real-time tick events. Persistent storage so streams survive restarts. A /simulate endpoint that replays any Nanda Town trace through the live API for regression testing. Multi-payee streams for royalty splits and revenue sharing.

Built With

• fastapi
• git
• githubactions
• hypothesis
• pydantic
• pyright
• pytest
• python3.12
• render
• ruff
• uv
• uvicorn