Payouts - Consul

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:

Status	Description
`processing`	Transfer initiated on-chain
`completed`	USDC delivered to recipient’s wallet
`pending_claim`	Recipient isn’t on the platform yet - funds are held securely until they claim
`cancelled`	Payout was cancelled; funds returned to your balance
`expired`	Payout expired; funds returned to your balance
`failed`	Transfer failed; a failure reason is provided

Payout Item Lifecycle Diagram

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.

​How Payouts Work

​Sending a Payout

​Idempotency

​Payout Lifecycle

​Cancelling a Payout

​Tracking Payouts

How Payouts Work

Sending a Payout

Idempotency

Payout Lifecycle

Cancelling a Payout

Tracking Payouts