SDKs and Postman

Use this page when you want the fastest copy-paste path after Developer quickstart. Hilt publishes official public developer assets for the API:

TypeScript SDK
Python SDK
Postman collection
Postman environment

These assets describe the same supported public API contract as the developer docs, OpenAPI schema, examples, and agent-readable files. These stay aligned with the same public merchant routes documented elsewhere in Hilt docs:

products
hosted checkout
payments
Hilt Pay API
agent bootstrap and setup intents
rail settings and setup readiness
payment sessions, proof submission, and entitlement checks
memberships
receipts
support
webhooks

Common questions

Does Hilt publish official SDKs?

Yes. Hilt publishes official TypeScript and Python SDKs, plus Postman assets for teams that want to inspect the API before writing code.

Which SDK should I start with?

Use the TypeScript SDK for Node.js backends and frontend-adjacent tooling. Use the Python SDK for Python services, scripts, support automation, and data workflows.

Is Postman still useful if I use an SDK?

Yes. Postman is the fastest way to inspect object shapes, test authentication, send webhook test events, and compare API behavior before putting the call into code.

30-second SDK proof

If you only want to prove the published SDKs install and can talk to Hilt, use one of these smallest possible reads.

TypeScript

import { HiltClient } from "@hiltpay/sdk";

const client = new HiltClient({ apiKey: process.env.HILT_API_KEY! });
const products = await client.products.list();

console.log(products);

Python

import os
from hilt_sdk import HiltClient

client = HiltClient(api_key=os.environ["HILT_API_KEY"])
print(client.products.list())

Success looks like:

the package installs cleanly
auth works
the SDK returns the same products your workspace sees in Hilt

Representative output:

[
  {
    "id": "ae9673c8-95db-4b39-bc2c-b5e6d5dfd9d3",
    "slug": "example-slug",
    "title": "Hilt Quickstart Pay API",
    "status": "ACTIVE"
  }
]

Node `.env.local`

HILT_API_KEY=hk_live_...
HILT_MERCHANT_WALLET=So1anaMerchantWallet1111111111111111111111111

Python `.env`

HILT_API_KEY=hk_live_...
HILT_MERCHANT_WALLET=So1anaMerchantWallet1111111111111111111111111

TypeScript quickstart

Install

npm install @hiltpay/sdk

Source and releases:

npm: https://www.npmjs.com/package/@hiltpay/sdk
GitHub: https://github.com/Hiltpay/hilt-sdk-js

Copy-paste example

import { HiltClient } from "@hiltpay/sdk";

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

const product = await client.products.create({
  product_type: "PAYMENT_LINK",
  title: "SDK quickstart access",
  description: "One-off access from the TypeScript SDK",
  amount_minor_units: 29000000,
  token_mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  merchant_wallet: process.env.HILT_MERCHANT_WALLET!,
  delivery_type: "REDIRECT",
  delivery_value: "https://example.com/hilt/thanks",
  membership_config: {
    enabled: true,
    platform: "CUSTOM",
    identity_type: "WALLET",
    identity_required: false,
    renewal_mode: "ONE_OFF",
    billing_interval_days: 30,
    grace_period_days: 3,
  },
});

const checkout = await client.checkout.getProduct(product.slug);

console.log({
  productId: product.id,
  slug: product.slug,
  title: checkout.title,
});

Expected result:

one active product in Hilt
one reusable product.id
one reusable slug
one buyer-facing checkout payload you can compare against the dashboard

Hilt Pay API durable entitlement check

import { HiltClient } from "@hiltpay/sdk";

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

const entitlement = await client.payApi.checkEntitlement({
  external_product_id: "pro-ai-api",
  rail: "solana_usdc",
  external_customer_id: "cust_123",
});

if (!entitlement.has_access) {
  throw new Error(`Payment required: ${entitlement.reason}`);
}

Use checkEntitlement for durable or time-based access display and planning. For each metered request, use atomic consumption instead:

