MCP Tools

The FluxA MCP server (@fluxa-pay/fluxa-wallet-mcp) exposes 13 tools. They cover Agent ID, mandates, x402 payments, payouts and payment links. Everything else (refunds, received payments, agent cards, AgentMarket, Agent VC) is available through the FluxA Wallet CLI and the fluxa-agent-wallet skill.

Conventions:

• Amounts are strings in atomic units: "1000000" = 1 USDC.
• Each tool returns a single JSON text block. When the user needs to act, the response includes a URL (authorizationUrl or approvalUrl) and short next-step guidance for the agent. Give the user the full URL to open.
• The server refreshes expired credentials automatically. If a tool says the Agent ID isn't configured, call init_agent_id.

Group	Tools
Agent ID	init_agent_id, get_agent_status
Mandates & x402	create_intent_mandate, get_mandate_status, request_x402_v3_payment, request_x402_payment
Payouts	request_payout, get_payout_status
Payment links	create_payment_link, list_payment_links, get_payment_link, update_payment_link, delete_payment_link

Agent ID

init_agent_id

Registers a FluxA Agent ID for this runtime and saves it locally. Registration is one-time. If an Agent ID is already configured, the tool returns it without registering again.

Parameter	Type	Required	Description
agent_name	string	No*	Readable name, for example "Claude Desktop - John's MacBook"
client_info	string	No*	Runtime description, for example "Claude Desktop v1.0 on macOS 14.1"

* Required unless the AGENT_NAME and CLIENT_INFO environment variables are set, in which case call it with {}.

Returns agent_id on success.

get_agent_status

Shows whether an Agent ID is configured. Takes no parameters.

{ "configured": true, "agent_id": "…", "agent_name": "Claude Code - your-machine", "registered_at": "2026-10-01T12:34:56.000Z" }

Mandates & x402

create_intent_mandate

Creates a spending budget (an intent mandate) for the user to sign. Returns mandateId and authorizationUrl. The first time, opening the URL also approves the agent for the user's wallet.

The tool takes a single intent object:

intent field	Type	Required	Description
naturalLanguage	string	Yes	What the budget is for, for example "Spend up to 1 USDC on market-data API calls over 30 days"
limitAmount	string	Yes	Total budget in atomic units
currency	enum	No	USDC (default), XRP, FLUXA_MONETIZE_CREDITS
validForSeconds	integer	No	Validity window. Default 28800 (8 hours)
category	string	No	Free-form category. Default general
hostAllowlist	string[]	No	Limit spending to these hosts. Leave it out to allow any host

get_mandate_status

Parameter	Type	Required	Description
mandate_id	string	Yes	The mandateId from create_intent_mandate

The mandate is usable once its status is signed. Until then it's awaiting the user's approval: give the user the authorizationUrl again.

request_x402_v3_payment

Recommended x402 tool. Signs a payment against a signed mandate and returns xPaymentB64. Send it as the X-PAYMENT header when you retry the original request. The mandate needs enough remaining budget and must still be within its validity window.

Parameter	Type	Required	Description
mandate_id	string	Yes	A signed mandate
payment_required	object	Yes	The HTTP 402 body: { x402Version, accepts: [...], error? } (see below)
intent	object	Yes	Why you're paying: why, http_method, http_url, caller (all required), plus optional trace_id, prompt_summary
selection	object	No	Pick an accepts entry: acceptIndex, scheme, network, asset
options	object	No	validity_window_seconds (default 60, capped at the entry's maxTimeoutSeconds), preferred_network, preferred_asset

Each accepts entry needs scheme, network, maxAmountRequired, resource, description, mimeType, payTo, maxTimeoutSeconds and asset, plus optional extra (name, version) and outputSchema. Only the exact scheme is supported. The tool picks the first exact entry whose currency matches the mandate's currency.

x402 payload versions

The MCP tools take the x402 v1 accepts shape shown above. For x402 v2 payloads, use the CLI's x402 command, which detects the version automatically.

request_x402_payment

Legacy x402 flow without a mandate: each payment may need the user's approval. It takes the same payment_required, intent, selection and options parameters as request_x402_v3_payment (without mandate_id). options also accepts approval_id, for retrying after the user approves. If approval is needed, the response includes an approvalUrl for the user. Prefer request_x402_v3_payment with a mandate.

Payouts

request_payout

Sends USDC on Base to an external address. The user approves each payout at the returned approvalUrl.

Parameter	Type	Required	Description
to_address	string	Yes	Recipient 0x… address on Base
amount	string	Yes	Atomic units, greater than 0
payout_id	string	Yes	Your unique ID for this payout. Reusing it retries safely without paying twice

The MCP tool always requires the user's approval for each payout. To pay out within a signed budget, use the CLI's payout --mandate.

get_payout_status

Parameter	Type	Required	Description
payout_id	string	Yes	The ID you passed to request_payout

Poll until the payout reaches a final outcome, reading displayStatus:

displayStatus	What to do
awaiting_approval	Remind the user of the approvalUrl
processing	Keep polling
completed	Done. txHash is the on-chain transaction
failed, expired, rejected, canceled	Not sent. Tell the user

Treat any other value as processing.

Payment links

create_payment_link

Parameter	Type	Required	Description
amount	string	Yes	Price in atomic units
currency	string	No	Default USDC
network	string	No	Default base
description	string	No	Shown on the payment page
resource_content	string	No	Content revealed to the payer after they pay
expires_at	string	No	ISO 8601 expiry
max_uses	integer	No	Maximum number of payments

Returns the link, including its linkId and shareable url.

list_payment_links

Parameter	Type	Required	Description
limit	integer	No	Maximum number of links to return

get_payment_link

Parameter	Type	Required	Description
link_id	string	Yes	The link's linkId
include_payments	boolean	No	Also return the payments made through this link
payments_limit	integer	No	Maximum number of payments to include

update_payment_link

Parameter	Type	Required	Description
link_id	string	Yes	The link's linkId
description	string	No	New description
resource_content	string	No	New delivered content
status	enum	No	active or disabled
expires_at	string | null	No	New expiry. null removes it
max_uses	integer | null	No	New usage cap. null removes it

delete_payment_link

Parameter	Type	Required	Description
link_id	string	Yes	The link's linkId

Not available over MCP

Use the CLI or the skill for:

• refunds and received-payment records (CLI › Receiving)
• payouts within a signed mandate (CLI › Payouts)
• wallet linking check, balances, mandate list and recent transactions (CLI › Account)
• Agent VC for third-party sign-in
• agent cards and linked-card checkout
• AgentMarket: search, tool planning, Units, Token Plans and API keys