Native subscriptions

How Native Solana Subscriptions Work in Hilt

A practical guide to Solana USDC subscriptions, on-chain recurring payments, stablecoin subscription billing, and how Hilt turns renewal collection into access.

5 June 2026Implementation guide

Native Solana subscriptions give Hilt merchants and Hilt Pay API developers a recurring access model without turning Hilt into a custodian or a card-style stored-payment processor.

The buyer approves a Solana USDC subscription once from their wallet. After that, successful collections extend the buyer's paid-through period and emit the same operating evidence as the first payment: payment confirmation, receipt, entitlement or membership update, webhook event, support context, and audit history.

That is why the product is more than on-chain recurring payments. Hilt turns stablecoin subscription billing into a usable business record that your API, community, SaaS product, dataset, or AI tool can trust at runtime.

Create a recurring product

Use billing_model: "recurring" and renewal_mode: "solana_native_subscription" so Hilt knows the product renews through native Solana USDC subscription setup.

Buyer approves once

The buyer completes checkout and signs the subscription approval from their wallet. Hilt records the initial payment and the subscription authorization context.

Successful collections extend access

Each successful collection creates payment confirmation, receipt state, entitlement or membership extension, webhook events, support context, and audit history.

Cancellation is period-aware

Future collection stops when cancellation is confirmed, while access can remain active until the paid-through date.

What Hilt records around a subscription

A subscription is useful only if the rest of the business can understand it. Hilt keeps the renewal mechanics connected to access, receipts, webhooks, support, analytics, and audit history.

Your app should not reconstruct recurring access from wallet history. Use Hilt's entitlement and subscription state as the source of truth for serving access.

recurring product and billing interval

buyer approval and native subscription authorization

initial payment and every successful collection

receipt and payment proof

member or entitlement paid-through date

webhook delivery trail

support context and audit history

1. Create a recurring product

For Hilt Pay API, make the billing model explicit. One-off products and recurring products are different modes with different checkout and entitlement behavior.

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-monthly-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
  }'

2. Start checkout and buyer approval

Create a payment session for the recurring product. The buyer completes the first payment and native subscription setup through the returned checkout or protocol handoff.

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-monthly-001" \
  -d '{
    "external_product_id": "pro-api-monthly",
    "external_customer_id": "cust_123",
    "rail": "solana_usdc"
  }'

3. Check access before serving

Entitlement state is the runtime gate. Your API, app, bot, or community should keep checking Hilt before serving the paid resource.

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-monthly",
    "external_customer_id": "cust_123"
  }'

4. Subscribe to renewal events

Use signed webhooks to keep your own product in sync after payments, renewals, expiries, and cancellation events. Verify signatures and process events idempotently.

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-recurring-access-001" \
  -d '{
    "label": "Recurring access sync",
    "url": "https://api.example.com/hilt/webhook",
    "subscribed_events": [
      "payment.confirmed",
      "receipt.created",
      "membership.activated",
      "membership.renewed",
      "membership.expired",
      "subscription.cancelled"
    ]
  }'

Cancellation preserves paid-through access

Native subscriptions are period-aware. When cancellation is confirmed, future collection stops. If the buyer has already paid for the current period and `immediate_revoke` is false, your product should keep access active until Hilt entitlement state says the paid-through period has ended.

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

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

Common mistakes to avoid

Stablecoin subscription billing is most reliable when the access model stays explicit. Keep payment, entitlement, subscription authorization, cancellation, and webhook state as separate records that Hilt connects for you.

Do not treat x402 as the settlement rail. x402 is the HTTP 402 protected-resource protocol shape.

Do not serve recurring access from a wallet signature alone. Check Hilt entitlement state.

Do not promise Base, EVM, or USDT settlement as live. Current public live settlement is Solana USDC.

Do not hide cancellation state. Keep paid-through access and future collection state separate.

Do not process webhook events without signature verification and idempotency.