Workspaces API

Create and manage workspaces programmatically. Each workspace gets a unique CDP wallet on Base, sandbox + live API keys, and optional webhook configuration.

Overview
What is a workspace?

A workspace is the top-level container in PayDirect. It represents a merchant, app, agent, or user account. Each workspace gets:

  • A unique CDP EOA wallet on Base mainnet (auto-provisioned)
  • Optional smart wallet for gasless transactions (on-demand)
  • Separate sandbox and live API keys
  • Optional settlement wallet for payment forwarding
  • Optional webhook configuration
  • Independent payment history and fee accounting
Workspace Lifecycle:

  1. POST /api/v1/workspaces         → workspace + EOA wallet + API keys
  2. POST /api/v1/workspaces/:id/smart-wallet  → smart wallet (gasless)
  3. Use API keys for payouts, payments, balance checks
  4. Webhooks deliver real-time events to your endpoint
POST
/api/v1/workspaces
Create Workspace
Public endpoint — no authentication required. Creates a new workspace with a CDP wallet and API keys. Rate-limited to 3 workspaces per email (contact support to increase). Pass ADMIN_API_SECRET for admin capabilities.

Request Body

FieldTypeRequiredDescription
namestringYesWorkspace name (min 2 chars)
ownerEmailstringYesOwner email address
platformstringNoPlatform identifier (e.g. "cowork", "venturebuilder"). Used for filtering in admin.
settlementWalletstringNo0x address for payment forwarding
webhookUrlstringNoWebhook endpoint URL
webhookEventsstring[]NoEvent filter (defaults to all events)
metadataobjectNoCustom JSON metadata (admin only)

Example Request

curl -X POST https://www.paydirect.com/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "ownerEmail": "dev@example.com",
    "settlementWallet": "0x1234...abcd",
    "webhookUrl": "https://myapp.com/webhooks/paydirect"
  }'

Response
201

{
  "workspaceId": "a1b2c3d4-...",
  "name": "My Agent",
  "walletAddress": "0xAbCd...1234",
  "environment": "live",
  "apiKeys": {
    "sandbox": "pd_test_...",
    "live": "pd_live_..."
  },
  "webhook": {
    "url": "https://myapp.com/webhooks/paydirect",
    "signingSecret": "whsec_..."
  }
}
GET
/api/v1/workspaces
List Workspaces
Admin only. Returns all workspaces with wallet addresses, paginated.

Authentication

Authorization: Bearer <ADMIN_API_SECRET>

Query Parameters

ParamDefaultDescription
limit50Max 100
offset0Pagination offset
GET
/api/v1/workspaces/:id
Get Workspace
Admin only. Returns workspace details including wallet address, API keys, webhooks, and payment stats.

Response includes

  • Workspace info (name, email, settlement address, plan, active status)
  • Wallet address and CDP wallet ID
  • API keys (id, name, environment, active status)
  • Webhook subscriptions
  • Payment stats (total, completed, pending, volume by token, fees)
PATCH
/api/v1/workspaces/:id
Update Workspace
Admin only. Update workspace settings.

Request Body (all fields optional)

FieldTypeDescription
namestringWorkspace name
settlementWalletstringUpdate merchant/settlement wallet
isActivebooleanEnable/disable workspace
suspendedbooleanSuspend/unsuspend workspace
metadataobjectCustom JSON metadata
POST
/api/v1/workspaces/:id/smart-wallet
Create Smart Wallet
Create a gasless smart wallet for a workspace. Authenticates via workspace API key or admin secret. Idempotent — returns existing wallet if already created.

Authentication

MethodDescription
Bearer pd_live_...Workspace API key (must belong to the workspace)
Bearer ADMIN_SECRETAdmin secret — can create for any workspace

Request Body (optional)

FieldTypeDescription
setDefaultbooleanIf true, set smart_wallet as workspace default

Example Request

curl -X POST https://www.paydirect.com/api/v1/workspaces/ws_abc123/smart-wallet \
  -H "Authorization: Bearer pd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "setDefault": true }'

Response
201

{
  "success": true,
  "workspaceId": "ws_abc123",
  "smartWallet": {
    "address": "0xSmartWallet...",
    "ownerAddress": "0xEOAWallet...",
    "walletId": "pd-sw-abc123"
  },
  "defaultWalletType": "smart_wallet"
}
GET
/api/v1/workspaces/:id/smart-wallet
Get Wallet Details
Returns EOA and smart wallet details for a workspace.

Response
200

{
  "workspaceId": "ws_abc123",
  "eoa": {
    "address": "0xEOAWallet...",
    "createdAt": "2026-01-15T10:00:00Z"
  },
  "smartWallet": {
    "address": "0xSmartWallet...",
    "walletId": "pd-sw-abc123",
    "createdAt": "2026-01-15T10:01:00Z"
  },
  "defaultWalletType": "smart_wallet"
}
PATCH
/api/v1/workspaces/:id/smart-wallet
Set Default Wallet Type
Set which wallet type is used when walletType is omitted from API requests.

Request Body

FieldTypeDescription
defaultWalletTypestring"workspace" (EOA) or "smart_wallet"
Platform Integration Example
Full workspace + smart wallet provisioning on user sign-up
const PAYDIRECT_URL = "https://www.paydirect.com";
const ADMIN_SECRET = process.env.PAYDIRECT_ADMIN_SECRET;

async function provisionUserWallet(user: { name: string; email: string }) {
  // Step 1: Create 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.name}`,
      ownerEmail: user.email,
      platform: "cowork",
      webhookUrl: "https://cowork.com/api/webhooks/paydirect",
    }),
  });
  const { workspaceId, apiKeys } = await wsRes.json();

  // Step 2: Create smart wallet + 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();

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

  return { workspaceId, walletAddress: smartWallet.address };
}

// Step 4: Use the API key for transfers
async function sendTokens(userApiKey: string, to: string, amount: string) {
  return fetch(`${PAYDIRECT_URL}/api/v1/payouts`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${userApiKey}`,
    },
    body: JSON.stringify({
      tokenSymbol: "ADAO",
      amount,
      destinationAddress: to,
      walletType: "smart_wallet",
    }),
  });
}