API Documentation

Wallet API

Check your workspace wallet balances on Base. Each workspace has an EOA wallet and can optionally enable a Smart Wallet for gasless transactions. Both hold USDC, ETH, and ADAO.

How Workspace Wallets Work

Dual wallet architecture: EOA + optional Smart Wallet

EOA Wallet

Auto-provisioned on workspace creation. Standard externally owned account managed by CDP.

Smart Wallet

Optional ERC-4337 smart account. Enable on-demand for gasless transactions via CDP Paymaster.

Gasless Transfers

Smart wallet token transfers are gas-sponsored. No ETH needed for USDC/ADAO payouts.

CDP-Managed

Both wallet types secured by Coinbase Developer Platform. Keys managed by CDP.

Workspace
├── EOA Wallet (0xAbc...)          ← always present
│   ├── ETH   — Gas for transactions
│   ├── USDC  — Stablecoin
│   └── ADAO  — Utility token
│
└── Smart Wallet (0xDef...)        ← optional, gasless
    ├── USDC  — Gasless transfers via Paymaster
    ├── ADAO  — Gasless transfers via Paymaster
    └── ETH   — Gas is sponsored (only needed for value transfers)

API Routes accept walletType: "eoa" | "smart_wallet"
Falls back to workspace default_wallet_type setting

GET

/api/v1/wallet/balance

Get current workspace wallet balances

Headers

Header	Required	Description
`Authorization`	Yes	Bearer pd_test_... or pd_live_...

cURL Example

curl https://www.paydirect.com/api/v1/wallet/balance \
  -H "Authorization: Bearer pd_live_abc123..."

TypeScript SDK

const balance = await client.getWalletBalance();

// EOA Wallet (always present)
console.log(balance.eoa.address);  // "0xAbc..."
console.log(balance.eoa.usdc);     // "1234.56"

// Smart Wallet (null if not enabled)
console.log(balance.smartWallet?.address);  // "0xDef..."
console.log(balance.smartWallet?.usdc);     // "500.00"

console.log(balance.defaultWalletType);  // "workspace" or "smart_wallet"

Response (200 OK)

{
  "eoa": {
    "address": "0xYourEOAWallet...",
    "eth": "0.05",
    "usdc": "1234.56",
    "adao": "50000.00"
  },
  "smartWallet": {
    "address": "0xYourSmartWallet...",
    "eth": "0.00",
    "usdc": "500.00",
    "adao": "10000.00"
  },
  "defaultWalletType": "workspace",
  "environment": "live"
}

Smart Wallet: The smartWallet field is null if the workspace has not enabled a smart wallet. Enable one via POST /api/workspaces/smart-wallet or in the dashboard under Settings > Wallets.

Auto gas funding: PayDirect automatically funds workspace wallets with ETH for gas on creation and tops them up periodically via a background cron. If eth is "0" and you have ADAO or USDC, the response includes a warning field — the gas cron should top it up shortly. On Base, gas costs ~$0.001 per transaction.

Response Fields

Field	Type	Description
`eoa`	object	EOA wallet balances: `address`, `eth`, `usdc`, `adao`
`smartWallet`	object \| null	Smart wallet balances (same shape as `eoa`). `null` if not enabled.
`defaultWalletType`	string	`"workspace"` (EOA) or `"smart_wallet"`
`environment`	string	`"sandbox"` (Base Sepolia) or `"live"` (Base Mainnet)

GET

/api/v1/wallet/stats

Aggregated workspace portfolio — balances and transaction history across EOA + smart wallet. Switching default wallet type does not reset counts.

For agents: Use this endpoint for cumulative volume, payment counts, and combined balances. Per-wallet breakdown is included under wallets.eoa and wallets.smartWallet.

cURL Example

curl https://www.paydirect.com/api/v1/wallet/stats \
  -H "Authorization: Bearer pd_live_abc123..."

Response (200 OK)

{
  "workspaceId": "uuid",
  "environment": "live",
  "defaultWalletType": "smart_wallet",
  "settlementAddress": "0xSettlement...",
  "wallets": {
    "eoa": {
      "address": "0xEOA...",
      "balances": { "eth": "0.01", "usdc": "100", "adao": "5000" },
      "transactions": { "incoming": 42, "outgoing": 5, "total": 47 }
    },
    "smartWallet": {
      "address": "0xSmart...",
      "balances": { "eth": "0", "usdc": "200", "adao": "12000" },
      "transactions": { "incoming": 18, "outgoing": 2, "total": 20 }
    }
  },
  "balances": {
    "eoa": { "eth": "0.01", "usdc": "100", "adao": "5000" },
    "smartWallet": { "eth": "0", "usdc": "200", "adao": "12000" },
    "settlement": { "eth": "0", "usdc": "0", "adao": "30000" },
    "total": { "eth": "0.01", "usdc": "300", "adao": "47000" }
  },
  "stats": {
    "totalPayments": 55,
    "totalOnChain": 67,
    "totalIncoming": 60,
    "totalOutgoing": 7,
    "totalActivity": 122,
    "totalFees": "12.50",
    "tokenVolumes": {
      "ADAO": { "count": 50, "volume": 45000, "inCount": 48, "outCount": 2 }
    }
  },
  "aggregated": {
    "transactions": { "incoming": 60, "outgoing": 7, "total": 67 },
    "note": "Stats aggregate all workspace wallets..."
  }
}

