docs
Wrap the paid x402 fetch you already have. mpp is coming soon. withTrace OFAC-screens each payment, keeps the agent's context, and labels MCC, GL, and vendor so the trace can be audited.
Why wrap
One interceptor turns an agent that can pay into an agent finance can run. Screening is $0.001 per transaction. You keep your payment stack.
Agents become compliant
Every ingested payment is screened against OFAC. Hits go to manual review. Screening does not reverse the tx.
The reason for the payment is kept
withTrace snapshots raw_context (METHOD, url, body) with the tx hash. MCC, GL, and vendor labels attach to that context so the spend can be audited.
Stored only for you
Each workspace's traces are org-scoped. Other tenants cannot see them. OpenTrace does not train on them. Export CSV from the audit tab.
Agents become SOC2 ready
OFAC, context, MCC, GL, and vendor land on ingested payments. That evidence trail helps agents become SOC2 ready. It is not a certification of OpenTrace itself.
What happens to a trace
Traces are not a public pool. They are org-scoped in OpenTrace storage for your agents, your auditors, and any finance agent you connect.
Pay
The agent calls fetch as it already does. withTrace does not change settlement.
Screen
After the paid fetch returns, withTrace POSTs tx_hash and raw_context (the agent's context). The worker OFAC-screens and labels MCC, GL, and vendor against that context.
Store
Context and labels are written to your org-scoped ledger (shared Postgres index + object storage). Other tenants cannot read it.
Use
The dashboard audit tab and CSV download read that ledger: context plus OFAC, MCC, GL, and vendor. Finance can audit without reconstructing the chain.
Isolation is the product: list and get are org-scoped (cross-tenant reads 404). OpenTrace does not train on your payments. The dashboard and CSV export query your ledger.
Add it yourself
x402 now. mpp coming soon. Call sites stay fetch(url).
npm i @opentracedev/clientconst fetch = wrapFetchWithPayment(globalThis.fetch, x402Client);
await fetch(url);import { withTrace } from "@opentracedev/client";
const fetch = withTrace(wrapFetchWithPayment(globalThis.fetch, x402Client), {
apiKey: process.env.OPENTRACE_API_KEY!,
});
await fetch(url);Connect the workspace
Generate a live ot_live_ key in the dashboard. Traces POST fire-and-forget after the hash. A failed screen never throws and never reverses settlement.
OPENTRACE_API_KEY=ot_live_…Install OpenTrace withTrace in this repo. First follow https://opentrace.pro/auth.md to sign the user in with OpenTrace Magic Auth (email one-time code on opentrace.pro, not localhost, not GitHub, not Google). Then wrap the paid x402 fetch the agent already uses (wrapFetchWithPayment from @x402/fetch). MPP / mppx.fetch is coming soon. Do not invent an mpp integration. Do not refactor payment logic, add queues, or invent a dashboard.
Goal: wrap that paid fetch with withTrace so each successful payment posts a trace (tx_hash + raw_context). raw_context is the agent's context (METHOD url body). The OpenTrace worker OFAC-screens that payment and labels MCC, GL, and vendor against the kept context so the trace can be audited. Do not change call sites. They stay fetch(url).
1. Follow the auth.md skill until OPENTRACE_API_KEY is in .env. That value is an ot_live_ ingest key.
2. Install the SDK:
npm i @opentracedev/client
Use pnpm or yarn if that is what the repo uses.
3. Wrap wrapFetchWithPayment(...) with withTrace. withTrace wraps a paid fetch function, or a client with request()/fetch(). Do not wrap the wallet or x402Client (the scheme registry).
```ts
import { withTrace } from "@opentracedev/client";
const fetch = withTrace(wrapFetchWithPayment(globalThis.fetch, x402Client), {
apiKey: process.env.OPENTRACE_API_KEY!,
});
await fetch(url);
```
Omit baseUrl to ingest at https://api.opentrace.pro/v1/traces. The SDK snapshots the Solana tx hash (txHash / tx_hash / signature, or PAYMENT-RESPONSE) and raw_context (METHOD url body), then fire-and-forget POSTs { tx_hash, raw_context }. Ingest errors are swallowed. A failed or delayed screen never throws into the agent and does not reverse settlement.
If the package is unpublished in this environment, add a local wrapper at lib/with-trace.ts that calls the original fetch, then POSTs { tx_hash, raw_context } to https://api.opentrace.pro/v1/traces with Authorization: Bearer <apiKey>, and never throws from the trace.
4. Find wrapFetchWithPayment(...) assignments. Wrap that function. Skip mppx.fetch until mpp support ships. Leave existing fetch(url) call sites unchanged.
5. Stop when: (a) auth.md login succeeded, (b) every paid fetch construction is wrapped with withTrace, (c) env is documented, (d) a payment still succeeds if the trace POST fails. Do not add tests unless the repo already has a payment test. If it does, assert the wrap still returns the original result.