@nerochain/x402-types

@nerochain/x402-types defines the wire format. It exports Zod schemas and TypeScript types that match @x402/core@2.11.0. Every other package in the SDK trio depends on it; consumers usually do not install it directly.

Install

pnpm add @nerochain/x402-types

What's exported

import {
  // Outer envelope
  PaymentPayloadSchema,
  PaymentRequiredSchema,
  PaymentRequirementsSchema,
  ResourceInfoSchema,
  SettlementResultSchema,
  SettlementErrorSchema,
  SettlementResponseSchema,

  // Scheme-specific inner payload schemas
  AaNativeInnerPayloadSchema,
  ExactInnerPayloadSchema,

  // HTTP header constants
  HEADER_PAYMENT_REQUIRED,    // "PAYMENT-REQUIRED"
  HEADER_PAYMENT_SIGNATURE,   // "PAYMENT-SIGNATURE"
  HEADER_PAYMENT_RESPONSE,    // "PAYMENT-RESPONSE"

  // Encoding helpers
  encodeHeaderValue,          // unknown -> base64url(JSON)
  decodeHeaderValue,          // base64url(JSON), schema -> T

  // Network helpers
  NeroNetworkSchema,
  NERO_MAINNET_CAIP,          // "eip155:1689"
  NERO_TESTNET_CAIP,          // "eip155:689"
  chainIdOf,                   // (caip) => chainId
} from "@nerochain/x402-types";

The TypeScript types are inferred from the schemas: type PaymentPayload = z.infer<typeof PaymentPayloadSchema>, and so on for the others.

Validating a payload at runtime

import { PaymentPayloadSchema, decodeHeaderValue } from "@nerochain/x402-types";

const headerValue = req.headers["payment-signature"];
const payload = decodeHeaderValue(headerValue, PaymentPayloadSchema);
// payload is fully typed; throws on malformed base64, malformed JSON, or schema mismatch

decodeHeaderValue is isomorphic — it works in both Node and browsers. It uses TextEncoder/TextDecoder and atob/btoa rather than Buffer, so client-side bundles don't need a polyfill.

Header constants vs. literal strings

Always prefer the exported constants over inline strings. The header names are PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE (uppercase with dashes). Consumers reading them off a Headers object should try both cases (HEADER_PAYMENT_RESPONSE and HEADER_PAYMENT_RESPONSE.toLowerCase()); the standard Headers.get API is case-insensitive but some intermediaries normalize headers to lowercase.

Schema versioning

The schemas track @x402/core@2.11.0 exactly. If upstream bumps the wire format, this package bumps in lockstep. The package exports a constant X402_VERSION = 2 you can compare against payload.x402Version to reject incompatible payloads early.