TypeScript SDK

const stats = await client.getWalletStats();

console.log(stats.stats.totalActivity);
console.log(stats.balances.total.adao);
console.log(stats.wallets.eoa?.transactions.total);
console.log(stats.wallets.smartWallet?.transactions.total);

Response Fields

Field	Type	Description
`stats.totalActivity`	number	Combined payment + on-chain activity (EOA + smart wallet)
`stats.tokenVolumes`	object	Per-token volume, in/out counts
`balances.total`	object	Combined ETH/USDC/ADAO across EOA, smart wallet, and settlement
`wallets.eoa` / `wallets.smartWallet`	object \| null	Per-wallet address, balances, and transaction counts
`aggregated.transactions`	object	Workspace-wide incoming/outgoing totals (persists after wallet switch)

Agent treasury pages: Call this endpoint server-side with the workspace live API key, then expose aggregated fields in your public stats API. Do not call PayDirect from the browser with a live key.

POST

/api/v1/workspaces/:id/internal-transfer

Move ADAO, USDC, or ETH between the workspace EOA and smart wallet (same workspace only).

Auth

Workspace live API key (Bearer pd_live_...) scoped to :id, or admin Bearer ADMIN_API_SECRET.

Request Body

{
  "tokenSymbol": "ADAO",
  "amount": "100",
  "direction": "eoa_to_smart"
}

direction: eoa_to_smart or smart_to_eoa. Use "max" for amount to transfer the full source balance.

cURL Example

curl -X POST https://www.paydirect.com/api/v1/workspaces/WORKSPACE_ID/internal-transfer \
  -H "Authorization: Bearer pd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"tokenSymbol":"ADAO","amount":"max","direction":"eoa_to_smart"}'

Response (201 Created)

{
  "success": true,
  "workspaceId": "uuid",
  "txHash": "0x...",
  "fromAddress": "0xEOA...",
  "toAddress": "0xSmart...",
  "tokenSymbol": "ADAO",
  "amount": "100",
  "direction": "eoa_to_smart",
  "explorerUrl": "https://basescan.org/tx/0x..."
}

Gas: Transfers from EOA to smart wallet for ERC-20 tokens require ETH on the EOA for gas. Smart wallet → EOA token transfers are gasless when the paymaster is configured.

Dashboard UI: Settings → Wallets → Internal Transfer uses the session endpointPOST /api/dashboard/wallets/internal-transfer with the same body.

Error Responses

Common wallet errors

No Workspace Wallet (400)

{
  "error": "No workspace wallet found. Provision a wallet first."
}

This means your workspace doesn't have a wallet yet. Go to the PayDirect dashboard to provision one, or contact support.

Unauthorized (401)

{
  "error": "Invalid API key"
}

Supported Tokens

Tokens held in your workspace wallet on Base

Token	Type	Decimals	Contract (Mainnet)	Use
ETH	Native	18	—	Gas for transactions + payments
USDC	ERC-20	6	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	Stablecoin payments & payouts
ADAO	ERC-20	18	`0x1ef7Be0aBff7d1490e952eC1C7476443A66d6b72`	AgentDAO utility token (0.75% Free / 0.5% Pro / 0.25% Enterprise)

Best Practices

Tips for managing your workspace wallet

Use smart wallets for gasless payouts. Enable a smart wallet to send USDC and ADAO without ETH for gas. Gas is sponsored by the CDP Paymaster.
Check balance before payouts. Call GET /api/v1/wallet/balance to see current balances for both EOA and smart wallets.
Use stats for treasury dashboards. Call GET /api/v1/wallet/stats for cumulative volume, activity counts, and combined balances that persist when you switch default wallet type.
Pass walletType per request. Override the default on any payment or payout by including "walletType": "smart_wallet" in the request body.
Gas is auto-funded for EOA. PayDirect tops up your EOA with ETH. Smart wallets don't need this — gas is sponsored.
Use sandbox for testing. Sandbox keys (pd_test_) point to Base Sepolia with test tokens. Smart wallets work on both environments.
Both addresses are public. View transactions for either wallet on BaseScan.