npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@phantomid/merchant-kit

v0.1.1

Published

One-line merchant kit for PHANTOM ID: drop-in JS snippet that turns any resource into a payable endpoint (402 -> quote -> facilitator payment -> automatic retry). Platform model: a single platform fee per payment, enforced on-chain by PhantomRouter and se

Readme

@phantomid/merchant-kit

One-line merchant kit for PHANTOM ID (AGP-115). Paste one script tag and any resource becomes a payable endpoint: the snippet wraps window.fetch, intercepts 402 Payment Required, pays through the PHANTOM ID facilitator, and retries automatically with the payment proof — the Stripe-snippet playbook for agent-to-merchant payments.

Install (one line)

<script src="https://unpkg.com/@phantomid/merchant-kit/dist/snippet.min.js"
        data-phantom-key="pk_live_YOUR_KEY" async></script>

dist/snippet.min.js is 4.8KB minified, zero dependencies (built by build.mjs from src/snippet-standalone.ts).

Data attributes

| attribute | default | meaning | |---|---|---| | data-phantom-key | — (required) | merchant API key (pk_live_…) | | data-phantom-facilitator | https://api.phantomid.example | facilitator base URL | | data-phantom-strict | true | reject paid responses without settlement proof |

Flow: fetch(url) → 402 → parse challenge → POST {facilitator}/v1/x402/pay → validate receipt → retry original request with X-Payment-Receipt header → strict-mode verifies the final response carries settlement proof (X-Payment-Settled: true, body.settled: true, or a valid body.receipt).

The key is a publishable merchant key (it lives in the browser, like a Stripe publishable key). Anyone who reads it can spend your facilitator balance on your visitors' behalf — that is the intended distribution model, but budget and domain policies should be set on the account.

Server-side: turn your endpoint into a paywall

import { phantomGuard } from "@phantomid/merchant-kit";

app.get("/premium",
  phantomGuard({
    price: "10000",              // 0.01 USDC (6-decimal base units)
    payTo: "0xYourTreasury…",
    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC
    network: "eip155:84532",
    resource: "https://api.example.com/premium",
    description: "premium data",
  }),
  (req, res) => {
    // req.phantomReceipt is the validated receipt
    res.json({ content: "…" });
  });

No receipt → 402 with x402 v2 PaymentRequirements (the snippet pays and retries transparently). Invalid receipt → 402 with reason. Valid receipt → request proceeds and the response is marked X-Payment-Settled: true.

Platform model — no third-party commissions

Platform model: a single platform fee per payment, enforced on-chain by PhantomRouter and sent to the PHANTOM treasury. The kit has no third-party commission mechanism. There is no take-rate, no merchant/processor commission, and no attribute or API to configure one (decision SPECTER-ONE, 2026-10-25, option A — take-rate discarded for v1).

Defensive validation: the kit rejects any receipt that claims a take (take_rate_bps > 0, a processor address, or take_amount > 0) with a TakeClaimedError — "receipt claims a take; platform does not issue takes". Our platform never issues takes, so any receipt claiming one is invalid by definition. This is defense, not a feature, and cannot be disabled.

Dashboard

Minimal read-only page of payments received per API key. It reads the existing tables — x402_payments (facilitator ledger, resolved via sha256(api_key) exactly like ApiKeyAuth) and chain_events (indexer, for on-chain reconciliation by recipient). No new infrastructure.

import { createDashboardServer } from "@phantomid/merchant-kit";
import { createDb } from "@phantom/api/src/db";

const db = await createDb(process.env.DATABASE_URL);
const server = await createDashboardServer(db, {
  apiKeySecret: process.env.PHANTOM_MERCHANT_KEY!, // pk_live_…
  recipient: "0xYourTreasury…".toLowerCase(),      // optional on-chain view
  port: 4173,
});
// open http://127.0.0.1:4173

Copy-paste examples

1. Charge for an API (Express)

import express from "express";
import { phantomGuard } from "@phantomid/merchant-kit";

const app = express();
app.get("/v1/prices",
  phantomGuard({
    price: "5000",                                  // 0.005 USDC / call
    payTo: "0xYourTreasury…",
    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    network: "eip155:84532",
    resource: "https://api.example.com/v1/prices",
    description: "live prices endpoint",
  }),
  (_req, res) => res.json({ btc: 67000, eth: 3450 }));
app.listen(3000);

Client side, one line in any page or agent dashboard:

<script src="https://unpkg.com/@phantomid/merchant-kit/dist/snippet.min.js"
        data-phantom-key="pk_live_YOUR_KEY" async></script>
<script>
  const r = await fetch("https://api.example.com/v1/prices"); // 402 → auto-paid → 200
</script>

2. Charge for content (static site)

<script src="https://unpkg.com/@phantomid/merchant-kit/dist/snippet.min.js"
        data-phantom-key="pk_live_YOUR_KEY" async></script>
<script>
  // Visitor clicks "unlock report": fetch returns 402, snippet pays, retries,
  // strict mode verifies settlement proof, content renders.
  document.getElementById("unlock").onclick = async () => {
    const r = await fetch("https://cdn.example.com/report-2026.pdf");
    if (r.ok) renderPDF(await r.blob());
  };
</script>

3. Charge for an MCP tool

// server.ts — MCP tool behind the guard
import { guardRequest, settledHeaderValue } from "@phantomid/merchant-kit";

server.tool("market_intel", { ticker: z.string() }, async (args, extra) => {
  const receiptHeader = (extra.headers?.["x-payment-receipt"] as string) ?? null;
  const decision = await guardRequest(receiptHeader, {
    price: "20000", // 0.02 USDC / call
    payTo: "0xYourTreasury…",
    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    network: "eip155:84532",
    resource: "mcp://example.com/market_intel",
    description: "market intelligence for one ticker",
  });
  if (!decision.allowed) {
    return { status: 402, body: decision.body }; // client agent pays & retries
  }
  return runMarketIntel(args.ticker); // decision.receipt available for audit
});
<!-- client agent page: same one-line snippet; every tool fetch auto-pays 402s -->
<script src="https://unpkg.com/@phantomid/merchant-kit/dist/snippet.min.js"
        data-phantom-key="pk_live_CLIENT_KEY" async></script>

API (Node)

  • wrapFetch(cfg, fetchImpl) — wrap any fetch with the 402→pay→retry flow.
  • configFromDataset(dataset) — build config from data-phantom-* attributes.
  • phantomGuard(cfg) / guardRequest(header, cfg) — server paywall (connect-style).
  • parseChallenge / validateReceipt / assertSettledResponse — primitives.
  • assertNoTakeClaimed — defensive rejection of receipts claiming a third-party take.
  • loadDashboardData / renderDashboardHtml / createDashboardServer — dashboard.
  • Errors: PhantomPaymentError, PhantomReceiptError, TakeClaimedError (all carry clear Spanish/English messages).

Development

npm test          # vitest (45 tests)
npm run build     # tsc + dist/snippet.min.js (<5KB enforced)
npm pack --dry-run

License

BUSL-1.1 (same as the phantom-id monorepo).