x402 v2 payment transport for the Me2eM payment layer: the base64 header codec (PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE), a payment-aware fetch client, server helpers, the facilitator contract and the Me2eM extra.me2em extension.
x402 is transport, not policy: who pays is attestation / Pact, how much is PaymentRequest, how it executes is a PaymentAdapter (@me2em/solana), who confirms is the facilitator. This package moves the signed artifacts over HTTP โ nothing else. Everything is fail-closed: an unknown version, scheme, network or error reason is always a refusal, never a success.
M1 release (rc.1). Codec, client, server helpers, extra.me2em, the FacilitatorClient contract and B402Facilitator (opt-in subpath, @experimental) are shipped. The Solana PaymentSigner arrives in @me2em/solana 1.1.0-rc.1 (M2). x402 v1 is not supported.
pnpm add @me2em/x402 @me2em/core
๐ก
@me2em/coreis a peer dependency (>=1.0.0-rc.7 <2.0.0-0) โ the x402 wire types, the structural guards and the error codes live there. The floor is rc.7 becauseisX402SettleResponseaccepts the upstream ยง5.3.2 empty-transaction failure settles only since then. There are no runtime dependencies โ the transport uses the globalfetch(Node โฅ 22.6, browsers).B402Facilitatoris opt-in:import { B402Facilitator } from '@me2em/x402/b402'โ the main entry stays free of any concrete facilitator.
import { createPaymentFetch, readSettlement, type PaymentSigner } from '@me2em/x402';
const signer: PaymentSigner = {
capabilities: [{ scheme: 'exact', network: 'solana:devnet' }],
async signPayment(requirements, resource) {
// chain-specific signing โ e.g. @me2em/solana's SolanaX402Signer (M2)
return myWallet.signTransfer(requirements, resource);
},
};
const pay = createPaymentFetch({ signer });
const res = await pay('https://api.example.com/premium-data');
if (res.status === 402) throw new Error('payment refused โ see the 402 body');
const settle = readSettlement(res); // null | X402SettleResponse (throws on a broken header)
if (settle && !settle.success) {
throw new Error(`settlement failed: ${settle.errorReason}`);
}
Behavior: a 200 or any non-402 response passes through untouched; a 402 with a parseable PAYMENT-REQUIRED selects the first option covered by signer.capabilities (or your selectRequirements), signs it and replays exactly once with PAYMENT-SIGNATURE โ the wrapper never retries after the payment attempt, so you can never pay twice by accident. Errors: PAYMENT_REQUIRED_MALFORMED, VERSION_UNSUPPORTED, NO_VIABLE_OPTION, SIGNER_REJECTED (the original error rides in details.cause).
import {
paymentRequiredResponse, readPaymentHeader, settlementHeader,
assertValidX402Config, type X402Config,
} from '@me2em/x402';
import { B402Facilitator } from '@me2em/x402/b402';
const config: X402Config = {
facilitator: new B402Facilitator({
baseUrl: process.env.B402_URL!, // ยง8 of the ะขะ โ pending, @experimental
auth: { headers: () => ({ authorization: `Bearer ${getJwt()}` }) },
}),
mode: 'pact-aware',
regulatoryProfile: 'none',
};
assertValidX402Config(config); // once at startup โ X402ConfigError (TypeError) on contradictions
server.on('GET /premium-data', async (req) => {
const payload = readPaymentHeader(req.headers, 'https://api.example.com/premium-data');
if (!payload) return paymentRequiredResponse(buildPaymentRequired()); // 402 + header
// your checks: accepted โ accepts[], attestation policy, Pact (agreementProof)โฆ
const verify = await config.facilitator.verify(payload.accepted, payload);
if (!verify.isValid) return new Response('invalid payment', { status: 402 });
const settle = await config.facilitator.settle(payload.accepted, payload);
if (!settle.success) throw new SettlementError(settle.errorReason); // your policy
return new Response(premiumData, { status: 200, headers: settlementHeader(settle) });
});
The verify โ resource โ settle orchestration is the application's (ะขะ ยง3.4 table). X402Config declares policy; it is never enforced per payment and never passed to the client API.
extra.me2em โ Me2eM metadata on the wireimport { withMe2emExtra, readMe2emExtra } from '@me2em/x402';
const requirements = withMe2emExtra(option, {
sellerId: 'base64url(SellerPubkey)',
reference: 'base58-reference',
agreementProof: base64(pactProofBytes), // opaque โ x402 never interprets it
});
const me2em = readMe2emExtra(buyerAccepted); // null when absent/malformed โ never throws
Two formats, two names: core's Me2emExtra is the application-side shape (all fields optional, agreementProof?: Uint8Array); X402Me2emExtra is the wire shape (sellerId required, base64 strings). The nested me2em key never collides with the x402-reserved extra keys (assetTransferMethod, paymentFlow, name, version).
Every transport failure is X402Error (code + optional details); configuration mistakes are X402ConfigError (a TypeError). Unknown runtime errorReason / me2emError values are surfaced in details and treated as failures โ never mapped to success.
| Code | Thrown by |
|---|---|
PAYMENT_REQUIRED_MALFORMED |
codec/client โ bad base64/JSON/shape, 402 without a header, size overflow on decode |
PAYMENT_PAYLOAD_MALFORMED |
codec โ broken PAYMENT-SIGNATURE |
PAYMENT_RESPONSE_MALFORMED |
readSettlement โ broken PAYMENT-RESPONSE (never silently null) |
VERSION_UNSUPPORTED |
codec โ well-formed JSON with x402Version !== 2 |
NO_VIABLE_OPTION |
client โ no accepts entry covered by capabilities |
SIGNER_REJECTED |
client โ signPayment threw (details.cause) |
RESOURCE_MISMATCH |
readPaymentHeader โ payload resource โ expected URL |
FACILITATOR_ERROR |
facilitators โ details: { phase, kind: network|timeout|http_5xx|http_4xx|auth|invalid_response } |
SETTLEMENT_FAILED |
application โ settle returned success: false (your policy, your throw) |
ME2EM_EXTRA_INVALID |
withMe2emExtra โ malformed Me2eM extra |
test/fixtures/spec-vectors.json carries the verbatim JSON examples of the upstream x402 v2 specification (x402-foundation/x402, specs/x402-specification-v2.md, commit 51a0664c2b7826e3cb02595481eb6848a1b11815, 2026-10-26) โ the codec is pinned to the real wire examples, not only to our own fixtures.
SolanaX402Signer in @me2em/solana 1.1.0-rc.1 (blockhash injection, explicit CAIP-2 capabilities).@me2em/facilitator โ self-hosted facilitator, separate ะขะ; FacilitatorClient here is contract-only.@me2em/pact โ Pact negotiations; only the opaque agreementProof format touches this package.