Xpaid Contracts

Type-safe API contracts for the Xpaid fintech platform. This package provides OpenRPC-compatible contracts for all API endpoints, ensuring end-to-end type safety across client and server implementations.

Features

• 🔒 Type Safety - Full TypeScript support with Zod validation
• 📝 OpenRPC Compatible - Standardized API contracts
• 🚀 Tree Shakeable - Optimized bundle size
• 📚 Auto-generated Types - Client and server types
• 🔄 Versioned API - Structured with /v1 prefix for future compatibility
• ✨ ORPC Integration - Built on ORPC for type-safe API development

Installation

# From monorepo root
pnpm install

# As external dependency (if published)
pnpm add @xpaid/contracts

Usage

Import Contracts

import type { Router } from 'xpaid-contracts/app'
// Use the contract in your API server
import { createServer } from '@orpc/server'

import { contract } from 'xpaid-contracts/app'

const server = createServer(contract)

Available Contracts

• xpaid-contracts/app - App API contracts

Contract Structure

Contracts are organized by version and route:

contract = {
  v1: {
    kyc: {
      start: any,  // Start KYC process
    },
    rate: {
      get: any,,    // Get exchange rate
      preview: any, // Preview rate
      list: any,  // List available rates
    },
    order: {
      get: any,    // Get order details
      create: any, // Create new order
      cancel: any, // Cancel order
    },
    self: {
      customer: {
        get: any,    // Get customer info
        update: any, // Update customer
        agree: any,  // Agree to terms
      },
      kyc: {
        get: any,    // Get KYC status
      },
      bankDetails: {
        get: any,    // Get bank details
        list: any,   // List all bank details
        create: any, // Create bank details
        update: any, // Update bank details
        delete: any, // Delete bank details
      },
      orders: {
        list: any,   // List user orders
      }
    }
  }
}

Type Safety

The contracts provide full type safety:

import type { Router } from 'xpaid-contracts/app'

// Router types are automatically inferred
const response: Router['v1']['kyc']['start']['output'] = any,

Validation

All request/response validation is handled by Zod schemas included in the contracts.

Development

# From monorepo root
pnpm run build --filter xpaid-contracts

# Watch mode
pnpm run dev --filter xpaid-contracts

Project Structure

packages/contracts/
├── src/
│   └── app/
│       ├── index.ts           # Contract exports
│       └── routes/
│           └── v1/            # Version 1 routes
│               ├── index.ts   # Route definitions
│               └── *.ts       # Individual endpoints
└── package.json

API Endpoints

KYC

• POST /v1/kyc/start - Start KYC verification process

Rates

• GET /v1/rate/get - Get current exchange rate
• POST /v1/rate/preview - Preview exchange rate
• GET /v1/rate/list - List available rates

Orders

• GET /v1/order/get - Get order by ID
• POST /v1/order/create - Create new order
• POST /v1/order/cancel - Cancel existing order

Self (User)

• GET /v1/self/customer/get - Get user customer info

• POST /v1/self/customer/update - Update customer info

• POST /v1/self/customer/agree - Agree to terms

• GET /v1/self/kyc/get - Get KYC status

• GET /v1/self/bankDetails/get - Get bank details

• GET /v1/self/bankDetails/list - List all bank details

• POST /v1/self/bankDetails/create - Create bank details

• POST /v1/self/bankDetails/update - Update bank details

• POST /v1/self/bankDetails/delete - Delete bank details

• GET /v1/self/orders/list - List user orders

Related Packages

• @orpc/contract - Contract definition utilities
• @orpc/server - Server implementation
• @orpc/client - Client implementation