hashspan

hashspan

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.

Quick start

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 SDK

With 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 exits

Full runnable walkthrough, with the SDK setup and a local chain: docs/quick-start.md, or on the website.

Choose your path

Packages

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.

Not an agent?

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).

With a coding agent

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.

Local lab

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.

Why

• 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/core has one peer dependency, @opentelemetry/api.

Safe by design

• 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).

Documentation

• 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

Contributing

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.

License

Apache-2.0