const consumption = await client.payApi.consumeEntitlement(
  {
    external_product_id: "pro-ai-api",
    external_customer_id: "cust_123",
    units: 1,
    metadata: { request_id: "req_01J..." },
  },
  { idempotencyKey: "consume-req_01J..." },
);

if (!consumption.consumed) throw new Error("Payment required");

Hilt Pay API payment session

import { HiltClient } from "@hiltpay/sdk";

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

const session = await client.payApi.createPaymentSession(
  {
    external_product_id: "pro-ai-api",
    external_customer_id: "cust_123",
    rail: "solana_usdc",
    metadata: {
      resource: "https://api.example.com/ai/pro",
    },
  },
  "session-cust-123-pro-ai-api-001",
);

const checkoutUrl = session.payment_session?.checkout_url;
const paymentRequirement = session.payment_session?.payment_requirement;

console.log({ checkoutUrl, paymentRequirement });

Use checkoutUrl for hosted Solana USDC checkout. Use paymentRequirement only when Hilt returns one for the protected-resource protocol path.

Settle an x402 V2 paid retry

When a buyer retries your protected resource with PAYMENT-SIGNATURE, settle it through Hilt before consuming the metered unit:

const settled = await client.payApi.settleX402(
  {
    payment_session_id: "hpa_x402_...",
    payment_signature: paymentSignature,
  },
  { idempotencyKey: "settle-req_01J..." },
);

const paymentResponse = settled.headers["PAYMENT-RESPONSE"];

Relay PAYMENT-RESPONSE to the buyer, atomically consume one unit with the same logical request id, and serve only after both operations succeed.

Hilt Pay API agent bootstrap

import { HiltClient } from "@hiltpay/sdk";

const client = new HiltClient();

const setup = await client.payApi.agentBootstrap({
  agent_name: "Acme API Builder",
  agent_platform: "cursor",
  requested_use_case: "Protect /ai/pro with Hilt Pay API",
  requested_permissions: ["access:read", "access:write", "access:webhooks"],
  ttl_hours: 24,
});

console.log(setup.setup_intent_id, setup.owner_approval_url);

Python quickstart

Install

pip install hilt-sdk

Source and releases:

PyPI: https://pypi.org/project/hilt-sdk/
GitHub: https://github.com/Hiltpay/hilt-sdk-python

Copy-paste example

import os
from hilt_sdk import HiltClient

client = HiltClient(api_key=os.environ["HILT_API_KEY"])

product = client.products.create(
    {
        "product_type": "PAYMENT_LINK",
        "title": "Python quickstart access",
        "description": "One-off access from the Python SDK",
        "amount_minor_units": 29000000,
        "token_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "merchant_wallet": os.environ["HILT_MERCHANT_WALLET"],
        "delivery_type": "REDIRECT",
        "delivery_value": "https://example.com/hilt/thanks",
        "membership_config": {
            "enabled": True,
            "platform": "CUSTOM",
            "identity_type": "WALLET",
            "identity_required": False,
            "renewal_mode": "ONE_OFF",
            "billing_interval_days": 30,
            "grace_period_days": 3,
        },
    }
)

receipts = client.receipts.list({"page": 1, "per_page": 5, "product_id": product["id"]})

print({
    "product_id": product["id"],
    "slug": product["slug"],
    "receipt_count": receipts["total"],
})

Expected result:

one product created from Python
one clean product["id"]
one repeatable receipts query for later proof handling

Hilt Pay API durable entitlement check

import os
from hilt_sdk import HiltClient

client = HiltClient(api_key=os.environ["HILT_API_KEY"])

entitlement = client.pay_api.check_entitlement(
    {
        "external_product_id": "pro-ai-api",
        "rail": "solana_usdc",
        "external_customer_id": "cust_123",
    }
)

if not entitlement["has_access"]:
    raise RuntimeError(f"Payment required: {entitlement['reason']}")

Use check_entitlement for durable or time-based access display and planning. For metered work:

