HTTP 402
How to Add HTTP 402 Payment Required to an API
A practical guide to protecting an API endpoint with HTTP 402, x402 payment requirements, Solana USDC settlement, and Hilt entitlement checks.
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 implementation is a loop: check entitlement, return `402` when access is missing, let the buyer or agent pay, then retry after Hilt confirms active access.
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 checks access
Your backend calls Hilt entitlement state before serving the paid response.
03
Server returns 402
If unpaid, return HTTP 402 with the Hilt-created payment requirement or checkout handoff.
04
Payment completes
The buyer or agent pays through Solana USDC on the current public live settlement path.
05
Retry succeeds
After Hilt activates entitlement state, the client retries and receives the protected resource.
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, retry, and check access again.
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": "payment_required",
"payment_protocol": "x402",
"settlement_rail": "solana_usdc",
"payment_session": {
"id": "aps_...",
"checkout_url": "https://pay.hilt.so/..."
},
"retry": {
"after": "payment_confirmed",
"check": "/v1/access/entitlements/check"
}
}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 entitlement checks as the access decision on every protected route.
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 the entitlement check before the paid route.
The protected-resource demo shows the denied, `402`, payment, proof, entitlement, retry loop in code.