# @nerochain/x402-types

> Wire-format Zod schemas and TypeScript types for x402 V2.

`@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

```bash
pnpm add @nerochain/x402-types
```

## What's exported

```ts
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

```ts
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.