consumption = client.pay_api.consume_entitlement(
    {
        "external_product_id": "pro-ai-api",
        "external_customer_id": "cust_123",
        "units": 1,
        "metadata": {"request_id": "req_01J..."},
    },
    idempotency_key="consume-req_01J...",
)

if not consumption["consumed"]:
    raise RuntimeError("Payment required")

Hilt Pay API payment session

import os
from hilt_sdk import HiltClient

client = HiltClient(api_key=os.environ["HILT_API_KEY"])

session = client.pay_api.create_payment_session(
    {
        "external_product_id": "pro-ai-api",
        "external_customer_id": "cust_123",
        "rail": "solana_usdc",
        "metadata": {
            "resource": "https://api.example.com/ai/pro",
        },
    },
    idempotency_key="session-cust-123-pro-ai-api-001",
)

payment_session = session.get("payment_session", {})
checkout_url = payment_session.get("checkout_url")
payment_requirement = payment_session.get("payment_requirement")

print({"checkout_url": checkout_url, "payment_requirement": payment_requirement})

Use the returned Hilt session state to build the 402 response or hosted checkout handoff.

Settle an x402 V2 paid retry

settled = client.pay_api.settle_x402(
    {
        "payment_session_id": "hpa_x402_...",
        "payment_signature": payment_signature,
    },
    idempotency_key="settle-req_01J...",
)

payment_response = settled["headers"]["PAYMENT-RESPONSE"]

Relay PAYMENT-RESPONSE, atomically consume one unit with the same logical request id, and serve only after both operations succeed.

Sandbox session helpers

Use sandbox sessions to validate SDK, webhook, receipt, and entitlement handling without live money. TypeScript:

const sandbox = await client.payApi.createSandboxPaymentSession(
  {
    external_product_id: "pro-ai-api",
    external_customer_id: "cust_123",
    rail: "solana_usdc",
    confirm_sandbox_mode: true,
  },
  { idempotencyKey: "sandbox-session-cust-123-pro-ai-api-001" },
);

if (!sandbox.payment_session?.id) {
  throw new Error("Sandbox session id missing from Hilt response");
}

await client.payApi.confirmSandboxPaymentSession(
  sandbox.payment_session.id,
  { proof: "sandbox-confirmed-access" },
  { idempotencyKey: "sandbox-confirm-cust-123-pro-ai-api-001" },
);

Python:

sandbox = client.pay_api.create_sandbox_payment_session(
    {
        "external_product_id": "pro-ai-api",
        "external_customer_id": "cust_123",
        "rail": "solana_usdc",
        "confirm_sandbox_mode": True,
    },
    idempotency_key="sandbox-session-cust-123-pro-ai-api-001",
)

client.pay_api.confirm_sandbox_payment_session(
    sandbox["payment_session"]["id"],
    {"proof": "sandbox-confirmed-access"},
    idempotency_key="sandbox-confirm-cust-123-pro-ai-api-001",
)

Webhook helpers

Both SDKs include raw-body verification helpers for Hilt webhooks. Hilt signs <timestamp>.<raw_json_body> and sends X-Hilt-Signature as t=<unix_timestamp>,v1=<hex_hmac_sha256>. TypeScript:

import { constructWebhookEvent, createWebhookRouter } from "@hiltpay/sdk";

const router = createWebhookRouter()
  .on("payment.confirmed", async (event) => {
    await grantAccess(event.data);
  })
  .on("membership.expired", async (event) => {
    await removeAccess(event.data);
  });

const event = await constructWebhookEvent(
  rawBody,
  request.headers.get("X-Hilt-Signature"),
  process.env.HILT_WEBHOOK_SECRET!,
);

await router.dispatch(event);

Python:

from hilt_sdk import construct_webhook_event, create_webhook_router

router = create_webhook_router()


@router.on("payment.confirmed")
async def grant_access(event):
    await sync_access(event["data"])


event = construct_webhook_event(
    raw_body,
    request.headers.get("X-Hilt-Signature"),
    HILT_WEBHOOK_SECRET,
)
await router.dispatch(event)

