npm package: @hexnaut/x402-analytics
Description: Analytics middleware for x402 API sellers
Latest version: 0.1.0

# x402-analytics

Analytics middleware for [x402](https://www.x402.org/) 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](https://hexnaut.xyz).

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

## Install

```bash
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

```ts
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

```ts
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](https://ethereum-magicians.org/t/erc-8128-signed-http-requests-with-ethereum/27515)). 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](https://ethereum-magicians.org/t/erc-8128-signed-http-requests-with-ethereum/27515) (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:

```json
{
  "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