API Documentation

Payouts API

Send crypto from your workspace wallet to any address on Base. Supports USDC, ETH, and ADAO. Payouts are synchronous — the transaction hash is returned immediately in the response.

How Payouts Work

Send funds directly from your workspace wallet

Your Workspace Wallet          PayDirect              Recipient
        │                           │                      │
   1.   │── POST /api/v1/payouts ──▶│                      │
        │   tokenSymbol: "USDC"     │                      │
        │   amount: "50.00"         │                      │
        │   destinationAddress      │                      │
        │                           │                      │
   2.   │                           │── Check balance      │
        │                           │── Send on-chain ────▶│
        │                           │                      │
   3.   │◀── { txHash, status:      │                      │
        │      "completed" }        │                      │
        │                           │                      │
   4.   │                           │── Webhook ──▶ payout.completed
        │                           │   (secondary confirmation)

Synchronous

Transaction hash returned immediately. No polling needed.

No Fees

No PayDirect fee on payouts. Only on-chain gas costs apply.

Idempotent

Use idempotencyKey to prevent duplicate payouts on retry.

POST

/api/v1/payouts

Send a payout from your workspace wallet

Request Body

Field	Type	Required	Description
`tokenSymbol`	string	Yes	`"USDC"`, `"ETH"`, or `"ADAO"`
`amount`	string	Yes	Positive amount (e.g. `"50.00"`)
`destinationAddress`	string	Yes	Recipient Base address (`0x...`, 42 chars)
`description`	string	No	Human-readable description (e.g. "Affiliate commission Q1")
`metadata`	object	No	Arbitrary key-value metadata
`idempotencyKey`	string	No	Unique key to prevent duplicate payouts on retry

Headers

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

cURL Example

curl -X POST https://paydirect.com/api/v1/payouts \
  -H "Authorization: Bearer pd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokenSymbol": "USDC",
    "amount": "50.00",
    "destinationAddress": "0xRecipientAddress...",
    "description": "Affiliate commission payout",
    "metadata": { "partnerId": "partner_123", "period": "2026-Q1" },
    "idempotencyKey": "payout-partner_123-2026Q1"
  }'

TypeScript SDK

const { payout, timestamp } = await client.createPayout({
  tokenSymbol: "USDC",
  amount: "50.00",
  destinationAddress: "0xRecipientAddress...",
  description: "Affiliate commission payout",
  metadata: { partnerId: "partner_123" },
  idempotencyKey: "payout-partner_123-2026Q1",
});

console.log(`Sent! TX: ${payout.txHash}`);
// payout.status is always "completed" on success

Response (200 OK)

{
  "payout": {
    "txHash": "0x1a2b3c4d5e6f...",
    "amount": "50.00",
    "tokenSymbol": "USDC",
    "destinationAddress": "0xRecipientAddress...",
    "fromAddress": "0xYourWorkspaceWallet...",
    "environment": "live",
    "status": "completed",
    "description": "Affiliate commission payout",
    "metadata": { "partnerId": "partner_123", "period": "2026-Q1" }
  },
  "timestamp": "2026-02-16T14:36:22.000Z"
}

Synchronous execution: Unlike payments (which go through a lifecycle), payouts execute immediately. The txHash and status: "completed" are in the response. No need to poll or wait for a webhook.

Balance check: PayDirect checks your workspace wallet balance before sending. If insufficient, you'll get a 400 with available and requested amounts.

Error Responses

Common payout errors

Insufficient Balance (400)

{
  "error": "Insufficient balance",
  "available": "12.50",
  "requested": "50.00",
  "tokenSymbol": "USDC"
}

Missing Fields (400)

{
  "error": "Missing required fields: tokenSymbol, amount, destinationAddress"
}

Invalid Address (400)

{
  "error": "Invalid destinationAddress format"
}

No Workspace Wallet (400)

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

Payout Failed (500)

{
  "error": "Payout failed"
}

On failure, a payout.failed webhook event is also fired with the error details.

Idempotency

Prevent duplicate payouts on retry

Include an idempotencyKey in the request body to ensure the same payout is not sent twice. If a payout with the same key was already sent, PayDirect returns the original result instead of sending again.

Duplicate Response (200 OK)

{
  "payout": {
    "txHash": "0x1a2b3c4d5e6f...",
    "status": "completed",
    "note": "Duplicate request -- returning previous result"
  }
}

Recommended key patterns:

payout-partner_123-2026Q1 — partner commission
affiliate-aff_456-jan2026 — affiliate payout
adao-cashout-user_789-1708100000 — user ADAO cashout

GET

/api/v1/payouts

List payout history for the workspace

Query Parameters

Parameter	Type	Description
`limit`	number	Max results (1-100, default: 50)
`offset`	number	Pagination offset (default: 0)

cURL Example

curl "https://paydirect.com/api/v1/payouts?limit=20&offset=0" \
  -H "Authorization: Bearer pd_live_abc123..."

Response (200 OK)

{
  "payouts": [
    {
      "txHash": "0x1a2b3c4d5e6f...",
      "type": "ERC20",
      "details": {
        "amount": "50.00",
        "tokenSymbol": "USDC",
        "destinationAddress": "0xRecipient...",
        "description": "Affiliate commission payout"
      },
      "createdAt": "2026-02-16T14:36:22.000Z"
    },
    {
      "txHash": "0x7a8b9c0d1e2f...",
      "type": "ETH",
      "details": {
        "amount": "0.05",
        "tokenSymbol": "ETH",
        "destinationAddress": "0xOtherRecipient..."
      },
      "createdAt": "2026-02-15T10:20:00.000Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Payout Webhook Events

Events fired during the payout lifecycle

Event	Description
payout.completed	Payout transaction confirmed on Base. Includes txHash, amount, tokenSymbol, destinationAddress, fromAddress.
payout.failed	Payout failed due to insufficient balance, chain error, or other issue. Includes error message.

Webhook Payload Example

{
  "id": "delivery-uuid-...",
  "event": "payout.completed",
  "data": {
    "txHash": "0x1a2b3c4d5e6f...",
    "amount": "50.00",
    "tokenSymbol": "USDC",
    "destinationAddress": "0xRecipientAddress...",
    "fromAddress": "0xYourWorkspaceWallet...",
    "environment": "live",
    "status": "completed",
    "description": "Affiliate commission payout",
    "metadata": { "partnerId": "partner_123" }
  },
  "timestamp": "2026-02-16T14:36:22.000Z"
}

Note: Since payouts are synchronous, the webhook is a secondary confirmation. You already have the txHash from the POST response. Webhooks are useful for asynchronous processing, audit logging, or systems that can't wait for the synchronous response.

Common Use Cases

When to use the Payouts API

Use Case	Token	Example
Affiliate commissions	USDC	Pay affiliates their earned commission each month
Partner revenue share	USDC	Pay partners their percentage of revenue
Referral rewards	ADAO	Send ADAO rewards to users who refer new signups
Token cashout	USDC	Convert internal token balances to USDC payouts
Agent-to-agent payments	USDC / ADAO	Autonomous agents paying other agents for services
Contractor payments	USDC / ETH	Pay freelancers and contractors in crypto