Examples

Use this page when you want end-to-end starting points rather than route-by-route explanation.

Base URLs

Marketing site:  https://www.hilt.so
Merchant app:    https://app.hilt.so
API:             https://api.hilt.so
Docs:            https://docs.hilt.so

Auth patterns

Server-side merchant automation normally uses:

X-Hilt-Key: hk_live_...

Session-assisted merchant tools can use:

Authorization: Bearer JWT_TOKEN

Runnable Grok Build and Next.js example

Use the public example when you want a complete protected-resource application rather than isolated request snippets:

Guide: https://docs.hilt.so/developers/grok-build
Source: https://github.com/Hiltpay/hilt-developer-assets/tree/main/examples/grok-build-nextjs

It includes a protected Next.js route, Hilt entitlement checks, HTTP 402 responses, local and Hilt sandbox validation, live Hilt Pay API mode, raw-body webhook verification, tests, AGENTS.md, and a Grok project skill. The example keeps Hilt keys and sandbox proofs on the server. It serves protected content only after entitlement is active.

Example 1: Create a hosted access product

cURL

curl -X POST https://api.hilt.so/v1/products \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_type": "PAYMENT_LINK",
    "title": "Members lounge",
    "description": "Monthly access",
    "amount_minor_units": 200000,
    "token_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "merchant_wallet": "So1anaMerchantWallet1111111111111111111111111",
    "delivery_type": "REDIRECT",
    "delivery_value": "https://example.com/welcome",
    "membership_config": {
      "enabled": true,
      "platform": "CUSTOM",
      "identity_type": "WALLET",
      "identity_required": false,
      "renewal_mode": "ONE_OFF",
      "billing_interval_days": 30,
      "grace_period_days": 3
    }
  }'

TypeScript

const response = await fetch("https://api.hilt.so/v1/products", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Hilt-Key": process.env.HILT_API_KEY!,
  },
  body: JSON.stringify({
    product_type: "PAYMENT_LINK",
    title: "Discord membership",
    description: "Monthly paid access",
    amount_minor_units: 29000000,
    token_mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    merchant_wallet: "So1anaMerchantWallet1111111111111111111111111",
    delivery_type: "DISCORD_INVITE",
    delivery_value: "https://discord.gg/example",
    membership_config: {
      enabled: true,
      platform: "DISCORD",
      identity_type: "DISCORD_USER_ID",
      renewal_mode: "ONE_OFF",
      billing_interval_days: 30,
      grace_period_days: 3,
    },
  }),
});

if (!response.ok) {
  const error = await response.json().catch(() => ({}));
  throw new Error(error.detail ?? `Hilt request failed: ${response.status}`);
}

const product = await response.json();
console.log(product.id, product.slug);

Set renewal_mode to ONE_OFF for single-payment products. Use native subscription setup for recurring products when the workspace has been enabled for it.

Official SDKs and Postman

If you want a faster start than hand-written fetch or requests, use the official developer assets:

TypeScript SDK: npm install @hiltpay/sdk
TypeScript SDK source: https://github.com/Hiltpay/hilt-sdk-js
Python SDK: pip install hilt-sdk
Python SDK source: https://github.com/Hiltpay/hilt-sdk-python
Developer assets repo: https://github.com/Hiltpay/hilt-developer-assets

The SDKs wrap the same examples shown below. The developer-assets repo carries public OpenAPI snapshots, Postman imports, and example webhook payloads for products, checkout, payments, memberships, receipts, support, and webhooks.

Example 2: Protect an AI API endpoint with Hilt Pay API

This is the metered Hilt Pay API runtime. Atomically consume one usage unit before billable work. When no unit is available, return HTTP 402 Payment Required with Hilt’s x402 V2 PAYMENT-REQUIRED header. On the paid retry, settle PAYMENT-SIGNATURE through Hilt, consume one unit, and serve. Solana USDC is the live settlement rail.

FastAPI

import os
from fastapi import FastAPI, Header, Request, Response
from fastapi.responses import JSONResponse
from hilt_sdk import (
    HiltApiError,
    HiltClient,
    PAYMENT_REQUIRED_HEADER,
    PAYMENT_RESPONSE_HEADER,
    PAYMENT_SIGNATURE_HEADER,
    decode_x402_header,
)

app = FastAPI()
hilt = HiltClient(api_key=os.environ["HILT_API_KEY"])
PRODUCT = "pro-ai-api"


