{"name":"Hilt Pay API sample payment-to-access flow","version":"2026-07-24","canonical_url":"https://www.hilt.so/v1/sample-flow","summary":"A public example showing how a product can use Hilt Pay API to protect a metered API endpoint with HTTP 402, Solana USDC settlement, receipt, entitlement, atomic usage, and webhook state.","audience":["developers","AI agents","API products","bots","paid software teams"],"current_live_scope":{"hilt_pay_api_namespace":"/v1/access","settlement":"Solana USDC","protocol_shape":"HTTP 402 Payment Required with a Hilt-created x402 payment requirement","subscription_mode":"Buyer-approved native Solana USDC subscriptions for recurring access"},"steps":[{"id":"discover","title":"Discover the public contract","description":"Read Hilt's LLM files, agent manifest, catalog, OpenAPI, SDK docs, and examples to choose Workspace or API.","links":["https://www.hilt.so/llms.txt","https://www.hilt.so/v1/catalog","https://docs.hilt.so/developers/access","https://docs.hilt.so/developers/grok-build"]},{"id":"setup","title":"Prepare the Hilt Pay API setup","description":"Create a setup intent, submit an app and product manifest, and route the owner through approval before live key use.","links":["https://www.hilt.so/developers/agent-setup","https://docs.hilt.so/developers/agent-setup"]},{"id":"attempt_access","title":"Attempt the authoritative access operation","description":"For durable access, call POST /v1/access/entitlements/check. For metered access, atomically attempt to consume one unit with POST /v1/access/entitlements/consume before each billable operation. Serve immediately only when that authoritative operation succeeds.","links":["https://docs.hilt.so/developers/access","https://docs.hilt.so/developers/examples","https://docs.hilt.so/developers/grok-build"]},{"id":"require_payment","title":"Return HTTP 402 when unpaid","description":"If access is missing, return a Hilt-created x402 payment requirement that describes the price and payment session for the protected resource.","links":["https://www.hilt.so/x402","https://www.hilt.so/articles/http-402-payment-required-api"]},{"id":"pay","title":"Let the buyer pay the advertised terms","description":"The buyer or buyer-agent validates the x402 V2 terms and signs the Solana USDC payment from its own wallet. The buyer never receives the merchant's Hilt API key.","links":["https://docs.hilt.so/developers/agent-micropayments"]},{"id":"retry","title":"Retry the protected resource","description":"The buyer retries the merchant's protected endpoint with PAYMENT-SIGNATURE. The buyer does not call Hilt's settlement or entitlement endpoints directly.","links":["https://docs.hilt.so/developers/examples"]},{"id":"settle","title":"Settle through Hilt from the merchant server","description":"The merchant server calls POST /v1/access/x402/settle. Hilt verifies the x402 V2 payment against the advertised Solana USDC terms, binds the receipt, activates entitlement, records support and audit state, and emits webhooks.","links":["https://docs.hilt.so/developers/webhooks","https://docs.hilt.so/merchant/payments-receipts"]},{"id":"consume_and_serve","title":"Consume usage, then serve","description":"For metered work, the merchant server atomically consumes one unit with POST /v1/access/entitlements/consume. The protected resource returns the paid result only after settlement and consumption both succeed.","links":["https://docs.hilt.so/developers/agent-micropayments"]}],"safe_boundaries":["Do not serve protected content from a wallet signature, transaction hash, or client claim alone.","For metered products, consume usage atomically before serving each billable operation.","Do not put Hilt API keys in browser code.","The buyer retries the protected resource; only the merchant server calls Hilt settlement and entitlement routes.","Do not claim Base, EVM, or USDT live settlement unless public Hilt docs announce availability.","Do not describe x402 as a chain, token, wallet, or settlement path."]}