Type Definitions

Complete TypeScript type definitions for Shade402.

Core Types

PaymentRequestData

interface PaymentRequestData {
  max_amount_required: string;
  asset_type: string;
  asset_address: string;
  payment_address: string;
  network: string;
  expires_at: Date | string;
  nonce: string;
  payment_id: string;
  resource: string;
  description?: string;
}

PaymentAuthorizationData

interface PaymentAuthorizationData {
  payment_id: string;
  actual_amount: string;
  payment_address: string;
  asset_address: string;
  network: string;
  timestamp: Date | string;
  signature: string;
  public_key: string;
  transaction_hash?: string;
}

ErrorDetails

interface ErrorDetails {
  [key: string]: any;
}

SolanaPaymentProcessorOptions

interface SolanaPaymentProcessorOptions {
  defaultDecimals?: number;
  memo?: string;
}

Client Types

X402AutoClientOptions

interface X402AutoClientOptions {
  maxRetries?: number;
  autoRetry?: boolean;
  maxPaymentAmount?: string;
  allowLocal?: boolean;
}

Express Types

X402ConfigOptions

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

PaymentRequiredOptions

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

X402Request

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

X402ErrorMiddlewareOptions

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

Build402ResponseOptions

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

Build402ResponseResult

interface Build402ResponseResult {
  body: PaymentRequestData;
  headers: Record<string, string>;
}

Next.js Types

X402Handler

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

X402HandlerContext

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

LangChain Types

X402PaymentToolOptions

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

LangGraph Types

PaymentState

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;
}

Usage Examples

Type-safe Request Handling

import { X402Request } from '@shade402/express';

app.get('/api/data',
  paymentRequired({ amount: '0.01' }),
  (req: X402Request, res: Response) => {
    // req.payment is typed
    const payment = req.payment; // PaymentAuthorization | undefined
    
    // req.decryptedResource is typed
    const resource = req.decryptedResource; // string | undefined
  }
);

Type-safe Configuration

import { X402ConfigOptions } from '@shade402/express';

const config: X402ConfigOptions = {
  paymentAddress: process.env.PAYMENT_WALLET_ADDRESS!,
  tokenMint: process.env.TOKEN_MINT!,
  network: 'solana-devnet',
  autoVerify: true,
};

initX402(config);

Type-safe Client Options

import { X402AutoClient } from '@shade402/client';

const options = {
  maxPaymentAmount: '1.0',
  autoRetry: true,
} as const;

const client = new X402AutoClient(wallet, rpcUrl, options);

Export Summary

All types are exported from their respective packages:

// Core package
import type {
  PaymentRequestData,
  PaymentAuthorizationData,
  ErrorDetails,
  SolanaPaymentProcessorOptions,
} from '@shade402/core';

// Express package
import type {
  X402ConfigOptions,
  PaymentRequiredOptions,
  X402Request,
  X402ErrorMiddlewareOptions,
  Build402ResponseOptions,
  Build402ResponseResult,
} from '@shade402/express';

// Client package
import type {
  X402AutoClientOptions,
} from '@shade402/client';

// LangChain package
import type {
  X402PaymentToolOptions,
} from '@shade402/langchain';

// LangGraph package
import type {
  PaymentState,
} from '@shade402/langgraph';

Next Steps

• Review API Reference for complete API documentation

• Check out Examples for type usage examples