HTTP `402 Payment Required` is a clean way for a paid API to deny access without pretending the request was unauthorized, forbidden, or missing. The client is allowed to use the resource, but payment has not been completed for the current customer and product.
The useful metered implementation is a loop: consume one unit, return `402` when usage is missing, let the buyer or agent pay, settle the retry through Hilt, consume one unit, then serve.
x402 gives that `402` response a machine-readable protocol shape. Hilt Pay API turns it into a real payment-to-access record with Solana USDC settlement, receipts, entitlements, webhooks, support context, and audit history.
01
Request comes in
A user, backend, or agent requests a protected API resource.
02
Server consumes usage
Your backend atomically consumes one Hilt usage unit before serving billable work.
03
Server returns 402
If usage is missing, return HTTP 402 with Hilt's x402 V2 PAYMENT-REQUIRED header.
04
Paid retry settles
The buyer pays the Solana USDC terms and retries with PAYMENT-SIGNATURE; your backend settles it through Hilt.
05
Retry succeeds
Your backend atomically consumes one unit and serves only after settlement and consumption succeed.
HTTP 402 is the response status
It tells the client that payment is required before the resource can be served.
x402 is the protocol shape
It gives agents and software a machine-readable payment requirement. It is not a blockchain, token, wallet, or settlement rail.
Hilt is the operating layer
Hilt handles the payment session, Solana USDC verification, receipt, entitlement, webhook, support context, and audit trail.
A minimal 402 response shape
In practice, your response should tell the client what happened, which protocol is being used, which settlement path applies, and which payment session or requirement to complete.
Keep the response useful for both humans and agents. The client should not need private docs to learn that it needs to pay and retry with `PAYMENT-SIGNATURE`.
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 x402 V2 requirement>
Content-Type: application/json
{
"error": "payment_required",
"payment_protocol": "x402",
"settlement_rail": "solana_usdc",
"payment_session": {
"id": "hpa_x402_..."
},
"retry": {
"header": "PAYMENT-SIGNATURE"
}
}The rules that keep the flow production-safe
Do not serve from a raw transaction hash or client claim.
Keep Hilt API keys server-side.
Use idempotency keys for writes such as product, webhook, and payment-session creation.
Process webhooks idempotently and verify signatures before changing local state.
Use atomic consumption as the authority for each metered request; use entitlement checks for durable access.
Why this matters for agentic payments
Agentic payments need a resource to explain what it costs and how to unlock it without a person reading a checkout page first. HTTP `402` and x402 provide that request/response language. Hilt provides the operating layer behind it so the payment becomes an entitlement your product can trust.
Next step
Wire atomic consumption before the paid route.
The protected-resource demo shows the consume, `402`, settle, consume, serve loop in code.