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)

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 balances for both EOA and smart wallets.
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.