Payout

What it is

A Payout lets an agent send USDC from the user's FluxA Wallet to any external address on Base. Common use cases include withdrawals, revenue splits, paying contractors, and settling off-chain obligations.

Payouts follow an approval flow — the agent initiates the request, the user approves it in the FluxA Wallet UI, and the system signs and broadcasts the on-chain transfer.

What agents can do with it

• Send funds to any address — initiate outbound USDC transfers to any 0x address on Base.
• Track payout status — poll the status endpoint until the payout reaches a terminal state (succeeded or failed).
• Attach metadata — include custom metadata (order IDs, source labels) for reconciliation.
• Webhook notifications — provide a webhook URL to receive push notifications when the payout completes.
• Idempotent retries — use the same payoutId to safely retry without duplicate transfers.

Related APIs

Method	Endpoint	Description
POST	/api/payouts	Create a payout request
GET	/api/payouts/:payoutId	Check payout status

Integration flow

Below is an example prompt you can give an AI agent to send a payout.

** Your task **
Send 2.00 USDC to 0xABCD...1234 as a reward payment for
completing a data labeling task.

** Step 1 — Create the payout **
Call the payout endpoint with the agent JWT:

curl -X POST https://walletapi.fluxapay.xyz/api/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_JWT" \
  -d '{
    "payoutId": "reward-task-42",
    "network": "base",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toAddress": "0xABCD...1234",
    "amount": "2000000",
    "description": "Data labeling reward — task #42",
    "metadata": { "taskId": "42", "type": "reward" },
    "ttlSeconds": 600
  }'

The response returns:
- payoutId
- status (e.g. "pending_authorization")
- approvalUrl (if user approval is needed)

If status is "pending_authorization", ask the user to open the
approvalUrl to approve the payout in their FluxA Wallet.

** Step 2 — Poll for completion **
After the user approves, poll the status endpoint until the
payout reaches a terminal state:

curl https://walletapi.fluxapay.xyz/api/payouts/reward-task-42

Possible statuses:
- pending_authorization — waiting for user approval
- processing — approved, transaction being broadcast
- succeeded — on-chain transfer confirmed (txHash available)
- failed — transfer failed
- expired — user did not approve within TTL

When status is "succeeded", the txHash field contains the
on-chain transaction hash.

** Step 3 — Confirm **
Report the result to the user:
- If succeeded: "Payout of 2.00 USDC sent. Tx: {txHash}"
- If failed/expired: explain the reason and offer to retry