Add x402 payment completion telemetry event

[Y33t-dev]

closes #296

Summary

x402 payment completion is not tracked as a telemetry event, so a host that wants to know what its agents are spending has to instrument every call site by hand.

This adds contrib/examples/issue-296-x402-payment-telemetry: an x402.payment.completed event carrying the resource id and amount the issue asks for, plus the asset, network, settlement hash, payer, status and duration that make it reconcilable against chain rather than merely countable.

withPaymentTelemetry() wraps the public wallet.x402.fetch, so it works today with no SDK change:

wallet.x402.fetch = withPaymentTelemetry(wallet.x402.fetch, {
  sink: (event) => analytics.track(event.type, toJSON(event)),
  onError: (err) => console.warn("x402 telemetry sink failed", err),
});

Omit sink and the original function is returned untouched, so telemetry is opt-in with no per-call cost when off.

Design rules

Telemetry must never break a payment. The event fires only after money has already moved on-chain. A sink that throws, rejects, hangs, or whose onError itself throws still returns the caller's X402Response. An async sink is deliberately not awaited, so a slow analytics call adds no latency to a settled payment; its rejection is caught internally rather than surfacing as an unhandled rejection. There is no configuration that lets telemetry fail a settled payment.

It must not leak secrets. No request headers or bodies are recorded. PAYMENT-SIGNATURE is a signed authorization, and the SDK already treats leaking it as a security bug (packages/mcp-x402-payer/src/output.ts). Resource URLs are stripped of query and fragment by default, since API keys live in query strings; resourceIdMode allows origin or opt-in full. A URL that fails to parse still has its query cut off lexically.

Amounts stay exact. Base units are bigint and a stroop-precision value can exceed Number.MAX_SAFE_INTEGER. JSON.stringify throws on a bigint, so toJSON() renders amount as a decimal string that round-trips through BigInt(...).

Only settled payments emit. A 402-free response is a cache hit, not a payment; counting it would inflate every metric built on this event. A failed payment emits nothing and rethrows untouched.

Tests

27 tests covering the event shape, URL sanitization, bigint precision and JSON round-tripping, and each way a sink can fail without disturbing the payment.

npx vitest run contrib/examples/issue-296-x402-payment-telemetry

Notes for the maintainer

Two requirements could not be met as literally written, because contributor PRs may only touch contrib/:

• README observability section. README.md is outside contrib/, so the reference documentation lives in the example's README instead, written so the tables can be lifted into that section verbatim.
• Emitting from inside the SDK. The example README sketches the in-SDK version: the completion point is where readSettlement() returns in src/x402-client.ts, and an optional telemetry?: X402TelemetryOptions on X402ClientDeps (threaded through X402FacadeDeps.config, alongside budgetAttributes) would emit the same event for every caller. Happy to open that as a follow-up if you widen the scope.

The 18 test failures on dev (in contrib/examples/ and src/session.test.ts, which also fails tsc) are pre-existing and untouched by this branch.

[drips-wave]

@Y33t-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[vercel]

@Y33t-dev is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.