Skip to main content
Once your Consul balance is funded, you can send payouts to one or more recipients in a single API call. Payouts are on-chain USDC transfers on Base that settle in seconds.

​
How Payouts Work

Each payout is a batch of items. Each item specifies an amount and a target - either an email address or a recipient ID. Consul handles the rest:
  • Existing users receive USDC directly in their Consul wallet.
  • New users receive an email invite to claim their funds. Consul creates a wallet behind the scenes and guides them through onboarding.
Payouts are atomic. If any item in a batch fails validation (e.g. insufficient balance for the total), the entire payout is rejected. No partial transfers occur.

​
Sending a Payout

Use the Create a Payout endpoint. You can target recipients by email or by recipient_id if they’ve already been created via the Recipients API: 
curl -X POST https://api.onconsul.com/v1/payouts \
  -H "Authorization: Basic base64($CONSUL_API_KEY)" \
  -H "Idempotency-Key: $UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"amount": "500", "email": "alice@example.com"},
      {"amount": "250", "recipient_id": "recipient_abc123"},
      {"amount": "1000", "email": "new-contractor@example.com"}
    ]
  }'
The response returns a payout in processing status. Individual items settle almost instantly (< 3s p99). Listen for the transfer.updated webhook to confirm each item has completed.

​
Idempotency

Include an Idempotency-Key header to safely retry payout requests without creating duplicates. If a request with the same key has already been processed, Consul returns the original response.

​
Payout Lifecycle

Each payout item follows its own lifecycle:
StatusDescription
processingTransfer initiated on-chain
completedUSDC delivered to recipient’s wallet
pending_claimRecipient isn’t on the platform yet - funds are held securely until they claim
cancelledPayout was cancelled; funds returned to your balance
expiredPayout expired; funds returned to your balance
failedTransfer failed; a failure reason is provided

​
Cancelling a Payout

You can cancel a payout that hasn’t settled yet by calling POST /payouts//cancel. This is only possible while the payout is still in processing or pending_claim status. Once a payout item has completed, it cannot be reversed. 
curl -X POST https://api.onconsul.com/v1/payouts/payout_abc123/cancel \
  -u $CONSUL_API_KEY
The response returns the updated payout object with a cancelled status. Funds are returned to your Consul balance.

​
Tracking Payouts

  • Get a Payout: GET /payouts/ returns the overall status, total amount, and item count.
  • List Payout Items: GET /payouts//items returns each item’s recipient, amount, and status.