Agent setup

Agent setup is the Hilt Pay API path for software that wants to configure paid access without asking the merchant to click through every technical step. Use it when an AI agent, Cursor workflow, platform agent, developer tool, or integration bot needs to:

create a sandbox setup intent
propose the app, product, protected resource, webhook, and settlement rail
test the denied -> 402 -> payment -> proof -> entitlement loop in sandbox
hand live approval back to the owner
receive scoped live credentials only after owner approval

The goal is agent-first without being reckless. Agents can prepare the integration. Owners still control live billing, live API keys, payout wallets, production rail settings, and emergency disable. For agentic payments, setup is only half the job. At runtime, a metered protected resource must atomically consume one unit and serve only after settlement and consumption succeed. Use entitlement checks for durable access display and planning.

The safe mental model

Step	Agent can do	Owner controls
Discover	Read docs, OpenAPI, SDKs, Postman, and `llms.txt`	n/a
Bootstrap	Create a sandbox setup intent	n/a
Manifest	Propose app, product, webhook, protected resource, protocol, and settlement rail	Review the proposed live configuration
Sandbox	Create sandbox products/sessions and check entitlements	n/a
Approval	Poll status and receive the approved shape	Approve live access, billing, live key scopes, payout wallet, and rail settings
Runtime	Create sessions, return x402 requirements, check entitlements, receive webhooks	Revoke keys, pause products, disable rails, change billing, and inspect audit/support history

Current Public Scope

Hilt Pay API currently supports:

solana_usdc as the live settlement rail
x402 as the HTTP 402 Payment Required protected-resource protocol
API pricing through Sandbox, Starter, Growth, Scale, and Enterprise
public SDKs on npm and PyPI
public GitHub developer assets, OpenAPI, and Postman

x402 is the protocol shape an agent sees when a protected resource requires payment. Hilt returns that requirement with the current settlement details needed to complete payment. Agentic payments describe this paid-resource loop. They are not a separate chain, token, wallet, or rail. Base USDC, selected EVM USDC chains, and USDT are not currently public settlement options unless the public docs and changelog explicitly say they are live.

1. Create a setup intent

curl -X POST https://api.hilt.so/v1/access/agent-bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'

The response includes:

setup_intent_id
one-time setup_token
sandbox API key
owner approval URL
expiry
allowed sandbox actions

The sandbox key is not a live-money key.

2. Submit a setup manifest

The manifest is the agent’s proposed plan. It should be explicit enough for the owner and Hilt to understand what will be created.

curl -X POST https://api.hilt.so/v1/access/agent-bootstrap/SETUP_INTENT_ID/manifest \
  -H "Content-Type: application/json" \
  -d '{
    "setup_token": "hst_...",
    "manifest": {
      "app": {
        "name": "Acme AI",
        "external_app_id": "acme-ai"
      },
      "product": {
        "external_product_id": "pro-api",
        "title": "Pro API access",
        "amount_minor_units": 79000000,
        "billing_model": "recurring",
        "renewal_mode": "solana_native_subscription",
        "billing_interval_days": 30,
        "entitlement_duration_days": 30,
        "cancel_at_period_end": true,
        "expected_monthly_volume_usd": 125000,
        "expected_monthly_payments": 1600,
        "default_rail": "solana_usdc",
        "allowed_rails": ["solana_usdc"]
      },
      "payment_protocol": "x402",
      "settlement_rail": "solana_usdc",
      "protected_resource": {
        "url": "https://api.acme.test/ai/pro",
        "method": "POST",
        "customer_identity": "external_customer_id"
      },
      "webhook": {
        "url": "https://api.acme.test/hilt/webhook",
        "subscribed_events": ["payment.confirmed", "receipt.created", "membership.activated"]
      }
    }
  }'

Hilt returns normalized setup state, readiness blockers, warnings, the next API actions, and a Hilt Pay API tier recommendation. The agent must make the billing decision explicit. Use billing_model: "one_off" for a single payment that grants a fixed access period. Use billing_model: "recurring" when access renews. Hilt Pay API recurring products use renewal_mode: "solana_native_subscription". Hilt keeps cancellation period-aware by default: if the buyer cancels, future collection stops and access remains until the paid-through date. The recommendation uses expected_monthly_volume_minor_units, expected_monthly_volume_usd, expected_monthly_payments, expected_monthly_webhook_events, and expected_monthly_entitlement_checks when the agent supplies them. It compares Starter, Growth, and Scale using the API subscription price plus Solana USDC transaction fees. If the agent does not know volume yet, Hilt defaults the recommendation to Starter and asks for better assumptions instead of forcing the owner to guess.

3. Poll setup status

curl -X POST https://api.hilt.so/v1/access/agent-bootstrap/SETUP_INTENT_ID/status \
  -H "Content-Type: application/json" \
  -d '{ "setup_token": "hst_..." }'

Use this while waiting for owner approval.

4. Owner approval

The owner opens the approval URL from a first-party Hilt session. The approval page is the trust handoff between the agent and the account owner. It shows the agent, requested permissions, product, price, protected resource, protocol, settlement rail, blockers, warnings, and the recommended API plan. The owner should only need to approve the intent, subscribe to the right API tier if needed, and confirm payout rail settings. They should not have to recreate the setup the agent already prepared. Approval can issue scoped live access for the owner’s workspace, but it does not bypass:

