@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:4173Copy-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 fromdata-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-runLicense
BUSL-1.1 (same as the phantom-id monorepo).
