docs: add x402 usage-based settlement example and accounting guidance

[up2itnow0822]

Market signal

MoonPay's Open Wallet Standard launch explicitly positions OWS as the wallet layer that makes x402 and session-style machine payments usable across agent frameworks. At the same time, x402's upto scheme has made usage-based settlement a first-class agent-payment pattern.

Why it matters

OWS already has x402-related adoption pressure in the repo, but the missing piece is practical guidance for usage-based settlement after a max authorization is approved.

For agent builders, the hard part is no longer just signing the payment. It is explaining:

• the max amount that was authorized
• the actual amount that settled
• the remaining headroom or released capacity
• the wallet-visible accounting effects after settlement

Without a reference pattern here, every framework will invent its own local accounting story.

Recommended action

Add an official x402 usage-based billing example and guidance for upto-style settlement flows in OWS docs/examples.

Scope

Suggested deliverables:

1. A minimal example showing max authorization first, then actual settlement.
2. Guidance on what the wallet layer should expose locally after settlement (authorized amount, settled amount, released amount, net delta).
3. A note on how OWS should interoperate with app-layer accounting modules when settlement occurs after the original authorization step.
4. Optional: a reference integration example using an external accounting layer such as agentwallet-sdk's UptoBillingPolicy, which already models max-authorize / actual-settle / release flows.

Non-scope

• Standardizing all downstream accounting formats.
• Replacing existing x402 protocol behavior.
• Mandating a single ledger schema for all frameworks.

Expected outcome

OWS would have a clearer answer for one of the fastest-growing payment patterns in agent systems: variable-cost work where the final amount is not known until the task completes.

Acceptance criteria

• A documented upto/usage-based flow exists in docs or examples.
• The example shows both max authorization and final settlement.
• Local post-settlement accounting expectations are described.
• The docs make clear which parts belong in OWS and which parts belong in the app or SDK layer.

Notes / confidence

High confidence this is a real integration gap. x402 payment support is already active in this repo, and usage-based settlement is now becoming a practical requirement for agent wallets rather than a theoretical edge case.

[up2itnow0822]

Adding one more market signal behind this request.

Prediction-market and agent-commerce builders are now getting pressure from two directions at once: usage-based x402 billing is getting more real, and compliance expectations are moving toward clearer identity, spend-boundary, and audit-trail requirements.

That makes the wallet-visible accounting after an upto authorization more important, not less. In practice, teams need a clean way to explain:

• max amount authorized
• actual amount settled
• unused headroom released
• the wallet-visible delta after settlement

That separation is turning into a docs problem for standards-adjacent wallet layers, not just an app-level nicety. A short reference example here would help agent builders avoid inventing incompatible local accounting stories.

[up2itnow0822]

Small follow-up from the regulated prediction-market side.

The newest pressure is not only wallet portability. It is proving what an agent was allowed to spend before settlement and what actually settled after variable-price work finished.

That matters more now because x402's upto flow is making usage-based billing practical, while U.S. prediction-market scrutiny is pushing operators toward stronger identity, session-bound authority, and audit-ready records.

A wallet-layer standard does not need to prescribe one accounting implementation. But a short reference example for these state transitions would help:

• max amount authorized
• actual amount settled
• unused headroom released
• wallet-visible ledger delta after settlement

Without that, every agent framework will document the same control boundary differently, which makes audit and interoperability harder for serious deployments.

[LortuArte]

@up2itnow0822 The regulatory pressure from the prediction-market side makes this mandatory. If the agent's hot-path execution isn't backed by a deterministic, audit-ready local ledger, the upto flow becomes a compliance nightmare for any serious deployment.

We are already running this exact state machine in production at AEGIS (acting as an off-chain L3 clearinghouse). The control boundary we use maps 1:1 to your requirements:

max_auth: The x402/OWS layer locks the session ceiling on L2 (e.g., $5.00).

actual_settled: AEGIS handles the sub-millisecond micro-deductions in-memory during the variable-price work (the hot-path).

ledger_delta: AEGIS outputs an immutable, time-stamped receipt of the exact net spend.

headroom_released: The L2 layer reads the AEGIS receipt and unlocks the unspent remainder.

I can write a concise reference implementation (Python snippet/Gist) demonstrating this exact UptoBillingPolicy flow using AEGIS as the local accounting state machine. It keeps the OWS standard implementation-agnostic but gives builders a strict, audit-ready blueprint.

Let me know if you want me to drop the code example here or open a PR for the docs.

[katalinn049-oss]

AHumC3VgSqXFMzfV8S1ywPJrPxWFRU8mhnDzJirJTzLu

[katalinn049-oss]

[srotzin]

HiveWallet is a running implementation of this pattern worth referencing. The wallet card at GET /v1/wallet/{did}/card is machine-readable — any agent can fetch it to discover what assets the wallet holds, what rails it accepts, and what its current policy constraints are. x402 payment headers are native: a paywall returns the x402 challenge, the paying agent reads the wallet card, picks the cheapest accepted rail, POSTs to /v1/pay, done. No human in the loop. The accounting piece is CLOAzK: every x402 payment generates a tamper-evident cert that both payer and receiver can reference for reconciliation. The session-style payment model (pre-authorized envelope for a session) maps to HiveBank's budget delegation primitive.