Agent cards

fluxa-wallet card … issues and manages prepaid AgentCard virtual cards. A card is funded in USD from the linked wallet, can be recharged, and its remaining balance can be withdrawn back to the wallet.

Availability

Most products need an account profile, and some need identity verification; card types shows what each product requires. The Super AI Developer Card also needs separate approval, which the user applies for on the Agent Cards page of the FluxA Wallet. If something is missing, card commands fail with an error that says what to do next. See Errors.

All card commands print bare JSON on success (no success/data envelope) and the usual error envelope on failure. Card amounts are USD decimals with at most 2 decimal places (25.00), not atomic units.

Typical flow

# 1. Profile: check first, create only if none exists
fluxa-wallet card holder me
fluxa-wallet card holder create --profile @profile.json

# 2. Pick a product
fluxa-wallet card types

# 3. A spending mandate the user approves (USDC, atomic units)
fluxa-wallet mandate-create --desc "Issue a $25 prepaid card" --amount 30000000

# 4. Issue the card once the mandate is signed
fluxa-wallet card create --card-type-id <cardTypeId> --amount 25.00 --mandate mand_xxx

# 5. Use it
fluxa-wallet card details --id card_xxx

Size the mandate to cover the card amount plus the fee shown by card types. See Mandates & x402 payments for mandate-create and approval.

Account profile

card holder me

Shows the account profile and its verification state, including the verification link the user should open when identity verification is required. Run this before holder create.

card holder create

Creates the account profile and starts identity verification. Use the real details of the wallet owner. Never invent or guess them.

fluxa-wallet card holder create --profile @profile.json
# or with individual flags
fluxa-wallet card holder create --first-name Ada --last-name Lovelace --email ada@example.com \
  --phone +14155550100 --country US --city "San Francisco" \
  --address-line1 "1 Market St" --postal-code 94105

Flag	Required	Description
--profile	—	Whole profile as JSON or @file.json (instead of the flags below)
--first-name, --last-name	Yes	Legal name
--email	Yes	Email
--phone	Yes	E.164 format, e.g. +14155550100
--country	Yes	2-letter country code. There is no default
--city, --address-line1, --postal-code	Yes	Address
--region, --address-line2	No	Address

After creating the profile, send the user the verification link from card holder me and wait until verification is approved.

card holder update

fluxa-wallet card holder update --profile @patch.json [--revision 3]

Partially updates the profile. Pass --revision (from holder me) to avoid overwriting a concurrent change. A conflict tells you to re-read the profile and retry.

Products

card types

Lists the card products available to the account: product ID, fees, limits and availability. Choose one and pass its ID as --card-type-id. Don't assume a default product or treat a missing fee as zero. A product appearing in the list does not mean the account has been granted access to it.

Issue a card

card create

fluxa-wallet card create --card-type-id <cardTypeId> --amount 25.00 --mandate mand_xxx

Flag	Required	Default	Description
--card-type-id	Yes*	—	Product ID from card types (*or --bin-id / --bin; exactly one)
--amount	Yes (new requests)	—	Initial balance in USD
--mandate	Yes	—	Signed mandate that pays for the card
--request-id	No	—	Continue an earlier request instead of starting a new one. Omit --amount and the product flag
--wait	No	30	Seconds to keep checking for the result, 0–300

When the card is ready within --wait, the command prints the card. Otherwise it prints the request with its current status and a continueCommand:

{
  "pendingRequestId": "creq_xxx",
  "status": "issuing",
  "amountUsd": "25.00",
  "continueCommand": "fluxa-wallet card create --request-id creq_xxx --mandate <mandate_id>"
}

Run the continueCommand (with the same mandate) to keep checking. Don't start a new card create to retry: that would be a second card. How to read status:

status	Meaning
completed	The card is issued. card list shows it
action_required	Something needs the user, for example profile verification. The response says what
failed, expired	The request did not complete. Any payment taken is returned. Start a new request if the user still wants a card
anything else	Still processing. Re-run the continueCommand

Use a card

Command	Description
card list [--global]	Cards created by this agent. --global lists every card on the linked account. Pending requests are not listed
card details --id <card_id>	Full card details (number, expiry, CVV). Treat as secret: don't log or store them, and fetch them only when needed
card balance --id <card_id>	Refreshes and shows the live balance
card transactions --id <card_id>	History. Optional --type purchase|refund|verification|reversal|fee|deposit|withdrawal, --page, --limit (max 50), --start-time/--end-time (Unix ms)
card 3ds latest --id <card_id>	Newest 3-D Secure challenge from the last 24 hours (code or verification link)
card 3ds latest_1h --id <card_id>	All 3-D Secure challenges from the last hour

When a merchant asks for 3-D Secure verification during checkout, run card 3ds latest and use the code or link it returns.

Recharge

fluxa-wallet card recharge --id card_xxx --amount 10.00 --mandate mand_xxx

Same flags and the same status / continueCommand handling as card create (--id replaces the product flag). Only one recharge can run per card at a time. The fee and the card's balance limit are shown by card types.

Withdraw to the wallet

fluxa-wallet card withdraw --id card_xxx               # full available balance
fluxa-wallet card withdraw --id card_xxx --amount 5.00
fluxa-wallet card withdrawals --id card_xxx
fluxa-wallet card withdrawal --id card_xxx --withdrawal-id cwd_xxx

Moves card balance back to the linked wallet as USDC, less the withdrawal fee. Only one withdrawal can run per card at a time.

{
  "withdrawalId": "cwd_xxx",
  "status": "processing",
  "amountUsd": "5.00",
  "feeUsd": "0.00",
  "payoutTxHash": null,
  "progressMessage": null
}

status is processing, completed or failed. While processing, show the user progressMessage if present and don't submit another withdrawal: the request resumes on its own. failureReason is only set when the status is failed.

Errors

The error envelope carries a code and, for most card errors, a hint on what to do next.

code	What to do
agent_not_linked	Run fluxa-wallet link-wallet and have the user finish linking
vip_whitelist_required	The product needs Super card approval. Send the user the application link in the error (details.applicationUrl), or to the Agent Cards page in the wallet. Retry after approval
card_access_unavailable	Eligibility couldn't be checked. This is not a rejection; retry later
cardholder_required	Run card holder me. Create a profile only if none exists
cardholder_not_approved	Verification isn't finished. Check card holder me and retry once approved
card_type_not_found, card_type_unavailable, card_type_ambiguous	Run card types and pass one available product with --card-type-id
recharge_in_progress, withdrawal_in_progress	Wait for the current one to finish
revision_conflict	Re-read card holder me and retry with the current --revision
Mandate errors	The mandate isn't signed, has expired, or doesn't cover the amount plus fee. Check it with mandate-status