Build paid API access with Grok Build

Use this guide when Grok Build is helping you add Hilt Pay API to an API, AI tool, bot, dataset, paid software feature, or private endpoint. The public example is a complete Next.js application, not only a prompt. It contains:

a protected server route
Hilt entitlement checks
HTTP 402 Payment Required responses
Hilt Pay API payment-session creation
local, sandbox, and live modes
a server-only development confirmation route
signed webhook verification
route-flow tests
AGENTS.md instructions and a Grok project skill

Hilt and Grok Build are separate products. This guide documents compatibility with Grok Build’s public agent instructions, project skills, headless mode, and MCP support. It does not describe an xAI partnership.

What each product does

Product	Role
Grok Build	Reads the project, follows `AGENTS.md`, invokes the Hilt project skill, edits the integration, and runs its checks.
Hilt Pay API	Creates payment sessions, returns x402 payment requirements, verifies Solana USDC payment, records receipts and entitlement state, and emits webhooks.
Your backend	Keeps Hilt keys private, checks entitlement, returns HTTP 402 when unpaid, and serves the protected resource only after Hilt returns `has_access: true`.

Current public live settlement is Solana USDC. x402 is the HTTP 402 Payment Required protected-resource protocol shape. It is not a blockchain, token, wallet, chain, or settlement rail.

1. Install Grok Build

Use the official Grok Build installer for your operating system. macOS, Linux, or WSL:

curl -fsSL https://x.ai/cli/install.sh | bash

Windows PowerShell:

irm https://x.ai/cli/install.ps1 | iex

Then authenticate and verify the installation:

grok login
grok version

Official Grok Build documentation: https://docs.x.ai/build/overview

2. Get the runnable Hilt example

git clone https://github.com/Hiltpay/hilt-developer-assets.git
cd hilt-developer-assets/examples/grok-build-nextjs
npm ci

The example is also indexed by Hilt’s agent manifest, catalog, LLM files, and developer documentation.

3. Run without a Hilt key

The default local mode proves the application control flow without moving money or claiming a Hilt receipt. macOS, Linux, or WSL:

cp .env.example .env.local
npm run dev

Windows PowerShell:

Copy-Item .env.example .env.local
npm run dev

Open http://localhost:3000 and complete this flow:

Request the protected report.
Confirm that the server returns HTTP 402.
Confirm that the response says payment_protocol: "x402" and settlement_rail: "solana_usdc".
Run the clearly labelled local confirmation.
Retry the protected route.
Confirm that the route serves the report only after the entitlement becomes active.

Local mode is a simulation. It does not create a live payment, Hilt receipt, or on-chain transaction.

4. Let Grok inspect the contract

From the example directory:

grok inspect
grok

Grok Build should report the repository AGENTS.md file and the hilt-pay-api project skill. Use this prompt:

Read AGENTS.md and invoke the hilt-pay-api project skill. Verify the protected route, explain the denied -> HTTP 402 -> entitlement -> access flow, and adapt the protected response to my product. Keep Hilt keys server-side, use Solana USDC as settlement, and run every acceptance check before reporting completion.

For a headless review, the example includes:

npm run grok:review

That command passes the checked-in PROMPT.md to Grok Build and requests JSON output. It does not pass Hilt credentials in the prompt.

5. Choose the right mode

Mode	Hilt key	What it proves	Money movement
`local`	None	Route logic, HTTP 402 handling, retry behavior, and client/server boundaries	None
`sandbox`	Sandbox Hilt Pay API key	Hilt sandbox session creation, sandbox confirmation, and entitlement lookup	None
`live`	Owner-approved live Hilt Pay API key	Real x402 requirement and Solana USDC payment-to-access flow	Buyer-approved live settlement

Hilt sandbox mode

Create a Hilt Pay API sandbox product, then update .env.local:

HILT_DEMO_MODE=sandbox
HILT_API_URL=https://api.hilt.so
HILT_API_KEY=hk_sandbox_...
HILT_PAY_API_PRODUCT=your-external-product-id

Restart the example and run the browser flow again. The sandbox proof remains in server memory and is never returned to the browser. The example calls:

POST /v1/access/entitlements/check
POST /v1/access/sandbox/payment-sessions
POST /v1/access/sandbox/payment-sessions/{sandbox_session_id}/confirm

