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/workspacesCreate 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
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Workspace name (min 2 chars) |
| ownerEmail | string | Yes | Owner email address |
| platform | string | No | Platform identifier (e.g. "cowork", "venturebuilder"). Used for filtering in admin. |
| settlementWallet | string | No | 0x address for payment forwarding |
| webhookUrl | string | No | Webhook endpoint URL |
| webhookEvents | string[] | No | Event filter (defaults to all events) |
| metadata | object | No | Custom 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/workspacesList Workspaces
Admin only. Returns all workspaces with wallet addresses, paginated.
Authentication
Authorization: Bearer <ADMIN_API_SECRET>Query Parameters
| Param | Default | Description |
|---|---|---|
| limit | 50 | Max 100 |
| offset | 0 | Pagination offset |
GET
/api/v1/workspaces/:idGet 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/:idUpdate Workspace
Admin only. Update workspace settings.
Request Body (all fields optional)
| Field | Type | Description |
|---|---|---|
| name | string | Workspace name |
| settlementWallet | string | Update merchant/settlement wallet |
| isActive | boolean | Enable/disable workspace |
| suspended | boolean | Suspend/unsuspend workspace |
| metadata | object | Custom JSON metadata |
POST
/api/v1/workspaces/:id/smart-walletCreate 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
| Method | Description |
|---|---|
| Bearer pd_live_... | Workspace API key (must belong to the workspace) |
| Bearer ADMIN_SECRET | Admin secret — can create for any workspace |
Request Body (optional)
| Field | Type | Description |
|---|---|---|
| setDefault | boolean | If 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-walletGet 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-walletSet Default Wallet Type
Set which wallet type is used when
walletType is omitted from API requests.Request Body
| Field | Type | Description |
|---|---|---|
| defaultWalletType | string | "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",
}),
});
}