API billing plan checks
payout wallet setup
rail health and live availability
live-mode confirmation
webhook signing secret handling
emergency disable controls

Agents should treat owner approval as the transition from sandbox setup to live-capable setup. They should not pretend sandbox credentials are production credentials.

5. Configure rail settings

The agent can configure the proposed live rail through the API once it has owner-approved credentials:

curl -X PUT https://api.hilt.so/v1/access/rail-settings/solana_usdc \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rail-settings-solana-usdc-001" \
  -d '{
    "enabled": true,
    "mode": "live",
    "payout_address": "MERCHANT_SOLANA_PAYOUT_WALLET",
    "label": "Primary Solana USDC payout"
  }'

Rail settings belong to the merchant account. Keep sensitive provider and signing credentials server-side in a secure secrets manager; never paste them into browser code, shared examples, or public documentation.

6. Create app and product

curl -X POST https://api.hilt.so/v1/access/apps \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: app-acme-ai-001" \
  -d '{
    "name": "Acme AI",
    "external_app_id": "acme-ai",
    "default_rail": "solana_usdc"
  }'

curl -X POST https://api.hilt.so/v1/access/products \
  -H "X-Hilt-Key: hk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-pro-api-001" \
  -d '{
    "access_app_id": "APP_ID",
    "external_product_id": "pro-api",
    "title": "Pro API access",
    "amount_minor_units": 79000000,
    "merchant_wallet": "MERCHANT_SOLANA_PAYOUT_WALLET",
    "billing_model": "recurring",
    "renewal_mode": "solana_native_subscription",
    "billing_interval_days": 30,
    "entitlement_duration_days": 30,
    "cancel_at_period_end": true,
    "default_rail": "solana_usdc",
    "allowed_rails": ["solana_usdc"],
    "status": "active",
    "live_mode_confirmed": true
  }'

Agents should use Idempotency-Key on every write.

7. Check readiness and available rails

curl "https://api.hilt.so/v1/access/setup/readiness?external_product_id=pro-api" \
  -H "X-Hilt-Key: hk_live_..."

curl "https://api.hilt.so/v1/access/products/available-rails?external_product_id=pro-api" \
  -H "X-Hilt-Key: hk_live_..."

Render only payment_session_options.session_creatable_rails[] to a buyer or agent. allowed_rails[] is policy; it is not proof that a rail is ready to appear in checkout.

8. Runtime protected-resource loop

The application should behave like this:

Agent or user requests a protected resource with a stable request id.
Your server calls POST /v1/access/entitlements/consume for one unit.
If consumption succeeds, serve the resource.
If usage is missing, create a payment session with POST /v1/access/payment-sessions.
Return HTTP 402 Payment Required with Hilt’s x402 V2 PAYMENT-REQUIRED header. Solana USDC is the settlement rail.
The agent or buyer pays the advertised terms and retries your resource with PAYMENT-SIGNATURE.
Your server sends that signature to POST /v1/access/x402/settle.
Hilt verifies settlement, creates receipt and entitlement state, and returns PAYMENT-RESPONSE.
Your server atomically consumes one unit with the same logical request id.
Serve only after settlement and consumption succeed.

9. Billing checkout for Hilt Pay API

Account owners can create a Stripe Checkout session for Hilt Pay API billing:

curl -X POST https://api.hilt.so/v1/access/billing/checkout/stripe \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "growth",
    "interval": "monthly",
    "success_url": "https://app.hilt.so/dashboard/billing?success=1",
    "cancel_url": "https://app.hilt.so/dashboard/billing?cancelled=1"
  }'

API keys and sandbox setup-intent keys cannot change account billing.

Agent rules

Agents should:

keep Hilt keys server-side only
use sandbox setup first
include idempotency keys
use atomic consumption as the authority for each metered request
use entitlement checks for durable or time-based access display and planning
treat x402 as protocol and Solana USDC as the current public live settlement rail
use webhooks for post-payment automation
keep Hilt ids and external ids in the app database
show owner approval and billing steps clearly

Agents must not:

embed Hilt keys in browser code
treat sandbox credentials as live credentials
show blocked rails as buyer options
claim Base/EVM/USDT are live unless the public docs say so
grant access from a pending payment session
treat webhook delivery alone as enough to serve protected work without an entitlement check

Start here

After payment

Examples and reference

Agent setup

Agent setup

The safe mental model

Current Public Scope

1. Create a setup intent

2. Submit a setup manifest

3. Poll setup status

4. Owner approval

5. Configure rail settings

6. Create app and product

7. Check readiness and available rails

8. Runtime protected-resource loop

9. Billing checkout for Hilt Pay API

Agent rules

Go deeper

​Agent setup

​The safe mental model

​Current Public Scope

​1. Create a setup intent

​2. Submit a setup manifest

​3. Poll setup status

​4. Owner approval

​5. Configure rail settings

​6. Create app and product

​7. Check readiness and available rails

​8. Runtime protected-resource loop

​9. Billing checkout for Hilt Pay API

​Agent rules

​Go deeper

Agent setup

The safe mental model

Current Public Scope

1. Create a setup intent

2. Submit a setup manifest

3. Poll setup status

4. Owner approval

5. Configure rail settings

6. Create app and product

7. Check readiness and available rails

8. Runtime protected-resource loop

9. Billing checkout for Hilt Pay API

Agent rules

Go deeper