Data Types & Models

All API responses include standard versioning metadata (apiVersion, timestamp).

API Response Formats

Transfer Response

interface TransferResponse {
  success: boolean;
  message: string;
  transaction: string;         // Actual blockchain transaction hash
  networkName: string;
  x402Data: X402Data;
  apiVersion: string;
  timestamp: string;
}

PayGate Response

interface PayGate {
  id: number;
  shortCode: string;
  target: string;  // targetUrl or originalFilename
  method: string;  // Single method (e.g., "GET") or comma-separated (e.g., "GET,POST,PUT")
  resourceType: "url" | "file";
  accessUrl: string;
  uploadUrl?: string;  // For file paygates only
  price: string;
  type: "credit" | "subscription";
  credits: number;
  network: string;          // Blockchain network ("base-sepolia" or "base")
  isEnabled: boolean;
  requireAuth: boolean;
  headerAuthMode: "hmac" | "plaintext";
  assumeValid: boolean;     // Skip blockchain verification after facilitator settlement
  customHeaders?: {[key: string]: string};  // Custom headers forwarded with requests
  title: string;
  description: string;
  coverUrl?: string;
  attemptCount: number;
  paymentCount: number;
  accessCount: number;
  createdAt: string;
  updatedAt: string;
  isPremium?: boolean;      // Premium PayGate indicator
  expiresAt?: string;       // Expiration date for premium PayGates
}

Update PayGate Request

interface UpdatePayGateRequest {
  title?: string;          // Display name for the PayGate
  description?: string;    // Detailed description  
  customHeaders?: {[key: string]: string};  // Custom headers to forward with requests
  price?: string;          // New price in USDC (e.g., "0.02" for $0.02)
  requireAuth?: boolean;   // Whether authentication is required
  headerAuthMode?: "hmac" | "plaintext";  // How to send sigwei_secret
  assumeValid?: boolean;   // Skip blockchain verification for faster payments
  method?: string;         // HTTP methods as comma-separated string (e.g., "GET,POST,PUT")
}

Premium PayGate Request

interface PremiumPayGateRequest {
  shortCode: string;        // Custom short code (letters, numbers, _, -)
  years: number;           // Duration in years (1-1000)
  payGateRequest: {        // Embedded standard PayGate request
    price: string;
    paymentAddress: string;
    network: string;         // Blockchain network ("base-sepolia" or "base")
    targetUrl?: string;
    originalFilename?: string;
    method?: string;         // HTTP methods as comma-separated string (e.g., "GET,POST,PUT")
    title?: string;
    description?: string;
    customHeaders?: {[key: string]: string};  // Custom headers to forward with requests
    credits?: number;
    requireAuth?: boolean;
    headerAuthMode?: "hmac" | "plaintext";
    assumeValid?: boolean;   // Skip blockchain verification for faster payments
  };
}

Premium PayGate Response

interface PremiumPayGateResponse {
  id: string;
  shortCode: string;
  accessUrl: string;
  expiresAt: string;       // ISO 8601 timestamp
  isPremium: boolean;      // Always true for premium PayGates
  apiVersion: string;
  timestamp: string;
}

Premium Extension Response

interface PremiumExtensionResponse {
  shortCode: string;
  expiresAt: string;       // New expiration date
  yearsAdded: number;
  apiVersion: string;
  timestamp: string;
}

Transaction History

interface HistoryResponse {
  success: boolean;
  history: TransactionHistoryItem[];
  pagination: PaginationMetadata;
  apiVersion: string;
  timestamp: string;
}

interface TransactionHistoryItem {
  // Base transaction fields
  id: number;
  createdAt: string;           // ISO 8601 timestamp
  updatedAt: string;           // ISO 8601 timestamp
  signerAddress: string;
  amount: string;              // Wei units as string
  network: string;
  chainId?: number;
  transactionHash?: string;
  status: string;
  error?: string;
  type: 'transfer' | 'purchase';

  // X402 protocol data
  x402Data?: X402Data;

  // Purchase-specific data (only for purchases)
  purchaseData?: PurchaseData;
}

interface X402Data {
  paymentRequirements?: string;          // JSON string
  paymentPayload?: object;               // Payment payload as JSON object
  paymentHeader?: string;
  settleResponse?: object;               // Settle response as JSON object
  typedData?: string;                    // JSON string
}

interface PurchaseData {
  shortCode?: string;
  targetUrl?: string;
  method?: string;
  purchaseType?: string;
  creditsAvailable?: number;
  creditsUsed?: number;
  paidRouteId?: number;
  paidToAddress?: string;
  title?: string;
  description?: string;
  payGateType?: string;
  totalCredits?: number;
}

interface PaginationMetadata {
  totalCount: number;
  limit: number;
  offset: number;
  hasNext: boolean;
  hasPrev: boolean;
}

Network Configuration

// Supported Networks
const NETWORKS = {
  'base-sepolia': {
    chainId: 84532,
    usdcAddress: '0x036CbD53842c5426634e7929541eC2318f3dCF7e'
  },
  'base': {
    chainId: 8453,
    usdcAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  }
};