API Documentation

Smart Wallets

Enable ERC-4337 smart wallets for gasless transactions. Smart wallets use account abstraction with CDP Paymaster so your workspace can send USDC, ETH, and ADAO without needing ETH for gas.

How Smart Wallets Work

Account abstraction with gas sponsorship

┌─────────────────────────────────────────────────────────┐
│  Your Workspace                                         │
│                                                         │
│  EOA Wallet (0xAbc...)        ← always present          │
│    └── Standard transactions (requires ETH for gas)     │
│                                                         │
│  Smart Wallet (0xDef...)      ← opt-in, gasless         │
│    └── UserOperations via ERC-4337 Bundler              │
│        └── Gas paid by CDP Paymaster (not you)          │
│                                                         │
│  default_wallet_type: "workspace" | "smart_wallet"      │
│    └── Used when walletType is not passed in request    │
└─────────────────────────────────────────────────────────┘

Flow (dashboard / session auth):
  1. Enable smart wallet  → POST /api/workspaces/smart-wallet
  2. Set as default       → PATCH /api/workspaces/smart-wallet

Flow (programmatic / API key auth):
  1. Enable smart wallet  → POST /api/v1/workspaces/:id/smart-wallet
  2. Set as default       → PATCH /api/v1/workspaces/:id/smart-wallet
  3. Get wallet details   → GET  /api/v1/workspaces/:id/smart-wallet

Common:
  3. Send gasless payout  → POST /api/v1/payouts { walletType: "smart_wallet" }
  4. Check balances       → GET /api/v1/wallet/balance (returns both wallets)

Gasless

Gas fees are sponsored by the CDP Paymaster. Send USDC, ADAO, and ETH without holding ETH for gas.

Agent-Friendly

AI agents can transact autonomously without gas management complexity. No ETH balance monitoring needed.

Backward Compatible

Your existing EOA wallet keeps working. Smart wallet is additive — opt in per request or set a default.

POST

/api/workspaces/smart-wallet

Enable a smart wallet for your workspace

Idempotent: If a smart wallet already exists, the existing wallet is returned instead of creating a duplicate. Safe to call multiple times.

Headers

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

cURL Example

curl -X POST https://www.paydirect.com/api/workspaces/smart-wallet \
  -H "Authorization: Bearer pd_live_abc123..."

Response (200 OK)

{
  "smartWallet": {
    "address": "0xSmartWalletAddress...",
    "type": "smart_wallet",
    "ownerAddress": "0xEOAWalletAddress..."
  },
  "message": "Smart wallet created successfully"
}

Response Fields

Field	Type	Description
`smartWallet.address`	string	The on-chain smart wallet address
`smartWallet.type`	string	Always `"smart_wallet"`
`smartWallet.ownerAddress`	string	The EOA wallet that owns and controls this smart wallet

PATCH

/api/workspaces/smart-wallet

Set the default wallet type for the workspace

Request Body

Field	Type	Required	Description
`defaultWalletType`	string	Yes	`"workspace"` (EOA) or `"smart_wallet"`

cURL Example

curl -X PATCH https://www.paydirect.com/api/workspaces/smart-wallet \
  -H "Authorization: Bearer pd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "defaultWalletType": "smart_wallet" }'

Response (200 OK)

{
  "defaultWalletType": "smart_wallet",
  "message": "Default wallet type updated"
}

How defaults work: When you create a payment or payout without specifying walletType, PayDirect uses your workspace's defaultWalletType. You can always override per-request by passing walletType in the request body.

POST

/api/v1/workspaces/:id/smart-wallet

API Key

Programmatically create a smart wallet for any workspace

For platform integrations: Use this endpoint when creating smart wallets programmatically (e.g., on user sign-up). Authenticates via API key or admin secret — no browser session needed. Idempotent: safe to call multiple times.

Authentication

Method	Description
`Bearer pd_live_...`	Workspace API key (must belong to the workspace in the URL)
`Bearer ADMIN_SECRET`	Admin secret — can create smart wallets for any workspace

Request Body (optional)

Field	Type	Required	Description
`setDefault`	boolean	No	If `true`, automatically set `smart_wallet` as the workspace default after creation

cURL Example

# Using workspace API key
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 }'

# Using admin secret (for platform integrations)
curl -X POST https://www.paydirect.com/api/v1/workspaces/ws_abc123/smart-wallet \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "setDefault": true }'

Response (201 Created)

{
  "success": true,
  "workspaceId": "ws_abc123",
  "smartWallet": {
    "address": "0xSmartWalletAddress...",
    "ownerAddress": "0xEOAWalletAddress...",
    "walletId": "sw_..."
  },
  "defaultWalletType": "smart_wallet"
}

