Skip to content
Tollgate Docs

Getting Started

This walkthrough takes you from an empty Next.js app to a working 402-gated endpoint. No blockchain RPC required for the first step — we use test-mode keys.

1. Install

pnpm add @tollgatepay/next @tollgatepay/core
# or npm / yarn / bun

2. Configure

Create .env.local:

TOLLGATE_API_KEY=aw_test_REPLACE_WITH_YOUR_KEY
TOLLGATE_PAYOUT_ADDRESS=0x0000000000000000000000000000000000000001
TOLLGATE_DEV_SALT=0x0000000000000000000000000000000000000000000000000000000000000002

API keys beginning with aw_test_ short-circuit the hot path to deterministic scenarios — no on-chain verify, no facilitator round-trip. Swap to aw_live_ once your payout address is wired up in the dashboard.

3. Wrap a route

// app/tollgate.ts — instantiated once at module scope.
import { initTollgate } from "@tollgatepay/next";

export const { wrap } = initTollgate({
  apiKey: process.env.TOLLGATE_API_KEY!,
  payoutAddress: process.env.TOLLGATE_PAYOUT_ADDRESS as `0x${string}`,
  developerSalt: process.env.TOLLGATE_DEV_SALT as `0x${string}`,
});

// app/api/premium/route.ts — gate a route behind a $0.05 charge.
import { wrap } from "../../tollgate";

export const GET = wrap({ price: 50_000 }, async (_req, payment) => {
  return Response.json({
    agent: payment.agentAddress,
    owedMicros: payment.totalOwedMicros,
  });
});

4. Try the demo

Call the endpoint without a header — you'll get a 402 Payment Required body containing the EIP-712 domain, price, and developer metadata.

curl -i http://localhost:3000/api/premium

Add x-tollgate-test-scenario: success to get a 200 without signing anything. Other scenarios: signature-mismatch, deadline-expired, nonce-reused.

5. Sign from an agent

Use @tollgatepay/agent on the agent side. See the Agent SDK docs.

Next steps