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`, `GET /entitlements/{id}`	decide whether to serve a protected resource
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

Your product receives a request for a paid resource.
Your backend calls Hilt to check whether the customer has access.
If access is missing, your backend returns HTTP 402 Payment Required.
The 402 body includes the Hilt payment requirement or checkout handoff your flow supports.
The buyer or buyer-agent completes the Solana USDC payment path.
Hilt verifies the payment, records the receipt, updates entitlement state, and emits webhooks when live settlement succeeds.
The requester retries the resource.
Your backend serves the resource only after Hilt returns has_access: true.

The important rule is simple: do not grant access from a client claim or a raw transaction hash. Use the Hilt entitlement check.

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,
    "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 access before serving a resource

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"
}

If has_access is false, return HTTP 402 with the payment requirement or checkout handoff your flow supports. This call is the runtime access gate for paid APIs, AI tools, private datasets, bots, and agentic payment flows. Do not replace it 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 HTTP 402

Your API can return an x402-shaped Hilt payment requirement when your product is using the protected-resource protocol path:

{
  "error": "payment_required",
  "payment_protocol": "x402",
  "settlement_rail": "solana_usdc",
  "payment_session": {
    "id": "aps_123"
  },
  "payment_requirement": {
    "x402Version": 1,
    "accepts": [
      {
        "network": "solana:mainnet",
        "asset": "USDC",
        "payTo": "MERCHANT_SOLANA_PAYOUT_WALLET",
        "resource": "https://api.example.com/ai/pro"
      }
    ]
  }
}

The buyer or buyer-agent pays through the requirement or checkout handoff. Your product retries the entitlement check before serving access.

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 pricing for the current public pricing table.

​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 access before serving a resource

​Create a payment session

​Return HTTP 402

​Submit proof when your flow needs it

​Native subscriptions

​Native subscription quickstart

​Webhooks

​Sandbox sessions

​Agent setup

​Pricing

​Related docs