GET

/api/v1/workspaces/:id/smart-wallet

API Key

Get wallet details for a workspace (EOA + smart wallet status)

cURL Example

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

Response (200 OK)

{
  "workspaceId": "ws_abc123",
  "eoa": {
    "address": "0xEOAWalletAddress...",
    "createdAt": "2026-01-15T10:00:00Z"
  },
  "smartWallet": {
    "address": "0xSmartWalletAddress...",
    "walletId": "sw_...",
    "createdAt": "2026-01-15T10:01:00Z"
  },
  "defaultWalletType": "smart_wallet"
}

Response (no smart wallet yet)

{
  "workspaceId": "ws_abc123",
  "eoa": {
    "address": "0xEOAWalletAddress...",
    "createdAt": "2026-01-15T10:00:00Z"
  },
  "smartWallet": null,
  "defaultWalletType": "workspace"
}

PATCH

/api/v1/workspaces/:id/smart-wallet

API Key

Set the default wallet type for a workspace programmatically

Request Body

Field	Type	Required	Description
`defaultWalletType`	string	Yes	`"workspace"` (EOA) or `"smart_wallet"`

cURL Example

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

Response (200 OK)

{
  "success": true,
  "workspaceId": "ws_abc123",
  "defaultWalletType": "smart_wallet"
}

Using walletType in Requests

Choose which wallet to use per API call

All payment and payout endpoints accept an optional walletType field. When set to "smart_wallet", the transaction uses the smart wallet with gasless execution via CDP Paymaster.

Gasless Payout Example

curl -X POST https://www.paydirect.com/api/v1/payouts \
  -H "Authorization: Bearer pd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokenSymbol": "USDC",
    "amount": "100.00",
    "destinationAddress": "0xRecipient...",
    "walletType": "smart_wallet"
  }'

Gasless Payment Example

curl -X POST https://www.paydirect.com/api/v1/payments \
  -H "Authorization: Bearer pd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokenSymbol": "USDC",
    "amount": "25.00",
    "merchantWallet": "0xMerchant...",
    "walletType": "smart_wallet"
  }'

walletType	Wallet Used	Gas	Notes
`"eoa"`	EOA Wallet	Paid by workspace ETH	Standard transaction, auto gas funding applies
`"smart_wallet"`	Smart Wallet	Sponsored (free)	UserOperation via Bundler, gas paid by CDP Paymaster
omitted	Workspace default	Depends on default	Uses `defaultWalletType` from workspace settings

How Gasless Transactions Work

ERC-4337 account abstraction with CDP Paymaster

Smart Wallet (ERC-4337)
  │
  1. PayDirect builds a UserOperation (transfer USDC/ADAO/ETH)
  │
  2. UserOperation sent to CDP Bundler with paymasterUrl
  │   └── CDP Paymaster evaluates and sponsors gas
  │
  3. Bundler submits the operation on-chain
  │   └── Gas fee paid by Paymaster, NOT by your wallet
  │
  4. Token transfer executes
  │   └── Recipient receives tokens
  │
  Result: Your wallet sends tokens without holding any ETH for gas

Supported tokens: Gasless transfers work for all tokens supported by PayDirect — USDC, ETH, and ADAO. The CDP Paymaster sponsors gas for any ERC-20 transfer and native ETH value transfers from the smart wallet.

Endpoints Summary

All smart wallet related endpoints

Programmatic (API key / admin secret)

POST

/api/v1/workspaces/:id/smart-walletCreate smart wallet

GET

/api/v1/workspaces/:id/smart-walletGet wallet details

PATCH

/api/v1/workspaces/:id/smart-walletSet default wallet type

Dashboard (session auth)

POST

/api/workspaces/smart-walletEnable smart wallet

PATCH

/api/workspaces/smart-walletSet default wallet type

Related endpoints

GET

/api/v1/wallet/balanceGet both wallet balances

POST

/api/v1/payoutsSend payout (accepts walletType)

POST

/api/v1/paymentsCreate payment (accepts walletType)

Best Practices

Tips for using smart wallets

Use smart wallets for agent workflows. Agents don't need to manage ETH for gas — they just send tokens.
Set smart_wallet as default for fully gasless operation. Once enabled, set the default so all API calls automatically use the smart wallet.
Fund your smart wallet with tokens. Smart wallets still need token balance to send. Transfer USDC/ADAO to the smart wallet address.
Both wallets can receive payments. Incoming transfers to either the EOA or smart wallet address are synced and visible in your dashboard.
Override per request. Even if your default is EOA, pass walletType: "smart_wallet" on individual payouts to use the gasless path.

Wallet API Payouts API Payments API