API Reference

Complete API reference for all Shade402 packages.

Core Package

PaymentRequest

Payment request model.

class PaymentRequest {
  maxAmountRequired: string;
  assetType: string;
  assetAddress: string;
  paymentAddress: string;
  network: string;
  expiresAt: Date;
  nonce: string;
  paymentId: string;
  resource: string;
  description?: string;

  constructor(data: PaymentRequestData): PaymentRequest;
  isExpired(): boolean;
  toDict(): Record<string, any>;
  toJSON(): string;
  static fromDict(data: unknown): PaymentRequest;
}

PaymentAuthorization

Payment authorization model.

class PaymentAuthorization {
  paymentId: string;
  actualAmount: string;
  paymentAddress: string;
  assetAddress: string;
  network: string;
  timestamp: Date;
  signature: string;
  publicKey: string;
  transactionHash?: string;

  constructor(data: PaymentAuthorizationData): PaymentAuthorization;
  toHeaderValue(): string;
  toDict(): Record<string, any>;
  toJSON(): string;
  static fromHeader(headerValue: string): PaymentAuthorization;
}

SolanaPaymentProcessor

Solana payment processor.

class SolanaPaymentProcessor {
  constructor(
    rpcUrl: string,
    keypair?: Keypair,
    options?: SolanaPaymentProcessorOptions
  );

  async createPaymentTransaction(
    request: PaymentRequest,
    amount: string,
    payerKeypair: Keypair,
    decimals?: number,
    options?: SolanaPaymentProcessorOptions
  ): Promise<Transaction>;

  async signAndSendTransaction(
    transaction: Transaction,
    keypair: Keypair
  ): Promise<string>;

  async verifyPayment(
    request: PaymentRequest,
    authorization: PaymentAuthorization
  ): Promise<boolean>;

  async getTokenBalance(
    publicKey: PublicKey | string,
    tokenMint: PublicKey | string
  ): Promise<number>;

  async close(): Promise<void>;
}

Encryption Functions

function encryptResource(plaintext: string, publicKeyPem: string): string;
function decryptResource(encryptedBase64: string, privateKeyPem: string): string;
function generateKeyPair(): { publicKey: string; privateKey: string };

Error Classes

class X402Error extends Error {
  code: string;
  details: ErrorDetails;
}

class PaymentRequiredError extends X402Error {
  paymentRequest: any;
}

class PaymentExpiredError extends X402Error {
  paymentRequest: any;
}

class InsufficientFundsError extends X402Error {
  requiredAmount: string;
  availableAmount: string;
}

class PaymentVerificationError extends X402Error {}
class TransactionBroadcastError extends X402Error {}
class InvalidPaymentRequestError extends X402Error {}

Client Package

X402Client

Explicit client with manual payment control.

class X402Client {
  constructor(
    walletKeypair: Keypair,
    rpcUrl?: string,
    httpClient?: AxiosInstance,
    allowLocal?: boolean
  );

  async get(
    url: string,
    options?: AxiosRequestConfig & {
      payment?: PaymentAuthorization;
      encryptedResource?: string;
    }
  ): Promise<AxiosResponse>;

  async post(
    url: string,
    data?: any,
    options?: AxiosRequestConfig & {
      payment?: PaymentAuthorization;
      encryptedResource?: string;
    }
  ): Promise<AxiosResponse>;

  async put(
    url: string,
    data?: any,
    options?: AxiosRequestConfig & {
      payment?: PaymentAuthorization;
      encryptedResource?: string;
    }
  ): Promise<AxiosResponse>;

  async delete(
    url: string,
    options?: AxiosRequestConfig & {
      payment?: PaymentAuthorization;
      encryptedResource?: string;
    }
  ): Promise<AxiosResponse>;

  async request(
    method: string,
    url: string,
    options?: AxiosRequestConfig & {
      payment?: PaymentAuthorization;
      encryptedResource?: string;
    }
  ): Promise<AxiosResponse>;

  paymentRequired(response: AxiosResponse): boolean;
  parsePaymentRequest(response: AxiosResponse): PaymentRequest;
  encryptResource(resource: string): string;
  getServerPublicKey(): string | null;
  async createPayment(
    request: PaymentRequest,
    amount?: string
  ): Promise<PaymentAuthorization>;
  async close(): Promise<void>;
}

X402AutoClient

Automatic client with automatic payment handling.

class X402AutoClient {
  constructor(
    walletKeypair: Keypair,
    rpcUrl?: string,
    options?: {
      maxRetries?: number;
      autoRetry?: boolean;
      maxPaymentAmount?: string;
      allowLocal?: boolean;
    }
  );

