Hilt Pay API

Hilt Pay API lets software turn a stablecoin payment into an access decision. Use it when an API, AI tool, bot, dataset, software feature, private product, or paid agent needs:

a payment session
an x402 402 Payment Required response
Solana USDC settlement
a receipt and proof trail
an entitlement check
webhook events
subscription state for recurring access
support context that can be fetched through the API

The public API namespace is /v1/access. This is the Hilt surface for paid API access and agentic payments: a protected resource can return a payment requirement, the buyer or agent can complete payment, and your backend can serve only after Hilt entitlement state is active.

Current public scope

Hilt Pay API is live with Solana USDC settlement. x402 is the protected-resource protocol shape for API and agent flows. Treat it as the HTTP 402 Payment Required contract your resource can return when access is missing. The live public settlement rail is Solana USDC; create live sessions only from rails returned as available by Hilt for that product and account. Additional settlement rails will have their own setup docs when they are publicly available.

Route overview

Use the /v1/access namespace for Hilt Pay API objects:

Area	Routes	Use when
Rails	`GET /rails`, `GET /rail-settings`, `PUT /rail-settings/{rail_id}`	list available payment paths and configure the merchant payout wallet for Solana USDC
Apps	`POST /apps`	create an app boundary for an API, bot, agent tool, dataset, or software product
Products	`POST /products`, `GET /products/available-rails`, `GET /products/{id}/available-rails`	create one-off or recurring access products and show only supported payment options
Readiness	`GET /setup/readiness`	check product, rail, webhook, billing, and live configuration before real traffic
Sessions	`POST /payment-sessions`	start a buyer or agent payment flow
Sandbox	`POST /sandbox/payment-sessions`, `POST /sandbox/payment-sessions/{sandbox_session_id}/confirm`	test the same access object shapes without live money
Entitlements	`POST /entitlements/check`, `POST /entitlements/consume`, `GET /entitlements/{id}`	check durable access or atomically consume metered usage
x402 settlement	`POST /x402/settle`	verify and settle an x402 V2 payment, issue the receipt, and activate the entitlement
Proofs	`POST /payment-proofs`	submit payment evidence when your flow needs an explicit proof step
Webhooks	`POST /webhooks`	send signed events to your backend after payment, receipt, membership, delivery, or subscription changes
Native subscriptions	`GET /native-subscriptions/{authorization_id}`, `POST /native-subscriptions/{authorization_id}/cancel-intent`, `POST /native-subscriptions/{authorization_id}/cancel-confirm`	read and cancel Solana USDC automatic renewal authorizations
Agent setup	`POST /agent-bootstrap`, `GET /agent-bootstrap/{setup_intent_id}/status`, `POST /agent-bootstrap/{setup_intent_id}/manifest`, `POST /agent-bootstrap/{setup_intent_id}/approve`	let an agent prepare setup while the owner approves billing, payout, and live credentials
API billing	`GET /billing/entitlement`, `POST /billing/checkout/stripe`	manage Hilt Pay API plan access

How the protected-resource flow works

For durable or time-based access, call POST /v1/access/entitlements/check and serve only when Hilt returns has_access: true. For metered requests:

Your product receives a request with a stable request id.
Your backend atomically consumes one unit with POST /v1/access/entitlements/consume.
If usage is missing, create a payment session and return HTTP 402 with Hilt’s PAYMENT-REQUIRED header.
The buyer or buyer-agent pays the Solana USDC terms and retries your resource with PAYMENT-SIGNATURE.
Your backend settles the signature through POST /v1/access/x402/settle.
Hilt verifies settlement, records the receipt, activates entitlement state, and returns PAYMENT-RESPONSE.
Your backend atomically consumes one unit with the same logical request id.
Serve only after settlement and consumption succeed.

Do not grant access from a client claim, signed payload alone, or raw transaction hash. Use Hilt’s durable check or atomic metered consumption for the access decision.

