Agent-to-agent micropayments

Hilt Pay API turns a paid agent request into durable operating state:

an x402 V2 payment requirement
confirmed Solana USDC settlement
a signed receipt
an entitlement with metered units
atomic usage records
webhook and support context

The public API namespace is /v1/access. x402 is the HTTP 402 Payment Required protocol shape. Hilt x402 V2 settles in Solana USDC. Native SOL is available through hosted Hilt Pay API payment sessions, not through x402. For the shortest TypeScript integration, use the protectEndpoint wrapper. This page explains the complete buyer and protected-resource protocol underneath it.

The runtime rule

For a metered endpoint, consume one unit before serving the result.

Identify the calling customer or agent.
Call POST /v1/access/entitlements/consume.
Serve the resource when consumption succeeds.
When access is missing or exhausted, create an x402 payment session.
Return 402 with Hilt’s PAYMENT-REQUIRED header.
Receive the buyer’s PAYMENT-SIGNATURE header.
Call POST /v1/access/x402/settle.
Consume one unit and serve the resource.

This avoids a check-then-use race. An entitlement check is useful for display and planning; atomic consumption is the authority for each metered request.

Create a metered product

curl -X POST https://api.hilt.so/v1/access/products \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: product-research-calls-001" \
  -d '{
    "access_app_id": "ACCESS_APP_ID",
    "external_product_id": "research-calls",
    "title": "1,000 research calls",
    "amount_minor_units": 5000000,
    "billing_model": "one_off",
    "usage_unit": "request",
    "usage_units_per_payment": 1000,
    "default_rail": "solana_usdc",
    "allowed_rails": ["solana_usdc"],
    "status": "active",
    "live_mode_confirmed": true
  }'

amount_minor_units uses USDC’s six decimal places. The example price is 5 USDC.

Create the challenge

curl -X POST https://api.hilt.so/v1/access/payment-sessions \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: session-agent-42-research-001" \
  -d '{
    "external_product_id": "research-calls",
    "external_customer_id": "agent_42",
    "payment_protocol": "x402",
    "settlement_rail": "solana_usdc",
    "metadata": {
      "resource": "https://api.example.com/v1/research"
    }
  }'

Relay the response’s encoded PAYMENT-REQUIRED value exactly. Do not rebuild the acceptance in your application. The product allows the Solana USDC settlement rail. The session selects payment_protocol: "x402" separately because x402 is the HTTP payment protocol, not a settlement rail.

Hilt exact payments

x402 allows payment schemes to define how value moves on each network. Hilt uses hilt-exact when the payment includes a Hilt platform fee. The acceptance contains:

the gross amount the buyer approves
the merchant’s direct USDC transfer
Hilt’s direct fee transfer
a requirement that both transfers share one signed Solana transaction

The API verifies the scheme, network, mint, gross amount, each recipient, each amount, the transfer authority, transaction signature, and instruction set. Unexpected instructions or changed payment terms are rejected before submission. When no second transfer is required, the acceptance can use the standard x402 exact scheme.

Sign and retry

Install the Hilt SDK plus the Solana libraries used by your wallet integration:

npm install @hiltpay/sdk @solana/web3.js @solana/spl-token

import {
  createHiltExactPaymentSignature,
  decodePaymentRequiredHeader,
} from "@hiltpay/sdk/x402";

const paymentRequired = decodePaymentRequiredHeader(paymentRequiredHeader);
const prepared = createHiltExactPaymentSignature(
  paymentRequired,
  signedSolanaTransactionBase64,
);

// The buyer retries the protected resource, not the Hilt API.
retryHeaders.set("PAYMENT-SIGNATURE", prepared.paymentSignature);

The buyer wallet constructs the two advertised USDC transfers and signs them as one transaction. The protected-resource server receives PAYMENT-SIGNATURE and calls hilt.payApi.settleX402(...) with its server-side key. The complete TypeScript example includes both boundaries and the Solana transaction builder.

Atomic usage consumption

const usage = await hilt.payApi.consumeEntitlement(
  {
    external_product_id: "research-calls",
    external_customer_id: "agent_42",
    units: 1,
    metadata: { request_id: requestId },
  },
  requestId,
);

if (!usage.consumed) {
  throw new Error("Usage was not consumed");
}

return runResearchJob();

Use the same stable request ID when retrying the same billable operation. Use a new ID for a new operation.

What Hilt records

Each successful payment can create or update:

payment and settlement evidence
signed receipt
entitlement period
granted and remaining usage
idempotent usage events
merchant webhook events
support and audit context

This is the difference between accepting a transaction and operating a paid agent product.

Safety boundaries

Keep the Hilt API key inside the merchant’s protected-resource server or controlled server-side agent runtime. Never expose it to browser code, a buyer agent, or another untrusted client.
Never grant access from a raw transaction hash or unverified wallet claim.
Never consume usage after serving the resource.
Never treat x402 as a chain, token, wallet, or settlement rail.
Use Hilt sandbox sessions to test payment, confirmation, and metered consumption without moving live funds.
Use setup readiness before accepting live traffic.

See Hilt Pay API, API keys, Testing, and Webhooks.

Start here

After payment

Examples and reference

Agent-to-agent micropayments

Agent-to-agent micropayments

The runtime rule

Create a metered product

Create the challenge

Hilt exact payments

Sign and retry

Atomic usage consumption

What Hilt records

Safety boundaries

​Agent-to-agent micropayments

​The runtime rule

​Create a metered product

​Create the challenge

​Hilt exact payments

​Sign and retry

​Atomic usage consumption

​What Hilt records

​Safety boundaries

Agent-to-agent micropayments

The runtime rule

Create a metered product

Create the challenge

Hilt exact payments

Sign and retry

Atomic usage consumption

What Hilt records

Safety boundaries