  async fetch(
    url: string,
    options?: AxiosRequestConfig & {
      method?: string;
      autoRetry?: boolean;
    }
  ): Promise<AxiosResponse>;

  async get(
    url: string,
    options?: AxiosRequestConfig & { autoRetry?: boolean }
  ): Promise<AxiosResponse>;

  async post(
    url: string,
    data?: any,
    options?: AxiosRequestConfig & { autoRetry?: boolean }
  ): Promise<AxiosResponse>;

  async put(
    url: string,
    data?: any,
    options?: AxiosRequestConfig & { autoRetry?: boolean }
  ): Promise<AxiosResponse>;

  async delete(
    url: string,
    options?: AxiosRequestConfig & { autoRetry?: boolean }
  ): Promise<AxiosResponse>;

  async close(): Promise<void>;
}

Express Package

Configuration

function initX402(config: X402ConfigOptions): void;
function getConfig(): X402ConfigOptions | undefined;
function isInitialized(): boolean;

interface X402ConfigOptions {
  paymentAddress: string;
  tokenMint: string;
  network: string;
  rpcUrl?: string;
  autoVerify?: boolean;
  defaultAmount?: string;
  paymentTimeout?: number;
  encryptionPublicKey?: string;
  encryptionPrivateKey?: string;
}

Middleware

function paymentRequired(options: PaymentRequiredOptions): RequestHandler;

interface PaymentRequiredOptions {
  amount: string;
  paymentAddress?: string;
  tokenMint?: string;
  network?: string;
  description?: string;
  expiresIn?: number;
  autoVerify?: boolean;
}

interface X402Request extends Request {
  payment?: PaymentAuthorization;
  decryptedResource?: string;
}

Error Middleware

function x402ErrorMiddleware(
  options?: X402ErrorMiddlewareOptions
): ErrorRequestHandler;

interface X402ErrorMiddlewareOptions {
  includeStack?: boolean;
  logErrors?: boolean;
  onError?: (error: Error, req: Request, res: Response) => void;
}

Response Builders

function build402Response(
  options: Build402ResponseOptions
): PaymentRequestData;

function build402ResponseWithEncryption(
  options: Build402ResponseOptions & {
    encryptionPublicKey?: string;
  }
): {
  body: PaymentRequestData;
  headers: Record<string, string>;
};

interface Build402ResponseOptions {
  amount: string;
  paymentAddress: string;
  tokenMint: string;
  network: string;
  resource: string;
  description?: string;
  expiresIn?: number;
}

Next.js Package

Configuration

function initX402(config: X402ConfigOptions): void;
function getConfig(): X402ConfigOptions | undefined;
function isInitialized(): boolean;

Middleware

function withPayment<T extends NextRequest | NextApiRequest>(
  options: PaymentRequiredOptions,
  handler: X402Handler<T>
): X402Handler<T>;

interface PaymentRequiredOptions {
  amount: string;
  paymentAddress?: string;
  tokenMint?: string;
  network?: string;
  description?: string;
  expiresIn?: number;
  autoVerify?: boolean;
}

interface X402HandlerContext {
  payment?: PaymentAuthorization;
  decryptedResource?: string;
}

type X402Handler<T> = (
  req: T,
  context: X402HandlerContext
) => Promise<NextResponse | void>;

LangChain Package

Payment Tool

function createX402PaymentTool(
  options: X402PaymentToolOptions
): DynamicStructuredTool;

class X402PaymentTool extends DynamicStructuredTool {
  constructor(options: X402PaymentToolOptions);
}

interface X402PaymentToolOptions {
  walletKeypair: Keypair;
  rpcUrl?: string;
  maxPayment?: string;
  name?: string;
  description?: string;
  allowLocal?: boolean;
}

LangGraph Package

Payment Nodes

async function paymentNode(state: PaymentState): Promise<PaymentState>;
async function fetchWithPaymentNode(state: PaymentState): Promise<PaymentState>;
function checkPaymentRequired(state: PaymentState): string;
function checkPaymentCompleted(state: PaymentState): string;

interface PaymentState {
  wallet_keypair?: Keypair;
  api_url?: string;
  api_response?: string;
  payment_completed?: boolean;
  payment_error?: string | null;
  payment_required?: boolean;
  max_payment_amount?: string;
  http_method?: string;
  allow_local?: boolean;
  rpc_url?: string;
  [key: string]: any;
}

Type Definitions

All packages export TypeScript type definitions. See Type Definitions for complete reference.

Next Steps

• Review Getting Started for usage examples

• Check out Examples for complete code samples

• See Best Practices for guidelines