Create an app

POST /v1/access/apps

curl -X POST https://api.hilt.so/v1/access/apps \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: app-pro-ai-api-001" \
  -d '{
    "name": "Pro AI API",
    "external_app_id": "pro-ai-api",
    "default_rail": "solana_usdc"
  }'

Use one app boundary per product area, customer product, or integration surface.

Configure Solana USDC settlement

PUT /v1/access/rail-settings/solana_usdc

curl -X PUT https://api.hilt.so/v1/access/rail-settings/solana_usdc \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: rail-settings-solana-usdc-001" \
  -d '{
    "enabled": true,
    "mode": "live",
    "payout_address": "YOUR_SOLANA_PAYOUT_WALLET",
    "label": "Primary Solana USDC payout"
  }'

Your checkout should render only rails returned as available by Hilt for the product and account.

Create a product

POST /v1/access/products

One-off 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-pro-ai-api-001" \
  -d '{
    "access_app_id": "ACCESS_APP_ID",
    "external_product_id": "pro-api",
    "title": "Pro API access",
    "amount_minor_units": 79000000,
    "default_rail": "solana_usdc",
    "billing_model": "one_off",
    "entitlement_duration_days": 30,
    "usage_unit": "request",
    "usage_units_per_payment": 1000,
    "status": "active",
    "live_mode_confirmed": true
  }'

Recurring 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-pro-api-subscription-001" \
  -d '{
    "access_app_id": "ACCESS_APP_ID",
    "external_product_id": "pro-api-monthly",
    "title": "Pro API monthly access",
    "amount_minor_units": 79000000,
    "default_rail": "solana_usdc",
    "billing_model": "recurring",
    "renewal_mode": "solana_native_subscription",
    "billing_interval_days": 30,
    "cancel_at_period_end": true,
    "status": "active",
    "live_mode_confirmed": true
  }'

For recurring products, the buyer approves a native Solana subscription setup once. Hilt records future successful collections as normal payment-to-access evidence: payment, receipt, entitlement period, webhook event, support context, and audit history.

Check setup readiness

GET /v1/access/setup/readiness

Use setup readiness before going live. It tells your agent or backend which product, rail, webhook, billing, and live settings still need attention.

curl "https://api.hilt.so/v1/access/setup/readiness?external_product_id=pro-api" \
  -H "X-Hilt-Key: $HILT_API_KEY"

Check durable access state

POST /v1/access/entitlements/check

curl -X POST https://api.hilt.so/v1/access/entitlements/check \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -d '{
    "external_product_id": "pro-api",
    "external_customer_id": "cust_123"
  }'

Response:

{
  "has_access": false,
  "status": "not_found",
  "access_product_id": "access_product_id",
  "external_product_id": "pro-api"
}

Use this call for durable or time-based access display and planning. If has_access is false, return HTTP 402 with the payment requirement or checkout handoff your flow supports. For metered agent requests, the runtime authority is POST /v1/access/entitlements/consume. Entitlement checks are useful for display and planning; atomic consumption decides whether each billable request is served. Do not replace either server-side decision with a wallet signature, transaction hash, or client-side claim.

Create a payment session

POST /v1/access/payment-sessions

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-cust-123-pro-api-001" \
  -d '{
    "external_product_id": "pro-api",
    "external_customer_id": "cust_123",
    "rail": "solana_usdc",
    "metadata": {
      "resource": "https://api.example.com/ai/pro"
    }
  }'

The response includes:

payment_session.id
payment_session.status
payment_session.checkout_url when the flow uses hosted checkout
payment_session.payment_requirement when the flow is protocol-based
pending_entitlement
rail
payment_session_options

Use checkout_url for hosted Solana USDC checkout handoff. Use payment_requirement only when the response includes a protocol requirement for your protected-resource flow.

Return and settle x402 V2

