Skip to content

Add x402 payment support (Node-first, opt-in) - #14

Merged
planadecu merged 26 commits into
mainfrom
feat/x402-payment-support
Jul 15, 2026
Merged

Add x402 payment support (Node-first, opt-in)#14
planadecu merged 26 commits into
mainfrom
feat/x402-payment-support

Conversation

@planadecu

@planadecu planadecu commented Jul 15, 2026

Copy link
Copy Markdown
Owner

Summary

Adds opt-in, Node-first x402 payment support so callers can make paid Glassnode calls (USDC on Base) through the existing GlassnodeAPI client — without the core package taking on any crypto dependency.

  • x402: true config preset routes to the paid endpoint; apiKey becomes optional in that mode, fetch required.
  • New subpath export glassnode-api/x402 with createX402Fetch({ account, maxPaymentPerCall }).
  • The crypto stack (@x402/fetch, @x402/evm, viem) is an optional peer dependency; the core entry stays zod-only and browser-safe (src/x402.ts is the only file that touches crypto, via dynamic import()).
  • Uses the x402 protocol v2 client (@x402/fetch + @x402/evm); spend cap enforced via a payment policy; a bare viem LocalAccount signs EIP-3009 authorizations.

Bumps to 0.8.0.

Also included (from hands-on testing)

  • GlassnodeApiError now surfaces the server's error-body message (e.g. "Resolution 1h is not allowed") and exposes it on .detail.
  • Security: api_key is redacted in URLs passed to the optional logger.
  • Accurate 402 message for failed x402 payments.
  • Example examples/ex.x402.active-addresses.ts (default BTC @ 24h), env-configurable; the testnet endpoint URL is supplied via env, never hardcoded.

Verification

  • 44 unit tests pass (1 integration test skipped unless X402_TESTNET_PRIVATE_KEY + X402_TESTNET_URL are set); lint, build, and build:browser clean.
  • Proven end-to-end on a real x402 testnet endpoint: a bare LocalAccount paid metadata ($0.01) + metric ($0.05) and returned validated data.

🤖 Generated with Claude Code

planadecu and others added 26 commits July 14, 2026 22:06
@planadecu @claude
Add design spec for x402 payment support (Node-first)
8327599 
Approach A: subpath export (glassnode-api/x402) + core x402 preset,
with x402-fetch/viem as optional peer deps. Coinbase x402-fetch v1,
Base/USDC, maxPaymentPerCall cap, apiKey optional under x402.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
Incorporate Opus design-review findings into x402 spec
1f132bc 
- Mandate excluding src/x402.ts from browser tsconfig/rollup (release-pipeline risk)
- Add source DEFAULT_API_URL constant; apiUrl .url().optional(); apiKey field -> string|undefined
- Note apiKey conditional-required is runtime-only (z.input)
- Helper: import type for viem, verify signer type before building walletClient,
  cast wrapped fetch as typeof fetch, cut walletClient override (YAGNI)
- Tests: vi.mock dynamic imports, assert parseUnits('0.06',6)===60000n, 402-not-retried
- Add per-call spend-guard caveat + wallet-safety guidance; subpath CJS-only note

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
Update x402 spec from live-endpoint probe + feedback
13d2382 
Verified against live x402.glassnode.com / .tech 402 challenges:
- Endpoint speaks x402 v2 (x402Version:2, header-based challenge, eip155
  CAIP-2 networks) -> switch client from Coinbase x402-fetch v1 to
  x402-foundation @x402/fetch v2 (v1 cannot parse v2)
- Bulk endpoints 404 over x402 -> callBulkMetric unsupported in x402 mode
- Pricing confirmed: metadata $0.01 (10000), metrics $0.05 (50000)
- Testnet x402.glassnode.tech = Base Sepolia (eip155:84532); add
  X402_TESTNET_API_URL + opt-in testnet integration test step
- Require fetch when x402:true (construction-time Zod refine)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
Lock x402 client to @x402/fetch v2 + @x402/evm (Coinbase CDP-recommen…
26e1708 
…ded)

Coinbase's CDP buyer quickstart itself now installs @x402/fetch @x402/evm
(scoped v2); the unscoped x402-fetch v1 is the deprecated predecessor and
cannot parse the v2 challenge the Glassnode endpoint returns. So the
"Coinbase client" and the foundation v2 client are the same package.

- Helper builds the v2 client (registerExactEvmScheme + x402Client) and
  wrapFetchWithPayment(fetch, client); deps @x402/fetch + @x402/evm + viem
- Spend cap: use v2 max-amount option if present, else a payment-requirements
  selector that throws over the cap
- Removes the "pending confirmation" caveat on the client decision

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
Add x402 payment support implementation plan
dcb33c8 
7 TDD tasks: config preset, base-URL resolution, 402 error, packaging
(optional peer deps + subpath export + browser exclude), createX402Fetch
helper, opt-in testnet integration, docs. Helper source pre-verified with
tsc 6.0.3 against real @x402/fetch + @x402/evm + viem types.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
Fix x402 plan: merge config + client task (green-at-commit)
daf220d 
Opus plan review found one blocker: Task 1 dropped the apiUrl Zod default
but deferred the constructor's base-URL resolution to Task 2, so the
existing default-URL test would fail under the Husky vitest-related
pre-commit hook and block the Task 1 commit. Merge config schema +
constructor/request changes into a single Task 1; renumber the rest (now
6 tasks). All other review checks passed (Zod, tests, packaging, lint).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu
feat(config): x402 preset, base-url resolution, conditional apiKey/fetch
84027e5
@planadecu
feat(errors): friendly 402 payment-required message
0cf8348
@planadecu
chore(x402): optional peer deps, ./x402 subpath export, browser exclude
db553ab
@planadecu
feat(x402): createX402Fetch helper (subpath glassnode-api/x402)
a81babf 
Adds src/x402.ts: usdcDecimalToAtomic, createMaxAmountPolicy, and
createX402Fetch, which turns a viem LocalAccount into an x402-payment
capable fetch (registers ExactEvmScheme for Base mainnet + Sepolia,
enforces a per-call USDC spend ceiling). All value imports of the
optional peer deps (@x402/fetch, @x402/evm) are dynamic import()s
inside the async function, so the subpath stays importable without
the deps installed until createX402Fetch is called; a missing dep
rejects with a clear install-instructions error.

