Platform Integration Guide

PLATFORM LEVEL (created once, manually)
├── Liquidity Workspace → Smart Wallet (token reserve for OTC swaps)
└── Revenue Workspace   → Smart Wallet (receives fees, forwards to treasury)
        └── settlement_address → External treasury wallet

USER LEVEL (created per user, via API on sign-up)
├── User "alice@example.com" → Smart Wallet (prepaid balance)
├── User "bob@example.com"   → Smart Wallet (prepaid balance)
└── ...

AGENT / PRODUCT LEVEL (created per listing, via API)
├── Agent "Content Strategist" → Smart Wallet (receives earnings)
├── Agent "Data Analyst Pro"   → Smart Wallet (receives earnings)
└── ...

Every entity gets its own PayDirect workspace + smart wallet. Smart wallets are gasless — no ETH needed for token transfers. The platform controls all wallets via their API keys.

async function onUserSignUp(user: { name: string; email: string }) {
  // 1. Create PayDirect workspace
  const wsRes = await fetch(`${PAYDIRECT_URL}/api/v1/workspaces`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${ADMIN_SECRET}`,
    },
    body: JSON.stringify({
      name: `User — ${user.email}`,
      ownerEmail: user.email,
      platform: "yourplatform",
      webhookUrl: "https://yourplatform.com/api/webhooks/paydirect",
    }),
  });
  const { workspaceId, walletAddress, apiKeys } = await wsRes.json();

  // 2. Create smart wallet (gasless) + set as default
  const swRes = await fetch(
    `${PAYDIRECT_URL}/api/v1/workspaces/${workspaceId}/smart-wallet`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${ADMIN_SECRET}`,
      },
      body: JSON.stringify({ setDefault: true }),
    }
  );
  const { smartWallet } = await swRes.json();

  // 3. Store credentials in your database
  await db.users.update(user.id, {
    paydirectWorkspaceId: workspaceId,
    paydirectApiKey: apiKeys.live,
    walletAddress: smartWallet.address,
  });

  return smartWallet.address;
}

User clicks "Buy 500 ADAO" ($2.50 USDC)
    │
    ├─ Leg 1: DEBIT user
    │   POST /api/v1/payouts (user's API key)
    │   → $2.50 USDC from User Wallet → Revenue Wallet
    │
    ├─ Leg 2: CREDIT user
    │   POST /api/v1/payouts (liquidity API key)
    │   → 500 ADAO from Liquidity Wallet → User Wallet
    │
    └─ Leg 3: SETTLEMENT (automatic)
        Revenue Workspace forwards USDC → Your Treasury
        (PayDirect takes 1.5% settlement fee on USDC for Free tier)

async function buyTokens(userId: string, adaoAmount: number) {
  const user = await db.users.findById(userId);
  const usdcCost = (adaoAmount * ADAO_PRICE_USD).toFixed(2);

  // Leg 1: Debit USDC from user → revenue wallet
  await fetch(`${PAYDIRECT_URL}/api/v1/payouts`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${user.paydirectApiKey}`,
    },
    body: JSON.stringify({
      tokenSymbol: "USDC",
      amount: usdcCost,
      destinationAddress: REVENUE_WALLET,
      walletType: "smart_wallet",
      idempotencyKey: `swap-${userId}-${Date.now()}-debit`,
    }),
  });

  // Leg 2: Credit ADAO from liquidity → user wallet
  await fetch(`${PAYDIRECT_URL}/api/v1/payouts`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${LIQUIDITY_API_KEY}`,
    },
    body: JSON.stringify({
      tokenSymbol: "ADAO",
      amount: String(adaoAmount),
      destinationAddress: user.walletAddress,
      walletType: "smart_wallet",
      idempotencyKey: `swap-${userId}-${Date.now()}-credit`,
    }),
  });
}

// Cron job: runs monthly (or daily to check due dates)
async function processSubscriptions() {
  const due = await db.subscriptions.findDue(); // WHERE next_billing_at <= NOW()

  for (const sub of due) {
    const user = await db.users.findById(sub.userId);

    // Check balance first
    const balRes = await fetch(`${PAYDIRECT_URL}/api/v1/wallet/balance`, {
      headers: { "Authorization": `Bearer ${user.paydirectApiKey}` },
    });
    const balance = await balRes.json();
    const adaoBalance = parseFloat(balance.smartWallet?.adao || balance.adao || "0");

    if (adaoBalance < sub.totalCost) {
      await db.subscriptions.pause(sub.id);
      await notifyUser(user, "Insufficient ADAO balance");
      continue;
    }

    // Pay agent (95%)
    const agentAmount = (sub.totalCost * 0.95).toFixed(4);
    await fetch(`${PAYDIRECT_URL}/api/v1/payouts`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${user.paydirectApiKey}`,
      },
      body: JSON.stringify({
        tokenSymbol: "ADAO",
        amount: agentAmount,
        destinationAddress: sub.agentWalletAddress,
        walletType: "smart_wallet",
        idempotencyKey: `sub-${sub.id}-${sub.period}-agent`,
      }),
    });

    // Platform fee (5%)
    const feeAmount = (sub.totalCost * 0.05).toFixed(4);
    await fetch(`${PAYDIRECT_URL}/api/v1/payouts`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${user.paydirectApiKey}`,
      },
      body: JSON.stringify({
        tokenSymbol: "ADAO",
        amount: feeAmount,
        destinationAddress: REVENUE_WALLET,
        walletType: "smart_wallet",
        idempotencyKey: `sub-${sub.id}-${sub.period}-fee`,
      }),
    });

    await db.subscriptions.markBilled(sub.id);
  }
}

// Check a user's balance
const res = await fetch(`${PAYDIRECT_URL}/api/v1/wallet/balance`, {
  headers: { "Authorization": `Bearer ${user.paydirectApiKey}` },
});
const balance = await res.json();

// Response:
// {
//   "address": "0xEOA...",
//   "eth": "0.001",
//   "usdc": "50.00",
//   "adao": "10000.00",
//   "smartWallet": {
//     "address": "0xSmartWallet...",
//     "eth": "0.00",
//     "usdc": "25.00",
//     "adao": "5000.00"
//   },
//   "defaultWalletType": "smart_wallet"
// }