For an x402 session, Hilt returns the standard V2 payment requirement and its encoded PAYMENT-REQUIRED header. Relay that header with HTTP 402 Payment Required. The selected acceptance names Solana mainnet, native USDC, the gross amount, the merchant recipient, and the Hilt payment scheme. When a platform fee applies, scheme: hilt-exact includes two direct USDC transfer legs in extra.hilt.atomicTransfers. The buyer signs one Solana transaction. The merchant payment and Hilt fee either settle together or neither settles; Hilt does not receive or forward the merchant portion. The buyer or agent retries with a base64-encoded x402 V2 PAYMENT-SIGNATURE header. Send that header and the Hilt payment-session ID to:

POST /v1/access/x402/settle

{
  "payment_session_id": "hpa_x402_...",
  "payment_signature": "BASE64_X402_V2_PAYMENT_PAYLOAD"
}

Hilt binds the selected acceptance to the stored session, verifies the signed transaction, submits it to Solana, waits for confirmation, creates the signed receipt, and activates or extends the entitlement. A successful response includes the encoded PAYMENT-RESPONSE header. Do not serve from a signed payload alone. Serve only after settlement succeeds and the entitlement check or usage consumption succeeds.

Consume metered usage

Metered products grant a fixed number of units per successful payment. Consume units atomically before serving:

POST /v1/access/entitlements/consume

{
  "external_product_id": "pro-api",
  "external_customer_id": "cust_123",
  "units": 1,
  "metadata": {
    "request_id": "req_01J..."
  }
}

Send a unique Idempotency-Key for each billable operation. Concurrent requests cannot consume the same final unit twice. When no units remain, return a fresh Hilt 402 challenge rather than serving the resource. For a complete route pattern, see Agent-to-agent micropayments.

Submit proof when your flow needs it

POST /v1/access/payment-proofs

Proof submission records the payment evidence for the payment session. It does not grant access by itself. Hilt still verifies payment state and updates entitlement state before has_access becomes true.

Native subscriptions

Hilt Pay API supports recurring products through native Solana subscription setup. For the complete merchant and API guide, see Native subscriptions. Use this for:

paid APIs
AI tools with monthly access
subscription datasets
recurring bot access
private software subscriptions
paid communities that need automatic access periods

The buyer signs once to approve the subscription setup. Future successful collections extend the paid-through period and emit the same operational events your product already consumes.

Native subscription quickstart

Create a recurring product with billing_model: "recurring", renewal_mode: "solana_native_subscription", billing_interval_days, and cancel_at_period_end.
Start a payment session for that product with rail: "solana_usdc".
Send the buyer to the returned checkout_url, or return the protocol requirement if your product is using the protected-resource path and Hilt returned one.
After the buyer signs and the first payment succeeds, check access with POST /v1/access/entitlements/check.
Store the Hilt identifiers you need for support: entitlement id, payment id, receipt id, and native subscription authorization id when present in the Hilt response or webhook payload.
Drive your own access decision from Hilt entitlement state, not from a wallet signature alone.

Read a native authorization:

curl https://api.hilt.so/v1/access/native-subscriptions/AUTHORIZATION_ID \
  -H "X-Hilt-Key: $HILT_API_KEY"

Cancellation is period-aware:

the buyer or merchant can stop future collection
access can remain active until the paid-through date
Hilt records cancellation and subscription state
your product reads the entitlement state through the same access check

Create a cancellation intent:

curl -X POST https://api.hilt.so/v1/access/native-subscriptions/AUTHORIZATION_ID/cancel-intent \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -d '{
    "reason": "buyer_requested",
    "cancel_at_period_end": true
  }'

Confirm the signed cancellation:

curl -X POST https://api.hilt.so/v1/access/native-subscriptions/AUTHORIZATION_ID/cancel-confirm \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: native-cancel-AUTHORIZATION_ID-001" \
  -d '{
    "cancel_tx_signature": "SOLANA_CANCEL_TRANSACTION_SIGNATURE",
    "reason": "buyer_requested",
    "immediate_revoke": false,
    "verify_onchain": true
  }'

