Metered payment channels

Hilt Pay API supports MPP session payment channels for high-frequency paid work where one on-chain payment per request would be too slow or too expensive. The payer escrows a USDC spending ceiling once. Each delivered unit is then authorized by a cumulative off-chain voucher. Hilt verifies and records every accepted voucher, and the channel settles once at the highest verified amount. Any unused USDC is returned to the payer through the channel close flow. Use payment channels for:

token or compute streaming
repeated agent tool calls in one session
inference, search, data, or media work billed in small units
bursts of API requests where the unit price is below practical per-transaction economics

Use x402 exact payments for a single known-price request. Use a hosted payment session for a conventional checkout. PayMe and Direct Checkout do not use this channel lifecycle.

Public contract

Hilt channels use:

Field	Value
HTTP payment protocol	MPP Payment authentication
Intent	`session`
Method	Solana
Network	`solana:mainnet`
Asset	native Solana USDC, six decimals
Channel program	`CHNLxYvVA28MJP9PrFuDXccuoGXAx7jBacfLEkahyGsX`
Voucher model	cumulative amount, never per-request addition
Hilt fee	1% of the final settled amount on standard Live pricing

The current MPP Solana session specification is an Internet-Draft. Hilt pins its server implementation and the mainnet channel program so a session cannot silently move to different settlement terms during its lifetime.

Security model

The merchant payout wallet, USDC mint, channel program, Hilt metering ceiling, unit price, Hilt fee destination, fee rate, expiry, external customer reference, voucher signer mode, and complete on-chain split are pinned when Hilt creates the session. Credentials issued for one Hilt session are rejected by every other session. Hilt does not hold the payer’s wallet key and cannot sign payer vouchers. A valid cumulative voucher can increase the authorized total only within the escrowed deposit. A later voucher replaces the earlier cumulative ceiling; it is not added to it again. Hilt stores channel state in PostgreSQL and serializes every mutation with a row lock. Delivery IDs and merchant write operations are idempotent. Voucher commitments above the Hilt metering ceiling are rejected even if the payer deposited more. The recovery worker settles expired or interrupted sessions only at the highest voucher Hilt already verified. It cannot increase the claim during recovery. At settlement, the channel program pays the developer wallet and Hilt fee destination directly from escrow using the split committed when the channel opened. Hilt’s operator key pays the settlement network fee and authorizes the claim transaction; it is assigned no payment share. Integer rounding can leave at most one USDC base unit, which the channel program sends to its protocol treasury when the sealed channel closes. Use a unique, stable external_customer_id that does not expose email, wallet, or other personal data. Keep the Hilt API key on your server.

Before you start

You need:

a Live Hilt Pay API key with access:read and access:write
an active one-off Hilt Pay API product using solana_usdc
a verified Solana payout wallet with an initialized, unfrozen native USDC token account
a unit price in USDC minor units
an MPP-compatible payer client that supports the Solana session intent

The product amount becomes the price of one usage unit. For example, 10000 means 0.01 USDC per unit.

Session lifecycle

Your server creates a capped metered session.
Hilt returns the signed WWW-Authenticate: Payment challenge in the response header and body.
The payer client verifies the challenge, approves the cap, opens the on-chain USDC channel, and submits its Authorization: Payment open credential.
Before each billable unit, your server reserves a delivery with a unique delivery ID.
The payer client signs the next cumulative voucher and posts the delivery ID and voucher to the directive’s commitUrl.
Hilt verifies the voucher, commits that exact delivery, and returns the updated evidence before your application releases the paid result.
The payer can top up or close through standard MPP actions. Your server can also request recovery settlement.
At the deadline, Hilt’s worker settles the highest accepted voucher and preserves the settlement signature and delivery ledger.

Do not serve paid work merely because a client sent a voucher. Serve only after Hilt accepts the authorization and the matching delivery is committed.

Create a session

POST /v1/access/metered-sessions

curl -i -X POST https://api.hilt.so/v1/access/metered-sessions \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: channel-customer-123-run-001" \
  -d '{
    "external_product_id": "research-token",
    "external_customer_id": "customer-123",
    "cap_minor_units": 5000000,
    "expires_in_seconds": 3600,
    "metadata": {"job_id": "job-8f42"}
  }'

cap_minor_units is Hilt’s maximum billable amount for this session and the suggested opening deposit. It is not an automatic charge. An MPP client can choose a larger deposit, but Hilt will never accept cumulative vouchers above this ceiling. The value must be a whole number of product units. Session expiry can be five minutes to 24 hours. Standard 1% products use Hilt’s published $50 fee cap, so a single channel can authorize at most 5,000 USDC. Hilt returns the exact maximum for products with different approved fee terms. The response includes:

{
  "metered_session": {
    "id": "hms_...",
    "status": "payment_required",
    "protocol": "mpp",
    "intent": "session",
    "rail_id": "solana_usdc",
    "metering": {
      "usage_unit": "token",
      "unit_price_minor_units": 10000,
      "cap_minor_units": 5000000,
      "deposit_minor_units": 0,
      "committed_minor_units": 0,
      "remaining_minor_units": 0
    },
    "fee": {
      "bps": 100,
      "paid_from_settled_amount": true,
      "minor_units": 0
    },
    "settlement": {
      "merchant_minor_units": 0,
      "hilt_fee_minor_units": 0,
      "rounding_residual_minor_units": 0
    }
  },
  "challenge": "Payment ...",
  "idempotent_replay": false
}

The same challenge is returned as WWW-Authenticate.

Open and authorize