Error handling

Both SDKs raise HiltApiError for non-2xx API responses. The error includes:

code
statusCode or status_code
requestId or request_id
retryable
docsUrl or docs_url
safe response body details

Use the Errors and status handling catalog for recommended action by code. SDK docs URLs point to anchors such as /developers/errors#payment-failed, /developers/errors#idempotency-in-progress, and /developers/errors#request-timeout. TypeScript:

import { HiltApiError } from "@hiltpay/sdk";

try {
  await client.payApi.createPaymentSession(body, { idempotencyKey: "session-001" });
} catch (error) {
  if (error instanceof HiltApiError) {
    console.error(error.code, error.statusCode, error.requestId, error.retryable);
  }
}

Python:

from hilt_sdk import HiltApiError

try:
    client.pay_api.create_payment_session(body, idempotency_key="session-001")
except HiltApiError as exc:
    print(exc.code, exc.status_code, exc.request_id, exc.retryable)

Subscription helper boundary

The SDKs expose the current public native subscription routes:

read a native subscription authorization
create a cancellation intent
confirm the signed cancellation

Public endpoints for list, pause, resume, and browser-safe customer management sessions are not exposed yet, so the SDKs do not fake those methods. Build recurring access today with a recurring product, a payment session, signed webhooks, and entitlement checks. Proposed backend contract for future high-level subscription helpers:

POST /v1/access/subscriptions
GET  /v1/access/subscriptions/{subscription_id}
GET  /v1/access/subscriptions
POST /v1/access/subscriptions/{subscription_id}/pause
POST /v1/access/subscriptions/{subscription_id}/resume
POST /v1/access/subscriptions/{subscription_id}/cancel
POST /v1/access/customer-sessions
POST /v1/access/sandbox/subscriptions/{subscription_id}/advance-period

The browser-facing contract should return only a short-lived customer token or hosted management URL. It must never expose a Hilt API key in browser code.

Hilt Pay API agent bootstrap

from hilt_sdk import HiltClient

client = HiltClient()

setup = client.pay_api.agent_bootstrap(
    {
        "agent_name": "Acme API Builder",
        "agent_platform": "cursor",
        "requested_use_case": "Protect /ai/pro with Hilt Pay API",
        "requested_permissions": ["access:read", "access:write", "access:webhooks"],
        "ttl_hours": 24,
    }
)

print(setup["setup_intent_id"], setup["owner_approval_url"])

Postman quickstart

Use the public developer-assets repo for the mirrored machine-readable assets:

https://github.com/Hiltpay/hilt-developer-assets

Import:

postman/hilt-postman-collection.json
postman/hilt-postman-environment.json

Set these environment variables

The shipped environment already includes these keys:

baseUrl
apiKey
bearerToken
merchantWallet
productId
slug
paymentId
payApiAppId
payApiProductId
membershipId
receiptId
endpointId

Run these requests in order

Products -> Create product
Hilt Pay API -> List Pay API rails
Hilt Pay API -> Create agent bootstrap
Hilt Pay API -> Submit setup manifest
Hilt Pay API -> Check setup readiness
Hilt Pay API -> Settle x402 V2 payment
Hilt Pay API -> Consume metered entitlement
Hilt Pay API -> Check durable entitlement
Webhooks -> Create webhook endpoint
Webhooks -> Send test event
Testing -> Create sandbox session

What you should capture as you go:

productId
slug
endpointId
fake sandbox ids such as fake_payment_id and fake_receipt_id

Why Postman is useful here

Postman is the fastest way to verify:

your auth surfaces are correct
the public API matches the docs
webhook endpoint management works with a bearer token
sandbox responses match the object shapes your application expects

Contract and fallback assets

The supported public developer surface is represented by:

these developer docs
the TypeScript SDK
the Python SDK
the Postman collection and environment
approved snapshots in the developer-assets repo

For Hilt Pay API, the contract must also preserve:

the /v1/access implementation namespace
solana_usdc as the first production settlement rail
x402 as the 402 Payment Required protocol shape for protected-resource flows
scoped API keys for server and agent integrations
receipt, entitlement, webhook, and audit retrieval through API

If you want Hilt-hosted fallback imports instead of GitHub:

https://www.hilt.so/downloads/hilt-postman-collection-latest.json
https://www.hilt.so/downloads/hilt-postman-environment-latest.json

If you want a Hilt-hosted Python package artifact instead of PyPI:

https://www.hilt.so/downloads/hilt_sdk-1.2.0-py3-none-any.whl

Auth surfaces

For most merchant requests in the SDKs and Postman collection, use:

X-Hilt-Key: hk_live_...

Webhook endpoint management currently requires a dashboard session token:

Authorization: Bearer JWT_TOKEN

That is why the webhook methods in the SDKs and the webhook requests in the Postman collection use the bearer-token surface instead of an API key.

What to do after the SDK quickstart

run a signed test webhook event
create one sandbox session
check setup readiness before live traffic
verify payment, membership, receipt, and delivery state afterwards

For that exact flow, go back to Developer quickstart and Testing and going live.

Start here

After payment

Examples and reference

SDKs and Postman

SDKs and Postman

Common questions

Does Hilt publish official SDKs?

Which SDK should I start with?

Is Postman still useful if I use an SDK?

30-second SDK proof

TypeScript

Python

Node `.env.local`

Python `.env`

TypeScript quickstart

Install

Copy-paste example

Hilt Pay API durable entitlement check

Hilt Pay API payment session

Settle an x402 V2 paid retry

Hilt Pay API agent bootstrap

Python quickstart

Install

Copy-paste example

Hilt Pay API durable entitlement check

Hilt Pay API payment session

Settle an x402 V2 paid retry

Sandbox session helpers

Webhook helpers

Error handling

Subscription helper boundary

Hilt Pay API agent bootstrap

Postman quickstart

Set these environment variables

Run these requests in order

Why Postman is useful here

Contract and fallback assets

Auth surfaces

What to do after the SDK quickstart

​SDKs and Postman

​Common questions

​Does Hilt publish official SDKs?

​Which SDK should I start with?

​Is Postman still useful if I use an SDK?

​30-second SDK proof

​TypeScript

​Python

​Node .env.local

​Python .env

​TypeScript quickstart

​Install

​Copy-paste example

​Hilt Pay API durable entitlement check

​Hilt Pay API payment session

​Settle an x402 V2 paid retry

​Hilt Pay API agent bootstrap

​Python quickstart

​Install

​Copy-paste example

​Hilt Pay API durable entitlement check

​Hilt Pay API payment session

​Settle an x402 V2 paid retry

​Sandbox session helpers

​Webhook helpers

​Error handling

​Subscription helper boundary

​Hilt Pay API agent bootstrap

​Postman quickstart

​Set these environment variables

​Run these requests in order

​Why Postman is useful here

​Contract and fallback assets

​Auth surfaces

​What to do after the SDK quickstart

SDKs and Postman

Common questions

Does Hilt publish official SDKs?

Which SDK should I start with?

Is Postman still useful if I use an SDK?

30-second SDK proof

TypeScript

Python

Node `.env.local`

Python `.env`

TypeScript quickstart

Install

Copy-paste example

Hilt Pay API durable entitlement check

Hilt Pay API payment session

Settle an x402 V2 paid retry

Hilt Pay API agent bootstrap

Python quickstart

Install

Copy-paste example

Hilt Pay API durable entitlement check

Hilt Pay API payment session

Settle an x402 V2 paid retry

Sandbox session helpers

Webhook helpers

Error handling

Subscription helper boundary

Hilt Pay API agent bootstrap

Postman quickstart

Set these environment variables

Run these requests in order

Why Postman is useful here

Contract and fallback assets

Auth surfaces

What to do after the SDK quickstart