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, internal 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.

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 launch posture

Hilt Pay API launches with:

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 launch settlement details needed to complete payment. Base USDC, selected EVM USDC chains, and USDT are future or production-gated lanes 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,
        "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 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 production gates
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 are part of the account control plane. In production, sensitive provider and signing keys should be stored as admin/vault references, not pasted into code or public docs.

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",
    "entitlement_duration_days": 30,
    "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.
Your server calls POST /v1/access/entitlements/check.
If has_access: true, serve the resource.
If not paid, create a payment session with POST /v1/access/payment-sessions.
Return HTTP 402 Payment Required with payment_protocol: "x402" and settlement_rail: "solana_usdc".
The agent or buyer pays through the provided requirement.
Hilt verifies settlement, creates receipt state, activates entitlement, and emits webhooks.
The agent retries the resource.

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
deny access unless has_access: true
treat x402 as protocol and Solana USDC as launch 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

​Agent setup

​The safe mental model

​Current public launch posture

​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