Hilt Pay API
AI-to-AI Micropayments with Solana USDC
How Hilt Pay API combines x402 V2, direct Solana USDC settlement, receipts, entitlements, webhooks, and atomic usage metering for paid agent requests.
The payment is only the middle of the request
An AI-to-AI payment flow needs more than a wallet transaction. One agent is buying a defined unit of work from another service, so the system must connect the payment to the correct resource, customer, request, receipt, and remaining usage balance.
Hilt Pay API handles that operating layer. x402 provides the HTTP `402 Payment Required` protocol shape, Solana USDC provides current public live settlement, and Hilt turns successful settlement into access state the protected resource can enforce.
Request loop
Check. Challenge. Pay. Settle. Consume. Serve.
Who controls each part
A merchant owner approves the Hilt Pay API plan, live credential scopes, payout wallet, and live use. After approval, the merchant's backend or controlled agent can run the paid-resource loop autonomously with its scoped Hilt key kept server-side.
Merchant-side agent or backend
Creates payment sessions, settles returned payment signatures, checks or consumes entitlement, and serves the protected work. Its Hilt credential never enters buyer-facing code.
Buyer agent
Reads the payment requirement, validates the advertised terms, and signs from its own controlled wallet. It does not receive the merchant's Hilt API key.
The complete paid-request loop
Hilt keeps every transition explicit so a network timeout or repeated agent request cannot silently become duplicate payment or duplicate usage.
01
Check and consume access
The protected resource asks Hilt to consume one entitlement unit using a unique request id. If a unit is available, the request can be served immediately.
02
Return HTTP 402
If access is missing or the usage balance is exhausted, the resource creates a Hilt payment session and returns its x402 V2 PAYMENT-REQUIRED header.
03
Pay once from the agent wallet
The buyer agent validates the advertised Solana USDC terms and signs one transaction containing the required transfers. Hilt never takes custody of the buyer's funds.
04
Settle and create access state
Hilt verifies the signed transaction against the payment requirement, confirms settlement, records the receipt, and grants the configured usage units.
05
Retry the original request
The buyer agent retries with PAYMENT-SIGNATURE. The resource settles idempotently, consumes one unit, and serves the result only after both operations succeed.
Atomic metering is the access decision
The entitlement usage call atomically checks the remaining balance and consumes the requested units. A unique idempotency key binds that decision to the agent request.
This lets a merchant sell one request, a bundle of calls, or another fixed usage unit without using a transaction hash as a reusable access token.
const usage = await hilt.payApi.consumeEntitlement(
{
external_product_id: "research-calls",
external_customer_id: agentId,
units: 1,
metadata: { request_id: requestId },
},
{ idempotencyKey: "consume-" + requestId },
);What the runtime protects
Fail-closed access
Payment proof alone is not the access decision. The protected resource serves work only after Hilt settlement and entitlement consumption succeed.
Safe retries
Settlement and usage calls use idempotency keys. A retry can reconcile a finalized transaction without asking the buyer to pay again.
Complete operating record
Each confirmed payment produces connected payment-session, receipt, entitlement, webhook, analytics, and audit state.
Zero custody
The buyer pays from its own wallet and merchant settlement goes directly to the merchant's configured payout wallet.
Build with the public contract
TypeScript SDK `1.2.0` includes the x402 V2 helpers, typed settlement methods, and atomic entitlement consumption. Python SDK `1.2.0` exposes the same settlement and metering operations for server-side services.
The public reference example uses current Solana Kit transaction and token clients, a committed lockfile, and the same fail-closed request order described here.