x402-oversight

Oversight and governance wrapper for x402 payments. Drop-in fetch replacement that enforces spend caps and captures a transaction record for every paid request from an AI agent.

Install

npm install x402-oversight

Requires Node 18+ (for global fetch).

Quick start

import { createOversight } from "x402-oversight";

const oversight = createOversight({
  agent: "researcher-01",
  budget: {
    perCall: 0.05,
    hourly: 25,
    daily: 100,
  },
  onRecord: (record) => {
    console.log("[oversight]", record.status, record.endpoint, `$${record.amount}`);
  },
});

const { response, record } = await oversight.fetch(
  "https://api.example.com/data",
);

console.log(await response.json());
console.log("spent so far:", oversight.snapshot());

What it does

You call oversight.fetch(url) instead of fetch(url).
If the server responds 402 Payment Required, the wrapper:
- Reads the price from the x-payment-amount-usd header
- Checks it against your perCall, hourly, daily, and lifetime caps
- Throws BudgetExceededError if any cap would be exceeded
- Otherwise retries the request with an x-payment-authorization header
Every outcome (success, blocked, error) is emitted to onRecord with:
- unique record id
- agent identifier
- endpoint
- amount
- tx hash (when provided by the server)
- timestamp
- status

API

`createOversight(options): Oversight`

Option	Type	Description
`agent`	`string`	Identifier for the calling agent. Required.
`budget.perCall`	`number?`	Max spend per single call, in USD.
`budget.hourly`	`number?`	Max spend per rolling hour, in USD.
`budget.daily`	`number?`	Max spend per rolling day, in USD.
`budget.lifetime`	`number?`	Hard cap across the lifetime of this oversight instance, in USD.
`onRecord`	`(r) => void \| Promise<void>`	Called after every transaction. Use this to write to your log store.
`fetch`	`typeof fetch`	Custom fetch implementation. Defaults to `globalThis.fetch`.

`oversight.fetch(input, init?): Promise<PaymentResponse>`

Same signature as the global fetch, but returns { response, record }.

`oversight.snapshot()`

Returns the running totals and the configured budget.

`BudgetExceededError`

Thrown before the second (paid) request is sent when any cap would be breached. Has kind (which cap), limit, and wouldSpend fields.

License

MIT