The payer client sends standard MPP credentials to the public authorization endpoint:

POST /v1/access/metered-sessions/{session_id}/authorize
Authorization: Payment <MPP credential>

The credential action may be open, use, voucher, topUp, or close. Hilt validates it against the exact session challenge and current channel state. Successful responses include Payment-Receipt. The public authorization route does not accept or require the merchant API key. The signed MPP credential is the authority for that channel action; it does not grant access to other Hilt routes.

Reserve a billable delivery

Create the reservation before releasing one or more units:

curl -X POST https://api.hilt.so/v1/access/metered-sessions/hms_.../deliveries \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: delivery-job-8f42-chunk-0001" \
  -d '{
    "units": 25,
    "delivery_id": "job-8f42-chunk-0001",
    "ttl_seconds": 300
  }'

Hilt multiplies units by the product unit price and returns the MPP delivery directive. Reusing the delivery ID with the same amount returns the existing reservation. Reusing it with different terms fails with 409. The response contains a standard MPP delivery directive and its public commitUrl. The payer client signs the required cumulative voucher and posts it with the delivery ID:

POST /v1/access/metered-sessions/{session_id}/commits
Content-Type: application/json

{
  "deliveryId": "job-8f42-chunk-0001",
  "voucher": {
    "voucher": {
      "channelId": "...",
      "cumulativeAmount": "250000",
      "expiresAt": 1788451200
    },
    "signer": "...",
    "signature": "...",
    "signatureType": "ed25519"
  }
}

This public route does not accept or require a merchant API key. The signed voucher is the authority for the named delivery only. Hilt checks the channel, monotonic cumulative amount, expiry, signature, reservation, amount, and metering ceiling together. Serve the result only after the response reports that delivery as committed.

Inspect evidence

GET /v1/access/metered-sessions/{session_id}

The response preserves:

payer and authorized voucher signer
deposit, committed total, and remaining authorized balance
highest accepted voucher signature
every reserved, committed, or expired delivery
close state and final Solana settlement signature
product, customer, fee, asset, program, and expiry terms

This is the merchant reconciliation record for the channel. The final Solana signature remains independently verifiable on-chain.

Close or recover

An MPP-compatible payer can submit a close action. Your server can also request settlement:

curl -X POST https://api.hilt.so/v1/access/metered-sessions/hms_.../settle \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: settle-channel-customer-123-run-001"

This endpoint can claim only the highest cumulative voucher already verified and stored by Hilt. Retrying with the same key is safe. Hilt also runs a recovery worker at session expiry, so an interrupted merchant process does not become the sole path to closure.

SDK methods

TypeScript SDK 1.5.0:

const created = await hilt.payApi.createMeteredSession(
  {
    external_product_id: "research-token",
    external_customer_id: "customer-123",
    cap_minor_units: 5_000_000,
    expires_in_seconds: 3600,
  },
  "channel-customer-123-run-001",
);

const reserved = await hilt.payApi.reserveMeteredDelivery(
  created.metered_session.id,
  { units: 25, delivery_id: "job-8f42-chunk-0001" },
  "delivery-job-8f42-chunk-0001",
);

const committed = await hilt.payApi.commitMeteredDelivery(
  created.metered_session.id,
  {
    deliveryId: reserved.delivery.deliveryId,
    voucher: signedVoucher,
  },
);

Python SDK 1.5.0 exposes the same lifecycle through create_metered_session, authorize_metered_session, reserve_metered_delivery, commit_metered_delivery, get_metered_session, and settle_metered_session.

Error handling

Code	Meaning	Action
`invalid_metered_session_cap`	The cap is below one unit, not divisible by the unit price, or exceeds the product’s fee-policy limit	Use the returned unit price and maximum cap
`hilt_pay_api_plan_protocol_unavailable`	The active API plan does not include MPP sessions	Enable MPP for the plan before creating a channel
`metered_sessions_unavailable`	New MPP channels are temporarily disabled	Do not create a replacement payment; retry channel creation later
`metered_session_usdc_product_required`	The selected product is not configured for Solana USDC	Use an active `solana_usdc` product
`metered_session_merchant_usdc_account_required`	The payout wallet cannot currently receive channel settlement	Initialize its native Solana USDC token account, then create the session again
`metered_session_not_open`	Delivery was requested before channel open	Complete the MPP open action first
`metered_delivery_idempotency_conflict`	A delivery ID was reused with a different amount	Reuse the original terms or create a new delivery ID
`metered_delivery_expired`	The payer did not authorize the reservation in time	Create a new delivery reservation
`metered_session_settlement_failed`	Settlement could not complete yet	Retry with the same idempotency key; do not increase or recreate the channel
`metered_session_settlement_in_progress`	Another request or the recovery worker is already settling this channel	Wait briefly, then retrieve the session before retrying

Start here

After payment

Examples and reference

Metered payment channels

Metered payment channels

Public contract

Security model

Before you start

Session lifecycle

Create a session

Open and authorize

Reserve a billable delivery

Inspect evidence

Close or recover

SDK methods

Error handling

Source standards

​Metered payment channels

​Public contract

​Security model

​Before you start

​Session lifecycle

​Create a session

​Open and authorize

​Reserve a billable delivery

​Inspect evidence

​Close or recover

​SDK methods

​Error handling

​Source standards

​Related docs

Metered payment channels

Public contract

Security model

Before you start

Session lifecycle

Create a session

Open and authorize

Reserve a billable delivery

Inspect evidence

Close or recover

SDK methods

Error handling

Source standards

Related docs