Protect an endpoint

Put billable work behind Hilt Pay API without building the HTTP 402, settlement, receipt, entitlement, and atomic-consumption loop yourself. The TypeScript SDK’s protectEndpoint wrapper works with Fetch-compatible server handlers, including Next.js App Router routes, workers, and modern Node server frameworks.

Before you start

You need:

a server-side Hilt API key with access:read and access:write
an active Hilt Pay API product using solana_usdc
usage_unit set to the thing you sell, such as request
usage_units_per_payment set to the number of calls each payment buys

Hilt x402 V2 currently settles in Solana USDC. Native SOL is available for hosted Hilt Pay API payment sessions, not x402.

Install the SDK

npm install @hiltpay/sdk

Wrap the route

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

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

export const POST = protectEndpoint({
  client: hilt,
  externalProductId: "research-calls",
  resourceDescription: "One research request",
  handler: async (request, { customerId, usage }) => {
    const input = await request.json();
    const result = await runResearch(input);

    return Response.json({
      result,
      customer_id: customerId,
      units_remaining: usage.usage.remaining,
    });
  },
});

Only code inside handler is served as billable work. The Hilt API key remains on your server and Hilt does not proxy the request body or paid result.

Python services

The Python SDK exposes the same decision boundary without requiring a specific web framework:

from hilt_sdk import HiltClient, protect_request

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

decision = protect_request(
    client=hilt,
    external_product_id="research-calls",
    customer_id=request.headers["X-Agent-Id"],
    request_id=request.headers["X-Request-Id"],
    resource_url=str(request.url),
    payment_signature=request.headers.get("PAYMENT-SIGNATURE"),
)

if not decision.allowed:
    return JSONResponse(
        decision.body,
        status_code=decision.status_code,
        headers=decision.headers,
    )

return run_paid_research()

Use the returned status, body, and headers unchanged when allowed is false. Run billable work only when allowed is true.

Send stable identities

Every caller must send:

one customer header: X-Hilt-Customer-Id, X-Customer-Id, or X-Agent-Id
one request header: Idempotency-Key, X-Request-Id, or X-Hilt-Request-Id

The request ID must contain at least eight characters. Reuse the same customer and request IDs when retrying the same billable operation. Use a new request ID for new work.

POST /research HTTP/1.1
X-Agent-Id: agent-42
X-Request-Id: req-01K4W8RQ6M
Content-Type: application/json

Custom identity resolvers are available when your application already has authenticated users:

export const POST = protectEndpoint({
  client: hilt,
  externalProductId: "research-calls",
  getCustomerId: async (request) => (await readSession(request)).accountId,
  getRequestId: (request) => request.headers.get("Idempotency-Key"),
  handler: async () => Response.json(await runPaidWork()),
});

What the wrapper does

For every request, the wrapper:

resolves the customer and stable request ID
atomically consumes the configured usage units
returns HTTP 402 with Hilt’s PAYMENT-REQUIRED header when usage is missing
accepts the buyer’s PAYMENT-SIGNATURE on the retry
settles the Hilt-bound Solana USDC payment
atomically consumes usage and then runs your handler
relays Hilt’s PAYMENT-RESPONSE header with the protected result

Hilt records settlement evidence, a receipt, entitlement state, usage, and applicable webhook events. Reusing the request ID keeps settlement and consumption retry-safe. One payment can grant many usage units. Requests consume those prepaid units without requiring a new on-chain transaction each time; the next 402 appears only when the balance is exhausted or access is otherwise unavailable.

Buyer behavior

The buyer or buyer agent calls your endpoint, validates the returned payment terms, signs the advertised Solana USDC transaction, and retries your endpoint with PAYMENT-SIGNATURE. The buyer does not receive your Hilt API key and does not call Hilt’s protected settlement or entitlement routes directly. Use the agent-to-agent micropayments guide for the buyer implementation, payment-term validation, and complete runtime explanation. The runnable TypeScript example contains both the protected resource and buyer agent.

Safety boundaries

Keep HILT_API_KEY in server-side secrets.
Never call billable work before atomic consumption succeeds.
Never authorize from a raw transaction hash, wallet claim, or client-side flag.
Preserve the same request ID across retries of one operation.
Make side effects inside the paid handler idempotent by request ID because a client may retry after receiving the result.
Use Hilt sandbox validation before live settlement.

See Hilt Pay API, API keys, Testing, and Errors.

Start here

After payment

Examples and reference

Protect an endpoint

Protect an endpoint

Before you start

Install the SDK

Wrap the route

Python services

Send stable identities

What the wrapper does

Buyer behavior

Safety boundaries

​Protect an endpoint

​Before you start

​Install the SDK

​Wrap the route

​Python services

​Send stable identities

​What the wrapper does

​Buyer behavior

​Safety boundaries

Protect an endpoint

Before you start

Install the SDK

Wrap the route

Python services

Send stable identities

What the wrapper does

Buyer behavior

Safety boundaries