If immediate_revoke is false, access can remain valid until the current paid-through date. Keep using entitlement checks to decide what the buyer can access.

Webhooks

POST /v1/access/webhooks

curl -X POST https://api.hilt.so/v1/access/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_API_KEY" \
  -H "Idempotency-Key: webhook-pro-ai-api-001" \
  -d '{
    "label": "Pro AI API access sync",
    "url": "https://api.example.com/hilt/webhook",
    "subscribed_events": [
      "payment.confirmed",
      "receipt.created",
      "membership.activated",
      "membership.renewed",
      "membership.expired",
      "subscription.cancelled",
      "delivery.failed"
    ],
    "product_ids": ["ACCESS_PRODUCT_OR_HILT_PRODUCT_ID"]
  }'

Store the returned signing secret immediately. Verify webhook signatures before changing access in your own system.

Sandbox sessions

Use sandbox sessions to test the integration without live money.

POST /v1/access/sandbox/payment-sessions

curl -X POST https://api.hilt.so/v1/access/sandbox/payment-sessions \
  -H "Content-Type: application/json" \
  -H "X-Hilt-Key: $HILT_SANDBOX_API_KEY" \
  -H "Idempotency-Key: sandbox-session-cust-123-001" \
  -d '{
    "external_product_id": "pro-api",
    "external_customer_id": "cust_123",
    "rail": "solana_usdc",
    "confirm_sandbox_mode": true
  }'

Use sandbox mode for:

denied access
pending access
allowed access
webhook consumer testing
repeated SDK and Postman checks

Use setup readiness before real traffic. A low-value live settlement check is optional after sandbox validation when your team wants extra confidence in the live wallet, payout, receipt, webhook, and entitlement path.

Agent setup

Agents can prepare the setup before the owner approves live use.

POST /v1/access/agent-bootstrap

The agent can submit a setup manifest for:

app
product
billing model
protected resource
webhook destination
settlement rail
owner approval handoff

Owners still approve live billing, payout settings, and production API credentials from Hilt.

Pricing

Hilt Pay API has separate pricing from Hilt Pay Workspace:

Tier	Monthly	Yearly	Solana USDC fee
Sandbox	$0	$0	Test mode only
Starter	$79	$790	1.00%
Growth	$349	$3,490	0.70%
Scale	$1,250	$12,500	0.45%
Enterprise	Custom	Custom	Custom

Open Hilt Pay API pricing for the current plans, comparison table, and fee estimator.

Start here

After payment

Examples and reference

Hilt Pay API

Hilt Pay API

Current public scope

Route overview

How the protected-resource flow works

Create an app

Configure Solana USDC settlement

Create a product

Check setup readiness

Check durable access state

Create a payment session

Return and settle x402 V2

Consume metered usage

Submit proof when your flow needs it

Native subscriptions

Native subscription quickstart

Webhooks

Sandbox sessions

Agent setup

Pricing

​Hilt Pay API

​Current public scope

​Route overview

​How the protected-resource flow works

​Create an app

​Configure Solana USDC settlement

​Create a product

​Check setup readiness

​Check durable access state

​Create a payment session

​Return and settle x402 V2

​Consume metered usage

​Submit proof when your flow needs it

​Native subscriptions

​Native subscription quickstart

​Webhooks

​Sandbox sessions

​Agent setup

​Pricing

​Related docs

Hilt Pay API

Current public scope

Route overview

How the protected-resource flow works

Create an app

Configure Solana USDC settlement

Create a product

Check setup readiness

Check durable access state

Create a payment session

Return and settle x402 V2

Consume metered usage

Submit proof when your flow needs it

Native subscriptions

Native subscription quickstart

Webhooks

Sandbox sessions

Agent setup

Pricing

Related docs