@stellar-x402/core

Core protocol schemas, challenge builders, and signature validators

Installation

pnpm add @stellar-x402/core

Functions

createX402ChallengeHeader

Constructs a base64-encoded x402 challenge string conforming to protocol specifications.

import { createX402ChallengeHeader, X402Challenge } from '@stellar-x402/core';

const challenge: X402Challenge = {
  version: 'x402-v1',
  network: 'stellar:testnet',
  asset: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC',
  price: '0.01',
  recipient: 'GCALKSGAZRJLSUEJT3M5W6LN4R7XQOLIRCOS6ZA6EDZVTZDBIIPPFKJ6',
  validUntil: Math.floor(Date.now() / 1000) + 300,
};

const headerValue = createX402ChallengeHeader(challenge);

---

parsePaymentSignatureHeader

Decodes and validates a client Payment-Signature header.

import { parsePaymentSignatureHeader } from '@stellar-x402/core';

const rawHeader = req.headers['payment-signature'];
const signature = parsePaymentSignatureHeader(rawHeader);

console.log(signature.payer);       // G... public key
console.log(signature.nonce);       // Monotonic u64 nonce
console.log(signature.authEntryXdr);// Base64 Soroban auth entry

---

Schemas (Zod)

• X402ChallengeSchema: Validates challenge parameters.
• PaymentSignatureSchema: Validates inbound payment signature structures.
• RoutePricingPolicySchema: Validates route price, asset, network, and recipient configs.