402Guard

402Guard is a TypeScript SDK that wraps any x402 enabled HTTP client with a policy engine, spend limits, and an on chain subscription registry on Avalanche Fuji.

You keep using your normal HTTP client, your thirdweb x402 facilitator, and your existing API routes. 402Guard sits on top and decides:

  • which agent is allowed to spend how much
  • which subscription is active
  • whether a given x402 quote should be paid or blocked

Then it records usage and can generate invoices and simple analytics.

This project was built for the Hack2Build: Payments x402 Hackathon and uses Avalanche Fuji Testnet, USDC, and thirdweb x402.

Architecture

402Guard has three main pieces.

1. @402guard/client

Client side SDK that you use in frontends or backends:

  • createGuardedClient - policy engine and usage store
  • createGuardedAxios - wraps an Axios instance and enforces policies
  • In memory usage store plus analytics helpers
  • Optional x402 hooks to handle 402 responses and do the payment retry

2. @402guard/subscriptions

Small on chain registry deployed on Avalanche Fuji:

  • Solidity contract Guard402Subscriptions
  • Functions to create plans, subscribe users, and record usage
  • Read helpers to check whether a given user is active on a plan

3. @402guard/server

Express helpers that plug the on chain subscription registry into API routes:

  • requireSubscription middleware that checks isSubscriptionActive
  • You put it in front of any premium endpoint

The demo app in apps/web wires all three together and exposes two pages:

  • /x402-demo - real x402 paid API call through thirdweb
  • /subscriptions-demo - guarded HTTP calls with daily caps plus on chain status and invoice

Installation

In your own project you would install the packages from npm:

npm install @402guard/client @402guard/subscriptions @402guard/server

For this monorepo the packages are already wired as workspace dependencies. From the repo root you can run:

bun install
bun run dev

The Next app will be available on http://localhost:3000.

Quickstart: guarded Axios without x402

This is the simplest way to use the SDK. No x402 integration yet, just budgets around normal HTTP calls.

import { createGuardedAxios } from class="text-[#ce9178]">"@402guard/client";

const client = createGuardedAxios({
  agentId: class="text-[#ce9178]">"marketing-demo-user",
  policies: {
    globalDailyUsdCap: 5,
    perServiceCaps: {
      class="text-[#ce9178]">"api.openai.com": {
        dailyUsdCap: 2,
        monthlyUsdCap: 20,
      },
    },
  },
  // Very rough estimator for demo purposes
  estimateUsdForRequest: (config) => {
    if (config.url?.includes(class="text-[#ce9178]">"/v1/chat/completions")) return 0.05;
    return 0.01;
  },
});

async function callApi() {
  const response = await client.guardedRequest({
    url: class="text-[#ce9178]">"https://api.openai.com/v1/chat/completions",
    method: class="text-[#ce9178]">"POST",
    data: { /* ... */ },
  });

  console.log(response.data);
}

x402 integration with thirdweb

The x402 mode lets 402Guard intercept real 402 Payment Required responses, inspect the thirdweb quote, enforce budgets, and only then pay and retry.

import { createGuardedAxios } from class="text-[#ce9178]">"@402guard/client";
import { createThirdwebPayWithX402 } from class="text-[#ce9178]">"./thirdweb-x402-adapter";

const guarded = createGuardedAxios({
  agentId: class="text-[#ce9178]">"wallet-address-or-session-id",
  subscriptionId: class="text-[#ce9178]">"starter",
  facilitatorId: class="text-[#ce9178]">"thirdweb-fuji",
  policies: {
    globalDailyUsdCap: 5,
    perServiceCaps: {
      class="text-[#ce9178]">"localhost:3000": { dailyUsdCap: 1 },
    },
  },
  selectPaymentOption: (quote) => quote.options[0],
  estimateUsdFromQuote: (quote, option) => quote.amountUsd,
  payWithX402: createThirdwebPayWithX402({
    clientId: process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID!,
  }),
});

const res = await guarded.guardedRequest({
  url: class="text-[#ce9178]">"/api/x402-thirdweb-demo",
  method: class="text-[#ce9178]">"GET",
});