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

webmcp-payments

v0.4.2

Published

x402 (HTTP 402) payment gate, on-chain verifier and WebMCP pricing discovery for EVM chains (Base, Arbitrum, Optimism). No platform fee by default.

Downloads

348

Readme

webmcp-payments

Server-side helpers for charging AI agents in stablecoins over x402 (HTTP 402 Payment Required) on EVM chains:

  • PaymentGate wraps a tool handler or an Express route. If the caller hasn't paid, it answers 402 with an x402 payment envelope. If the caller sends a payment proof, it checks the transaction on-chain before running your handler.
  • PaymentVerifier checks an ERC-20 Transfer on-chain (via viem) against a payment envelope.
  • PaymentDiscovery publishes per-tool pricing in a WebMCP-style manifest so agents can see costs before calling.

Supported chains: base, base-sepolia, arbitrum, optimism. Tokens: USDC (all chains), USDT and DAI (not on base-sepolia).

No platform fee is charged by default. See Fees.

Install

npm install webmcp-payments viem

Node.js 18 or newer. Ships CommonJS and ESM builds with TypeScript types.

Usage

Gate a tool handler

import { PaymentGate } from 'webmcp-payments';

const gate = new PaymentGate({
  merchantWallet: '0xYourMerchantWallet',   // receives the payment
  chain: 'base',                            // default: 'base'
  acceptedTokens: ['USDC'],                 // default: ['USDC']
});

const premiumData = gate.protect(
  gate.require({ amount: '0.50', token: 'USDC', chain: 'base' }),
  async (input: { symbol: string }) => ({ symbol: input.symbol, price: 123 }),
  'premium-data'                            // resource id
);

const result = await premiumData({ symbol: 'ETH' });
// No payment yet -> { success: false, status: 402, paymentRequired: { protocol: 'x402', amount: '500000', recipient: '0xYourMerchantWallet', nonce, ... } }

// After the agent pays on-chain, call again with the proof:
await premiumData({ symbol: 'ETH' }, {
  paymentProof: { txHash: '0x…', chain: 'base', nonce: result.paymentRequired!.nonce, payer: '0xAgentWallet' },
});
// -> { success: true, status: 200, result: { … } } once the transfer is verified

Other pricing helpers: gate.metered({ perUnit, unit, maxAmount?, token, chain }) and gate.subscription({ amount, interval, token, chain }). The envelope amount for metered pricing is one unit (perUnit).

Express middleware

app.post('/api/premium', gate.express(gate.require({ amount: '0.50', token: 'USDC', chain: 'base' })), handler);

Without a valid proof the route answers 402 with { error: 'Payment Required', paymentRequired: <envelope> }. The agent retries with these headers: X-Payment-Tx, X-Payment-Chain, X-Payment-Nonce, X-Payment-Payer. On success the middleware sets X-Payment-Verified: true and calls next().

Verify a payment yourself

import { PaymentVerifier } from 'webmcp-payments/verifier';

const verifier = new PaymentVerifier({ confirmations: 1, rpcUrls: { base: 'https://your-rpc' } });
const res = await verifier.verify(proof, envelope); // { verified: boolean, error?, txHash?, blockNumber? }

Pricing discovery

import { createDiscovery } from 'webmcp-payments/discovery';

const discovery = createDiscovery({ defaultChain: 'base' });
discovery.register({ name: 'premium-data', description: 'Premium market data', pricing: gate.require({ amount: '0.50', token: 'USDC', chain: 'base' }) });
discovery.registerFree('ping', 'Health check');

discovery.toManifest();          // { version: '1', tools: [...], paymentConfig: { protocol: 'x402', ... } }
discovery.toDiscoveryResponse(); // { status: 200, headers, body } for e.g. GET /.well-known/webmcp

Exports

| Entry point | Exports | |---|---| | webmcp-payments | PaymentGate, extractProofFromHeaders, PaymentVerifier, PaymentDiscovery, createDiscovery, PLATFORM_FEE_RATE, DEFAULT_FEE_RATE, WEBMCP_TREASURY (deprecated, unused), CHAIN_CONFIGS, TOKEN_DECIMALS, toSmallestUnit, fromSmallestUnit, calculateFee, generateNonce, getTokenAddress, VERSION, plus types | | webmcp-payments/middleware | PaymentGate, extractProofFromHeaders | | webmcp-payments/verifier | PaymentVerifier | | webmcp-payments/discovery | PaymentDiscovery, createDiscovery |

Fees

The default fee is 0%. With the default configuration the 402 envelope asks the agent to pay the full price to your merchantWallet, and it contains no feeRecipient or feeAmount fields. Nothing is sent to anyone else, and the package has no built-in fee destination.

Charging a fee. To add a fee you must pass both feeRate (greater than 0 and less than 1) and your own feeWallet:

const gate = new PaymentGate({
  merchantWallet: '0xYourMerchantWallet',
  feeRate: 0.01,                    // 1%
  feeWallet: '0xYourFeeWallet',     // required whenever feeRate > 0
});

Passing feeRate > 0 without feeWallet throws feeWallet is required when feeRate > 0. With a fee, the envelope's amount is the price minus the fee (what the merchant receives), and the envelope adds feeRecipient (your feeWallet) and feeAmount (in the token's smallest unit). For a 0.50 USDC price at 1%: amount: '495000', feeAmount: '5000'. With feeRate left out or set to 0, feeWallet is ignored.

Change from 0.3.x. Versions 0.3.0 and 0.3.1 applied an undocumented 1% fee by default, sent to 0xd7cF53B92A145A9EAFF210f56664865714F3D7BE unless you overrode feeWallet/feeRate. From 0.4.0 the default is 0% and a fee only ever goes to a feeWallet you supply. The WEBMCP_TREASURY export still exists so old imports compile, but it's deprecated and unused; don't use it. See CHANGELOG.md.

Security notes and known limitations

Read these before using the package with real funds.

  • Set WEBMCP_ACCESS_TOKEN_SECRET. PaymentGate accepts session tokens (X-Payment-Token header / context.accessToken) signed with this environment variable. If it's unset, a built-in default secret is used, and anyone who knows it can mint a token that skips payment. Set it to a long random value in production.
  • Session tokens don't carry over. Tokens returned after verification are signed by the gate's internal verifier with a random per-process secret, so they won't validate on later requests. Treat each request as needing its own proof.
  • No replay protection. The library doesn't remember which transaction hashes it has already accepted, and the gate takes the nonce from the proof. Keep your own store of used txHash values and reject repeats.
  • The payer isn't checked. PaymentVerifier checks that the merchant (and, if enabled, the fee wallet) received at least the expected amount, but doesn't check that the transfer came from proof.payer.
  • Fees aren't enforced on-chain. If you configure a fee, a transaction that pays the merchant its net amount still verifies even without the fee transfer.
  • No public source repository exists for this package. The published files include source maps with the full TypeScript source.

License

MIT