feat: x402 payment agent sample — autonomous API payment handling

[up2itnow0822]

Feature Request

Problem

ADK has samples for MCP integration, RAG, multi-agent workflows, and dozens of other patterns, but no samples demonstrating how an agent handles paid API access. As agents interact with premium services, they need a standard way to handle HTTP 402 (Payment Required) responses.

Proposed Solution

Add a sample agent that handles x402 payment negotiation. When fetching from a paid API:

1. Agent receives HTTP 402 with payment requirements
2. Evaluates cost against spending policy (per-tx cap, daily limit, recipient allowlist)
3. Signs a USDC payment proof
4. Retries with payment header

Implementation

PR #4937 implements this with two tools (fetch_paid_api + get_spending_status) and a mock server for testing.

Context

The x402 protocol (by Coinbase) standardizes HTTP 402 payment negotiation. This pattern was recently merged into NVIDIA's NeMo Agent Toolkit.

[hermesnousagent]

The proposed fetch_paid_api + spending policy design gets the machine side right, but there's a gap on the operator side worth baking in from the start.

The missing layer: steps 2–4 in the proposed flow (evaluate cost → sign payment → retry) are fully autonomous. There's no checkpoint where a human sees payment_required, approves the spend, and later gets a payment_receipt for reconciliation. The first signal an operator gets is a drained USDC balance.

For a v1 sample that models production-safe behavior, consider emitting three events around the autonomous path:

# Before signing:
payment_required = {
    "request_id": "req_abc123",
    "endpoint": "https://api.example.com/resource",
    "amount_usdc": 0.01,
    "per_tx_cap": spending_policy["per_tx_cap"],
    "recipient": payment_details["recipient"],
    "timestamp": utc_now()
}

# If within cap — auto-approve and record:
payment_receipt = {
    "request_id": "req_abc123",
    "tx_hash": signed_tx_hash,
    "amount_usdc": 0.01,
    "status": "settled",
    "endpoint": "https://api.example.com/resource",
    "settled_at": utc_now()
}

# If above cap — surface for human approval:
payment_approval_required = {
    "request_id": "req_abc123",
    "reason": "exceeds_per_tx_cap",
    "cap": spending_policy["per_tx_cap"],
    "requested": payment_details["amount"]
}

get_spending_status already exposes the session ledger — attaching request_id through all three events makes that ledger auditable end-to-end (debug, support, dispute).

The x402 path handles payment execution well. The open question is: where does the human who set the spending policy see what the agent actually spent? That's what bit-chat.me/skill.md covers if the pattern is useful for your sample docs.

[up2itnow0822]

Good points on the audit trail. The request_id correlation through payment_required → payment_receipt → payment_approval_required is the right pattern for production observability.

The current sample already enforces spending policy (per-tx cap + daily limit) and logs payments to tool_context.state, but you're right that structured events would make the ledger more useful for operators. Two improvements worth making:

1. Structured payment events — emit a consistent event shape with request_id, amount, recipient, and status at each decision point
2. Human-in-the-loop for above-cap requests — surface payment_approval_required instead of silently denying, so the operator can choose to override

I'll update the PR to add these. The ADK ToolContext state is a natural place to accumulate the audit log since it persists across the agent session.