Skip to content
Tollgate Docs

@tollgatepay/core

Runtime-agnostic primitives shared by @tollgatepay/next, @tollgatepay/agent, and the facilitator API. Split across subpath exports so Workers bundles can import narrowly.

Subpath imports

import { ERROR_CODES, usd, type IOUMessage } from "@tollgatepay/core";
import { TOLLGATE_DOMAIN, verifyIOUSignature } from "@tollgatepay/core/eip712";
import { canonicalizePath } from "@tollgatepay/core/path";
import { InMemoryStore, RedisStore } from "@tollgatepay/core/store";

Key exports

Types

  • IOUMessage — the EIP-712 primaryType: "IOU" body. bigint for every uint256 field.
  • IOUHeader — the wire envelope (base64-JSON) in x-tollgate-iou.
  • PaymentRequiredResponse — the full 402 body shape.
  • TollgateConfig — shared developer-side config type.
  • MicroUSDC — branded integer. Use usd("0.05") or toMicroUSDC(n).
  • ErrorCode / ERROR_CODES — error catalog.

EIP-712

  • TOLLGATE_DOMAIN — default (Base, chainId 8453). Build others with buildDomain(chainId).
  • signIOU / signIOUWithPrivateKey — canonical signers (the agent SDK delegates here).
  • verifyIOUSignature — recovers + compares. Returns { valid, recoveredAddress }.
  • encodeIOUHeader / decodeIOUHeader / parseIOUHeaderSafe — envelope codec (Zod-validated).

Canonicalization

  • canonicalizePath(p) — trims, lowercases, and collapses UUID/numeric/hex segments to [id].
  • pathAppearsDynamic(p) — heuristic — true when a segment still looks dynamic after canonicalization.

Store adapters

import { autoDetectStore, InMemoryStore, RedisStore } from "@tollgatepay/core/store";

// Pick the right adapter for the runtime (Cloudflare KV, Vercel KV, Upstash
// Redis, or in-memory). Falls back to in-memory if no binding is found.
const store = await autoDetectStore({ env: process.env });

See also