Also adds "types": ["node"] to tsconfig.json: @x402/core's shipped
.d.mts references the global Buffer type without an explicit
reference/import, and this project's base tsconfig was not
auto-including @types/node ambient globals (same gap tsconfig.test.json
already worked around), which broke `tsc` once src/x402.ts pulled in
@x402/core's types transitively. Verified this doesn't leak into the
browser build (tsconfig.browser.json already excludes src/x402.ts;
confirmed no x402 symbols appear in the rollup bundles).
@planadecu
test(x402): opt-in testnet integration test + test:x402 script
5f09080
@planadecu
docs(x402): README section, CHANGELOG, bump to 0.8.0
76ce22b
@planadecu @claude
docs(examples): x402 SUI active-addresses example (testnet/mainnet vi…
0d23828 
…a env)

Adds examples/x402.active-addresses.ts: builds a payment-capable fetch from a
funded Base wallet, checks the metadata endpoint for SUI + 1h support, then
fetches SUI active addresses (last 1 month, 1h) over x402. Network (testnet/
mainnet), wallet key, and per-call cap are env-driven. Updates .env.example,
examples package.json (@x402/fetch, @x402/evm, viem), and the examples README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
fix(errors): make 402 message accurate for failed x402 payments
dcf1b00 
The old 402 message ("pass an x402-capable fetch") misleads when the fetch
IS x402-capable but the payment didn't settle (e.g. insufficient USDC or
over maxPaymentPerCall) — the exact case an unfunded testnet wallet hits.
Reword to cover both: payment-not-completing (check USDC balance / cap) and
the no-wrapper case.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
docs(examples): default x402 example to ETH, add X402_ASSET, skip uns…
9d724bc 
…upported

SUI active_count isn't offered on the testnet x402 endpoint (metadata: SUI
absent from the supported-asset list), so default the example to ETH (works
on testnet) and make the asset overridable via X402_ASSET. When the chosen
asset isn't supported for the metric, the example now prints a few supported
assets and returns early instead of wasting the $0.05 metric call on a 403.
Renamed to ex.x402.active-addresses.ts to match the local examples naming.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
feat(errors): surface the server error-body message in GlassnodeApiError
bacc5d8 
Glassnode returns a JSON body like {"message":"Resolution 1h is not
allowed. Allowed resolutions: [24h, 1w, 1month]"} on failures, but the
client discarded it — so a 403/400 gave only a generic message. request()
now reads the error body (best-effort, never throws), extracts message/error
(or raw text), and appends it; GlassnodeApiError gains an optional `detail`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
docs(examples): x402 example default 24h, configurable metric/resolution
8766dc8 
active_count rejects i=1h on the x402 endpoint ("Resolution 1h is not
allowed"), so default to 24h. Make metric/asset/resolution env-configurable
and add X402_SKIP_METADATA to isolate a single paid call.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
docs(changelog): note GlassnodeApiError error-body surfacing under 0.8.0
14be260 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
fix(security): redact api_key in logged URLs
641cf44 
The optional logger received the full request URL, which in non-x402 mode
includes ?api_key=<key> — leaking the API key into any log sink. Mask the
api_key value before logging (other params preserved).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
docs(changelog): note api_key log redaction under 0.8.0
f65d083 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
refactor(x402): don't hardcode the testnet endpoint; supply it via env
19a37bf 
Remove the X402_TESTNET_API_URL constant (which baked the testnet domain
into the shipped library) and every reference to that domain across tests,
example, README, and design docs. Target a non-default x402 endpoint by
passing its URL as `apiUrl`:
- example reads an optional X402_API_URL override (not in .env.example)
- integration test reads X402_TESTNET_URL and skips when unset

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
fix(errors): don't append raw JSON body when it has no message/error
fab8ea3 
A 402 body of literal "null" (the x402 challenge lives in a header, body is
null) was being appended to the error as "— null". readErrorDetail now only
uses a string message/error field from valid JSON, and falls back to raw
text only for non-JSON bodies.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
docs(examples): default x402 asset to BTC; drop X402_ASSET from .env.…
d948126 
…example/docs

X402_ASSET is an example-only override, so keep it in the script (default BTC)
but remove it from .env.example and the README. .env.example documents
X402_API_URL (mainnet) with a valid https URL and drops the contradictory
"not shown" comment.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu @claude
docs(readme): document x402 config option and error-detail surfacing
b645cff 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu
Merge remote-tracking branch 'origin/main' into feat/x402-payment-sup…
a4c060f 
…port

# Conflicts:
#	package.json
#	pnpm-lock.yaml
@planadecu @claude
chore(deps): pin optional x402 peer deps to the v2 major (^2.18.0)
72875ed 
Per PR review: >=2.18.0 would allow a breaking @x402/* v3; ^2.18.0 pins to
the v2 API the helper targets (matches viem's ^2.48.11).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011Cf2DgwfRTWWuKtEhUeuZq
@planadecu
planadecu merged commit 9a2f6da into main Jul 15, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@planadecu