@app.post("/ai/pro")
def pro_endpoint(
    request: Request,
    response: Response,
    x_customer_id: str = Header(...),
    x_request_id: str = Header(...),
    payment_signature: str | None = Header(None, alias=PAYMENT_SIGNATURE_HEADER),
):
    payment_response = None
    if payment_signature:
        payload = decode_x402_header(payment_signature)
        session_id = payload["accepted"]["extra"]["hilt"]["paymentSessionId"]
        settled = hilt.pay_api.settle_x402(
            {"payment_session_id": session_id, "payment_signature": payment_signature},
            idempotency_key=f"settle-{x_request_id}",
        )
        payment_response = settled["headers"][PAYMENT_RESPONSE_HEADER]

    try:
        consumption = hilt.pay_api.consume_entitlement(
            {
                "external_product_id": PRODUCT,
                "external_customer_id": x_customer_id,
                "units": 1,
                "metadata": {"request_id": x_request_id},
            },
            idempotency_key=f"consume-{x_request_id}",
        )
    except HiltApiError as error:
        if error.error_code not in {
            "entitlement_not_found",
            "entitlement_not_active",
            "usage_balance_insufficient",
        }:
            raise
        session = hilt.pay_api.create_payment_session(
            {
                "external_product_id": PRODUCT,
                "external_customer_id": x_customer_id,
                "payment_protocol": "x402",
                "settlement_rail": "solana_usdc",
                "metadata": {"resource": str(request.url)},
            },
            idempotency_key=f"payment-{x_request_id}",
        )
        payment_session = session["payment_session"]
        required = payment_session["payment_requirement"]["headers"][PAYMENT_REQUIRED_HEADER]
        return JSONResponse(
            {"error": "payment_required", "payment_session": payment_session},
            status_code=402,
            headers={PAYMENT_REQUIRED_HEADER: required, "Cache-Control": "no-store"},
        )

    if payment_response:
        response.headers[PAYMENT_RESPONSE_HEADER] = payment_response
    return {"result": "paid work can run", "consumption": consumption}

The complete runnable FastAPI example includes local no-money simulation, retry-idempotency tests, and webhook verification: examples/hilt-access-fastapi in the developer-assets repository.

Node and Express

import { HiltApiError, HiltClient, type HiltX402PaymentPayload } from "@hiltpay/sdk";
import {
  decodeX402Header,
  PAYMENT_REQUIRED_HEADER,
  PAYMENT_RESPONSE_HEADER,
  PAYMENT_SIGNATURE_HEADER,
} from "@hiltpay/sdk/x402";

const hilt = new HiltClient({ apiKey: process.env.HILT_API_KEY! });

app.post("/ai/pro", async (req, res, next) => {
  const customerId = req.header("x-customer-id");
  const requestId = req.header("x-request-id");
  if (!customerId || !requestId) return res.status(400).end();

  try {
    const signature = req.header(PAYMENT_SIGNATURE_HEADER);
    let paymentResponse: string | undefined;
    if (signature) {
      const payload = decodeX402Header<HiltX402PaymentPayload>(signature);
      const sessionId = payload.accepted.extra?.hilt?.paymentSessionId;
      if (!sessionId) throw new Error("PAYMENT-SIGNATURE is not bound to Hilt");
      const settled = await hilt.payApi.settleX402(
        { payment_session_id: sessionId, payment_signature: signature },
        { idempotencyKey: `settle-${requestId}` },
      );
      paymentResponse = settled.headers[PAYMENT_RESPONSE_HEADER];
    }

    try {
      const consumption = await hilt.payApi.consumeEntitlement(
        {
          external_product_id: "pro-ai-api",
          external_customer_id: customerId,
          units: 1,
          metadata: { request_id: requestId },
        },
        { idempotencyKey: `consume-${requestId}` },
      );
      if (paymentResponse) res.setHeader(PAYMENT_RESPONSE_HEADER, paymentResponse);
      return res.json({ result: "paid work can run", consumption });
    } catch (error) {
      const paymentNeeded =
        error instanceof HiltApiError &&
        ["entitlement_not_found", "entitlement_not_active", "usage_balance_insufficient"].includes(
          error.errorCode ?? "",
        );
      if (!paymentNeeded) throw error;
    }

    const session = await hilt.payApi.createPaymentSession(
      {
        external_product_id: "pro-ai-api",
        external_customer_id: customerId,
        payment_protocol: "x402",
        settlement_rail: "solana_usdc",
        metadata: { resource: `${req.protocol}://${req.get("host")}${req.originalUrl}` },
      },
      { idempotencyKey: `payment-${requestId}` },
    );
    const paymentSession = session.payment_session!;
    const requirement = paymentSession.payment_requirement as Record<string, unknown>;
    const headers = requirement.headers as Record<string, string>;
    res.setHeader(PAYMENT_REQUIRED_HEADER, headers[PAYMENT_REQUIRED_HEADER]);
    return res.status(402).json({ error: "payment_required", payment_session: paymentSession });
  } catch (error) {
    return next(error);
  }
});

