Withdraw from a card

Move unused card balance back to the FluxA Wallet linked to your agent. Withdrawals do not need a mandate: the money always goes back to the linked wallet, and the request body cannot change the destination.

A withdrawal is processed in the background. Externally it has only three states: processing, completed, failed.

CLI

fluxa-wallet card withdraw --id card_7Hq2LmX9pRt4               # full remaining balance
fluxa-wallet card withdraw --id card_7Hq2LmX9pRt4 --amount 5.00
fluxa-wallet card withdrawals --id card_7Hq2LmX9pRt4
fluxa-wallet card withdrawal --id card_7Hq2LmX9pRt4 --withdrawal-id wdr_…

---

Request a withdrawal

POST/api/v2/cards/{cardId}/withdrawBearer agent-vc

curl -X POST https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/withdraw \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_VC" \
  -d '{ "amountUsd": "5.00" }'

Field	Type	Required	Description
amountUsd	string	no	Amount to take off the card, in USD. Omit to withdraw the full live balance. Must not exceed the balance and must be larger than the withdrawal fee.

The withdrawal fee (feeUsd) is deducted from amountUsd; the wallet receives amountUsd − feeUsd.

Response 202:

{
  "withdrawalId": "wdr_5e2a9c1f-7b3d-4e6a-8f0c-2d4b6a8e1c37",
  "status": "processing",
  "amountUsd": "5.00",
  "feeUsd": "0.50",
  "payoutTarget": "…"
}

Keep withdrawalId and poll Get a withdrawal. Only one withdrawal can be in progress per card; do not submit another while one is processing.

---

List withdrawals

GET/api/v2/cards/{cardId}/withdrawalsBearer agent-vc

curl https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/withdrawals \
  -H "Authorization: Bearer $AGENT_VC"

Returns { "withdrawals": [ … ] }, newest first, each in the shape below.

---

Get a withdrawal

GET/api/v2/cards/{cardId}/withdrawals/{withdrawalId}Bearer agent-vc

curl https://agentcard.fluxapay.xyz/api/v2/cards/card_7Hq2LmX9pRt4/withdrawals/wdr_5e2a9c1f-7b3d-4e6a-8f0c-2d4b6a8e1c37 \
  -H "Authorization: Bearer $AGENT_VC"

{
  "withdrawal": {
    "withdrawalId": "wdr_5e2a9c1f-7b3d-4e6a-8f0c-2d4b6a8e1c37",
    "status": "completed",
    "cardDebited": true,
    "cardRestored": false,
    "amountUsd": "5.00",
    "feeUsd": "0.50",
    "payoutTarget": "…",
    "payoutTxHash": "0x…",
    "failureReason": null,
    "progressMessage": null,
    "createdAt": "2026-10-27T12:00:00.000Z",
    "updatedAt": "2026-10-27T12:01:30.000Z"
  }
}

Field	Description
status	processing, completed or failed.
cardDebited	true once the amount has been taken off the card.
cardRestored	true if the amount was put back on the card because the transfer to the wallet could not be made.
amountUsd, feeUsd	Amount taken off the card and the fee.
payoutTarget	Identifies the destination (your linked wallet). Treat as opaque.
payoutTxHash	On-chain transaction hash of the transfer to the wallet, once sent.
failureReason	Only when status is failed: a short explanation. Otherwise null.
progressMessage	Optional human-readable note while processing (for example, that the request will resume automatically). Show it to the user as-is.

Statuses

status	Meaning	What to do
processing	In progress. This can take a while.	Keep polling. Do not submit another withdrawal.
completed	The funds were sent to the wallet.	Done.
failed	The withdrawal did not complete.	Check cardRestored and the card balance. If the problem persists, contact FluxA support with the withdrawalId.

Withdrawals also appear in transactions with type: "withdrawal".

---

Errors

Status	code	What to do
400	invalid_amount	The amount is invalid or does not cover the fee.
400	insufficient_card_balance	The amount is more than the card balance.
400	withdraw_not_supported	Withdrawals are not available for this card.
404	card_not_found, withdrawal_not_found	Check the IDs.
409	withdrawal_in_progress	Wait for the current withdrawal to finish.
429	daily_withdraw_limit_reached	Withdrawals are temporarily limited. Try again tomorrow.
5xx	—	The live balance could not be read; nothing was withdrawn. Retry later.