docs(x402): metered upto settlement in seller quickstart#20
Merged
Conversation
Sellers advertising `upto` only learned how to set the max, not how to settle the actual usage afterwards. Add a "Settling the actual amount" section covering `setSettlementOverrides` (settle ≤ max, "0" = no onchain tx), with the generic mechanics linked to the upstream x402 docs and only the HPP-specific facts stated here (both facilitators support upto variable settlement; /supported to confirm). Adds a gateway/non-Node note (sidecar vs native facilitator HTTP) for API-gateway sellers.
Neither our docs nor upstream explained the observable serve-then-settle timing. Add it where integrators need it: - how-it-works: the response is held until settlement completes, so a 200 (with a payment-response receipt) means settled onchain; a settle failure returns an error instead of the resource (work done but not delivered/ charged). HPP settles synchronously (waits for onchain confirm, p50 ~1.3s). - seller quickstart: res.json() != settled; react to settlement via resourceServer.onAfterSettle / onSettleFailure (ctx.result = outcome), with the full hook set linked upstream. All verified onchain on Sepolia (partial settle, settle-0, buyer receipt decode, onAfterSettle firing with ctx.result).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Fills two gaps in the x402 seller/settlement docs — both missing from our docs and upstream — needed by gateway/LLM sellers (e.g. hpp-router #150).
1. Metered
uptosettlement (quickstart-sellers→ "Settling the actual amount")Sellers advertising
uptoonly learned to set the max, not how to settle the actual usage. Adds thesetSettlementOverridesrecipe (settle≤ max,"0"⇒ no onchain tx), generic mechanics linked upstream, HPP facts stated here, and a gateway/non-Node note (sidecar vs native).2. Serve-then-settle contract + settlement hooks (
how-it-works,quickstart-sellers→ "Reacting to settlement")The observable timing was undocumented everywhere:
200(withpayment-responsereceipt) means settled onchain; a settle failure returns an error, not the resource (work done but not delivered/charged). HPP settles synchronously (waits for onchain confirm, p50 ~1.3s).res.json()≠ settled; react viaresourceServer.onAfterSettle/onSettleFailure(ctx.result= outcome); full hook set linked upstream.Verification (HPP Sepolia, onchain)
10000, override1000→ onchain transfer = 1000 (tx 0x164163eb…).{ amount: "0" }→ receipttransaction: ""(no onchain tx).200→ decodedpayment-response={ success, transaction, payer, network }.onAfterSettlefires after settlement;ctx.result={ success, payer, transaction, network }.Every claim in the added examples is verified against live onchain behavior. Content-only, additive; page compiles (
onBrokenLinks: 'throw').