Use the same rule in every framework:

atomically consume one unit before billable work
return 402 with Hilt’s PAYMENT-REQUIRED header when usage is missing
let the buyer pay and retry with PAYMENT-SIGNATURE
settle the signature through Hilt
atomically consume one unit and serve only after consumption succeeds

POST /v1/access/entitlements/check is useful for durable or time-based access display and planning. It is not the authority for a billable metered request.

Example 3: Create a signed handoff link

Use this when your own bot or backend already knows who the buyer is before checkout.

curl -X POST https://api.hilt.so/v1/products/PRODUCT_ID/handoff-link \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identity_type": "TELEGRAM_USER_ID",
    "identity_value": "728255790",
    "identity_display": "@buyer",
    "expires_in_minutes": 30
  }'

Representative response:

{
  "handoff_token": "hilt_handoff_...",
  "expires_at": "2026-04-16T18:30:00Z",
  "checkout_url": "https://www.hilt.so/p/example-slug?handoff=hilt_handoff_..."
}

Example 4: Start a buyer session and keep the payment id

cURL

curl -X POST https://api.hilt.so/v1/products/p/example-slug/connect \
  -H "Content-Type: application/json" \
  -d '{
    "payer_wallet": "BuyerWallet1111111111111111111111111111111111"
  }'

What to keep from the response

Persist:

payment_id
amount_minor_units
merchant_amount_minor_units
asset_symbol
expires_at

Example 5: Poll payment status during an active buyer session

cURL

curl https://api.hilt.so/v1/payments/PAYMENT_ID

TypeScript

type PaymentStatus = {
  id: string;
  product_id: string;
  status: string;
  tx_signature?: string | null;
  delivery_status?: string | null;
};

async function getPayment(paymentId: string): Promise<PaymentStatus> {
  const response = await fetch(`https://api.hilt.so/v1/payments/${paymentId}`);
  if (!response.ok) {
    throw new Error(`Unable to read payment ${paymentId}: ${response.status}`);
  }
  return response.json();
}

const payment = await getPayment("f0f4e620-1ca3-4fc8-b0ba-2d04342fe467");

switch (payment.status) {
  case "CONFIRMED":
    console.log("ready for member lookup");
    break;
  case "PENDING_CONFIRMATION":
    console.log("keep waiting with the same payment_id");
    break;
  default:
    console.log("current status:", payment.status);
}

Use this when the buyer is still waiting on the checkout screen. For longer-running automation after checkout, prefer Hilt webhooks.

Python

import requests

def get_payment(payment_id: str):
    response = requests.get(
        f"https://api.hilt.so/v1/payments/{payment_id}",
        timeout=20,
    )
    response.raise_for_status()
    return response.json()

payment = get_payment("f0f4e620-1ca3-4fc8-b0ba-2d04342fe467")
print(payment["status"], payment.get("tx_signature"))

Rust

use reqwest::Client;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Payment {
    id: String,
    status: String,
    tx_signature: Option<String>,
}

async fn get_payment(payment_id: &str) -> Result<Payment, reqwest::Error> {
    let client = Client::new();
    client
        .get(format!("https://api.hilt.so/v1/payments/{payment_id}"))
        .send()
        .await?
        .error_for_status()?
        .json::<Payment>()
        .await
}

Example 6: Read the post-payment trail

Look up a membership

curl "https://api.hilt.so/v1/memberships/lookup?identity=@buyer" \
  -H "X-Hilt-Key: hk_live_..."

Read receipts in Python

import requests

response = requests.get(
    "https://api.hilt.so/v1/receipts",
    headers={"X-Hilt-Key": "hk_live_..."},
    params={"page": 1, "per_page": 20},
    timeout=20,
)
response.raise_for_status()
print(response.json())

Example 7: Open a support ticket

curl -X POST https://api.hilt.so/v1/support/tickets \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Buyer needs help",
    "category": "OTHER",
    "body": "Payment confirmed, but the buyer still needs a manual handoff."
  }'

Example 8: Continue a support thread

