[Hackathon Feedback] Multiple blockchain settlements per single agent request — deferred batch settlement needed

[clriesco]

Problem

When using decorator-based integrations (Strands @requires_payment, LangChain @requires_payment), each tool call triggers an independent blockchain settlement. In agentic flows where the LLM invokes multiple tools per request, this causes severe performance degradation.

Current behavior

Each decorated tool independently performs the full x402 cycle:

User Request
  → tool_A → verify → execute → settle (blockchain write)
  → tool_B → verify → execute → settle (blockchain write)  
  → tool_C → verify → execute → settle (blockchain write)
  → Response to user

Performance impact

Metric	1 tool	3 tools	5 tools
Blockchain writes	1	3	5
Estimated added latency	~2-5s	~6-15s	~10-25s

Root cause

The @requires_payment decorator is stateless and isolated per tool. It has no awareness of the broader multi-tool execution, no shared context for credit accumulation, and calls settle_permissions() independently each time.

Desired behavior

User Request
  → tool_A → verify → execute → accumulate 1 credit
  → tool_B → verify → execute → accumulate 2 credits
  → tool_C → verify → execute → accumulate 1 credit
  → Single settlement: 4 credits (1 blockchain write)
  → Response to user

Proposed Solutions

1. Settlement session / accumulator — A SettlementSession context manager that decorators write to. Single settle_permissions() at the end.
2. settle="deferred" parameter — Option on @requires_payment to skip settlement and store credit count in tool context.
3. Agent-level decorator — @agent_requires_payment wrapping the entire agent, verify once + settle once.
4. Facilitator batch settlement API — New endpoint accepting an array of charges, single blockchain tx.
5. Verify-only mode + explicit settle — Decorators only verify; caller settles with total after execution.

Additional Context

• Reported at the March 2026 hackathon event
• For agents routinely invoking 3-5+ tools, settlement latency dominates total response time
• Proposals build(deps): bump jinja2 from 3.1.3 to 3.1.4 #2 and Create a Notebook that works as tutorial for payments-py library #5 are lowest effort (decorator parameter change)