OpenTelemetry instrumentation for viem, the Coinbase CDP SDK, x402 and MPP. Trace the on-chain transactions and payments your AI agents and services send, inside the traces you already have.
When an agent or a service sends a transaction, its trace usually stops at the call. Whether the transaction was
mined, reverted, or what it cost lives somewhere else. hashspan closes that gap: each transaction becomes a send /
confirm span pair, keyed by the transaction hash, inside the trace that sent it, with status, gas and fees
attached, exported to the backend you already use (Jaeger, Grafana Tempo, Langfuse, Honeycomb, ...).
Status: 1.x, published with npm provenance. The API is stable; span, attribute and metric names can still change in a minor release (change policy).
A real run on Base Sepolia with hashspan 1.3.0: the vendor payment and the reverted withdrawal. How it looks in Jaeger: screenshot.
Requires Node.js 22.3 or later.
npm install @hashspan/viem @opentelemetry/api viem
npm install @opentelemetry/sdk-node # unless your app already sets up an OpenTelemetry SDKWith an OpenTelemetry SDK started, extend your viem clients (account, to and value are your own):
import { createPublicClient, createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { withHashspan } from '@hashspan/viem';
const hashspan = withHashspan();
const wallet = createWalletClient({ account, chain: base, transport: http() }).extend(hashspan);
const reader = createPublicClient({ chain: base, transport: http() }).extend(hashspan);
// In your agent's tool call or your request handler: the spans join its trace.
const hash = await wallet.sendTransaction({ to, value }); // send span
await reader.waitForTransactionReceipt({ hash }); // confirm span
await hashspan.flush(); // before the process exitsFull runnable walkthrough, with the SDK setup and a local chain: docs/quick-start.md, or on the website.
| You send with | Start here |
|---|---|
| viem clients | the snippet above, then @hashspan/viem |
| Coinbase CDP SDK server or smart accounts | @hashspan/cdp |
| x402 payments | @hashspan/x402, the x402 agent example and the x402 tutorial |
| MPP payments made with mppx | @hashspan/mpp |
| A wallet service (Privy, Turnkey, Circle, ...) | wallet services |
| A worker, a wallet backend or a bot, not an agent | not an agent? |
| A coding agent that adds it for you | with a coding agent |
| Another send path | @hashspan/core |
| Package | Install it when | Status |
|---|---|---|
@hashspan/core |
you record another send path yourself; the adapters bring it along |  |
@hashspan/viem |
you send with viem clients (viem OpenTelemetry guide) |  |
@hashspan/cdp |
you send with Coinbase CDP server or smart accounts |  |
@hashspan/x402 |
you pay for APIs with x402 (x402 tutorial) |  |
@hashspan/mpp |
you pay with MPP through mppx (0.x, follows mppx's minor lines) |  |
@hashspan/faults |
you test an EVM client, node or service against JSON-RPC faults: hangs, errors, resets, wrong results (0.x, Node.js, no dependencies) |  |
Install the latest version of each package you use (versions). GitHub releases are tagged per package, so "Latest" there is the package released last.
hashspan does not need one: in a payout worker, a wallet backend or a bot, the spans nest under the request or job span you already have (services that are not agents, payout worker example).
skills/hashspan is an Agent Skills skill that
adds hashspan to a TypeScript project, checked in CI: npx skills add selimaytac/hashspan. The website has a
guide for adding hashspan with a coding agent and
the hashspan skills with ready prompts.
In a checkout of this repository, make lab-up starts Jaeger on http://localhost:16686 and make demo runs the
example agent on a local chain, with no API key (setup and other targets).
The full set of scenarios, with Grafana dashboards, is in hashspan-lab.
- No new dashboard. It's a library that emits standard OpenTelemetry spans. Your existing backend is the UI.
- Agent-aware, not agent-only. Transaction spans nest under your framework's agent and tool spans and carry
gen_ai.agent.id; without an agent, under whatever span is active. - Real cost, and metrics. Fees include the L1 data fee that L2s such as Base charge; latency and fees are also recorded as histograms (semantic conventions).
- Small footprint.
@hashspan/corehas one peer dependency,@opentelemetry/api.
- It never signs or broadcasts a transaction and needs no private key (security model).
- Its RPC calls are read-only (the requests it adds).
- Privacy defaults are conservative. Calldata arguments and error messages are opt-in, and addresses can be hashed or dropped (privacy notes).
- Website: hashspan.dev · quick start · viem OpenTelemetry guide · build with AI · x402 tutorial · transaction errors explained
- Start: docs index · Tracing backends · Integrations · Troubleshooting
- Reference: Semantic conventions · Architecture · OpenTelemetry attributes lookup
- Project: Roadmap · Releasing · ADRs · Security
Questions, feedback on the span schema, bug reports and pull requests are all welcome. Start with the contributing guide, or pick a good first issue.