curl -X POST https://api.hilt.so/v1/support/tickets/hilt_ticket_R64eNsqH_nntOg/message \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "body": "We retried delivery and confirmed the membership is active."
  }'

Example 9: Webhook consumer after checkout

If your application already has queue workers or background automation, native webhooks are now the cleanest Hilt integration.

TypeScript

async function handleHiltWebhook(event: {
  id: string;
  type: string;
  data: {
    payment?: { id: string; status: string };
    membership?: { id: string; status: string };
    receipt?: { id: string };
  };
}) {
  if (await alreadyProcessed(event.id)) {
    return;
  }

  if (event.type === "payment.confirmed") {
    await unlockAccessFromPayment(event.data.payment?.id);
    await markProcessed(event.id);
    return;
  }

  if (event.type === "payment.failed") {
    await markCheckoutFailed(event.data.payment?.id);
    await markProcessed(event.id);
  }
}

Python

def handle_hilt_webhook(event: dict) -> None:
    if already_processed(event["id"]):
        return

    if event["type"] == "payment.confirmed":
        unlock_access_from_payment(event["data"]["payment"]["id"])
        mark_processed(event["id"])
        return

    if event["type"] == "payment.failed":
        mark_checkout_failed(event["data"]["payment"]["id"])
        mark_processed(event["id"])

Example rule of thumb

The simplest reliable pattern is:

let Hilt run checkout and settlement
keep the payment_id
let your backend react to webhook events afterwards
read GET /v1/payments/{payment_id} only when the buyer is actively waiting or you need a fallback check

That is usually cleaner than rebuilding the payment, membership, receipt, and support state machine yourself.

Common questions

Which Hilt example should I copy first?

Start with product creation, then signed handoff or checkout session start, then payment status, then webhook handling.

Do the examples replace the SDKs?

No. The examples show the underlying API patterns. Use the SDKs when you want typed helpers and less hand-written request code.

What is the safest example pattern?

Let Hilt run hosted checkout and settlement, store payment_id, and react to signed webhook events after checkout.

Start here

After payment

Examples and reference

Examples

Examples

Base URLs

Auth patterns

Runnable Grok Build and Next.js example

Example 1: Create a hosted access product

cURL

TypeScript

Official SDKs and Postman

Example 2: Protect an AI API endpoint with Hilt Pay API

FastAPI

Node and Express

Example 3: Create a signed handoff link

Example 4: Start a buyer session and keep the payment id

cURL

What to keep from the response

Example 5: Poll payment status during an active buyer session

cURL

TypeScript

Python

Rust

Example 6: Read the post-payment trail

Look up a membership

Read receipts in Python

Example 7: Open a support ticket

Example 8: Continue a support thread

Example 9: Webhook consumer after checkout

TypeScript

Python

Example rule of thumb

Common questions

Which Hilt example should I copy first?

Do the examples replace the SDKs?

What is the safest example pattern?

​Examples

​Base URLs

​Auth patterns

​Runnable Grok Build and Next.js example

​Example 1: Create a hosted access product

​cURL

​TypeScript

​Official SDKs and Postman

​Example 2: Protect an AI API endpoint with Hilt Pay API

​FastAPI

​Node and Express

​Example 3: Create a signed handoff link

​Example 4: Start a buyer session and keep the payment id

​cURL

​What to keep from the response

​Example 5: Poll payment status during an active buyer session

​cURL

​TypeScript

​Python

​Rust

​Example 6: Read the post-payment trail

​Look up a membership

​Read receipts in Python

​Example 7: Open a support ticket

​Example 8: Continue a support thread

​Example 9: Webhook consumer after checkout

​TypeScript

​Python

​Example rule of thumb

​Common questions

​Which Hilt example should I copy first?

​Do the examples replace the SDKs?

​What is the safest example pattern?

Examples

Base URLs

Auth patterns

Runnable Grok Build and Next.js example

Example 1: Create a hosted access product

cURL

TypeScript

Official SDKs and Postman

Example 2: Protect an AI API endpoint with Hilt Pay API

FastAPI

Node and Express

Example 3: Create a signed handoff link

Example 4: Start a buyer session and keep the payment id

cURL

What to keep from the response

Example 5: Poll payment status during an active buyer session

cURL

TypeScript

Python

Rust

Example 6: Read the post-payment trail

Look up a membership

Read receipts in Python

Example 7: Open a support ticket

Example 8: Continue a support thread

Example 9: Webhook consumer after checkout

TypeScript

Python

Example rule of thumb

Common questions

Which Hilt example should I copy first?

Do the examples replace the SDKs?

What is the safest example pattern?