Live mode

After the owner has approved live setup, billing, payout wallet configuration, live API key scopes, and webhook configuration:

HILT_DEMO_MODE=live
HILT_API_URL=https://api.hilt.so
HILT_API_KEY=hk_live_...
HILT_PAY_API_PRODUCT=your-external-product-id
HILT_WEBHOOK_SECRET=whsec_...

Live mode calls:

POST /v1/access/entitlements/check
POST /v1/access/payment-sessions

The payment-session request explicitly uses:

{
  "payment_protocol": "x402",
  "settlement_rail": "solana_usdc"
}

The development confirmation route returns 409 in live mode. The buyer or buyer-agent must complete the real payment path. Your server then checks Hilt entitlement again before serving the protected resource.

Implementation contract

The entitlement check is the access decision. Do not serve paid work from a wallet signature, transaction hash, client claim, pending payment session, or webhook alone.

Optional Agentverse discovery in Grok Build

Hilt can also be discovered through its Agentverse presence. Agentverse is an optional discovery path for Grok. Grok Build can connect to Agentverse MCP Lite because Grok supports remote MCP servers. This is optional. Agentverse helps the coding agent discover and inspect marketplace agents; it is not the Hilt Pay API transport and it is not required for the runnable example. macOS, Linux, or WSL:

export AGENTVERSE_API_TOKEN="your-agentverse-token"
grok mcp add --scope project --transport http agentverse-lite https://mcp-lite.agentverse.ai/mcp --header "Authorization: Bearer ${AGENTVERSE_API_TOKEN}"
grok mcp doctor agentverse-lite

Windows PowerShell:

$env:AGENTVERSE_API_TOKEN = "your-agentverse-token"
grok mcp add --scope project --transport http agentverse-lite https://mcp-lite.agentverse.ai/mcp --header "Authorization: Bearer $env:AGENTVERSE_API_TOKEN"
grok mcp doctor agentverse-lite

Keep the token in the environment. Do not commit it to .grok/config.toml, AGENTS.md, prompts, or source code.

Verify the build

npm test
npm run typecheck
npm run build

The included tests verify:

missing customer identity is rejected
unpaid access returns HTTP 402
the response separates x402 protocol from Solana USDC settlement
the local flow cannot be confused with a live payment
a session cannot be confirmed for a different customer
protected content is served only after entitlement is active
API keys and sandbox proofs do not appear in browser responses

Before live traffic

use a server-only Hilt API key with the required scopes
configure the correct Hilt Pay API product and Solana payout wallet
use a fresh attempt id for each logical checkout attempt
verify Hilt webhooks against the raw body and X-Hilt-Signature
store processed webhook event ids durably and process events idempotently
complete sandbox validation
let the owner approve live keys, billing, payout wallet configuration, and live use
test the denied -> 402 -> payment -> entitlement -> retry loop

Hilt Agent Builder Kit
Agent setup
Hilt Pay API
Testing
Webhooks
SDKs and Postman
https://www.hilt.so/.well-known/hilt-agent.json
https://api.hilt.so/v1/openapi.json

Start here

After payment

Examples and reference

Build paid API access with Grok Build

Build paid API access with Grok Build

What each product does

1. Install Grok Build

2. Get the runnable Hilt example

3. Run without a Hilt key

4. Let Grok inspect the contract

5. Choose the right mode

Hilt sandbox mode

Live mode

Implementation contract

Optional Agentverse discovery in Grok Build

Verify the build

Before live traffic

​Build paid API access with Grok Build

​What each product does

​1. Install Grok Build

​2. Get the runnable Hilt example

​3. Run without a Hilt key

​4. Let Grok inspect the contract

​5. Choose the right mode

​Hilt sandbox mode

​Live mode

​Implementation contract

​Optional Agentverse discovery in Grok Build

​Verify the build

​Before live traffic

​Related resources

Build paid API access with Grok Build

What each product does

1. Install Grok Build

2. Get the runnable Hilt example

3. Run without a Hilt key

4. Let Grok inspect the contract

5. Choose the right mode

Hilt sandbox mode

Live mode

Implementation contract

Optional Agentverse discovery in Grok Build

Verify the build

Before live traffic

Related resources