x402-analytics

Analytics middleware for x402 API sellers. Drop into your Hono or Express server to track every paid request — method, path, status, response time, buyer address, and USDC payment amount — and batch-send it to Hexnaut.

Built for APIs that serve AI agents paying with USDC on Base via the x402 protocol.

Install

npm install x402-analytics
# or
pnpm add x402-analytics

Peer dependencies: hono >=4 or express >=5 (both optional — install whichever you use).

Quick Start

Hono

import { Hono } from "hono";
import { x402Analytics } from "x402-analytics/hono";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");

const app = new Hono();

app.use(
  x402Analytics({
    account,
    sellerEndpoint: "https://api.example.com",
  }),
);

app.get("/data", (c) => c.json({ ok: true }));

export default app;

Express

import express from "express";
import { x402Analytics } from "x402-analytics/express";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");

const app = express();

app.use(
  x402Analytics({
    account,
    sellerEndpoint: "https://api.example.com",
  }),
);

app.get("/data", (req, res) => res.json({ ok: true }));

app.listen(3000);

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | account | SignerAccount | required | Wallet account for signing ingest requests (ERC-8128). Compatible with viem's PrivateKeyAccount. | | endpoint | string | https://api.hexnaut.xyz/v1/ingest | Hexnaut ingestion endpoint. | | sellerEndpoint | string | — | Your API's public URL. Sent to Hexnaut for auto-registration. | | flushInterval | number | 5000 | Milliseconds between batch flushes. | | flushSize | number | 50 | Max events per batch before auto-flush. | | maxBufferSize | number | 10000 | Max events buffered in memory. Oldest events are dropped when exceeded. | | onError | (err, droppedCount) => void | — | Called when a flush fails. droppedCount indicates events dropped due to buffer overflow. |

How It Works

1. The middleware intercepts each request and records method, path, status code, and response time.
2. It parses the X-PAYMENT / PAYMENT-SIGNATURE header to extract the buyer's address and USDC amount.
3. Events are buffered and batch-flushed to the Hexnaut ingestion endpoint on a timer or when the batch is full.
4. Each batch is signed with ERC-8128 (RFC 9421 HTTP Message Signatures + secp256k1) using your wallet account — the library never touches your private key.
5. On flush failure, events are re-queued with exponential backoff. On shutdown (SIGTERM/SIGINT), pending events are flushed before exit.

What Gets Tracked

Each event sent to Hexnaut contains:

{
  "method": "GET",
  "path": "/data",
  "buyer_address": "0x1234...abcd",
  "amount_usdc": "0.001000",
  "status_code": 200,
  "response_time_ms": 42,
  "timestamp": "2026-01-15T12:00:00.000Z"
}

USDC amounts are stored as 6-decimal strings (e.g., "1.000000"), never floats.

Edge Runtime Compatible

No Buffer or node:crypto — works on Cloudflare Workers, Deno, and Node.js (>=18.4.0).

License

MIT