Setup

Three steps take an agent from a fresh install to ready-to-pay:

fluxa-wallet status          → is an Agent ID configured?
fluxa-wallet init ...        → register one (once)
fluxa-wallet check-wallet    → is it linked to the user's wallet?
fluxa-wallet link-wallet     → if not, get the URL for the user to approve

status

Checks the local configuration. If the agent is registered and its JWT is valid, it also checks whether the agent is linked to a wallet.

fluxa-wallet status

No options.

Configured:

{
  "success": true,
  "data": {
    "configured": true,
    "agent_id": "ag_xxxxxxxxxxxx",
    "has_token": true,
    "has_jwt": true,
    "jwt_expired": false,
    "agent_name": "My Agent",
    "wallet_linked": true
  }
}

Field	Meaning
configured	An Agent ID, token and JWT are all present
jwt_expired	The JWT has expired or expires within 5 minutes. Other commands refresh it automatically
wallet_linked	true / false, or null if it could not be checked right now. Absent when the JWT has expired

Not configured:

{ "success": true, "data": { "configured": false, "has_registration_info": false } }

has_registration_info is true when AGENT_NAME and CLIENT_INFO are both set, so init can run without flags.

init

Registers a new Agent ID and saves its credentials locally. Run it once per agent.

fluxa-wallet init --name "Research Agent" --client "Claude Code on macOS"

Flag	Type	Required	Description
--name	string	Yes, unless AGENT_NAME is set	Agent name. Users see this when they approve the agent
--client	string	Yes, unless CLIENT_INFO is set	Where the agent runs, e.g. client name and version

{
  "success": true,
  "data": { "message": "Agent registered successfully", "agent_id": "ag_xxxxxxxxxxxx" }
}

If an Agent ID is already configured, init changes nothing and returns "message": "Agent ID already configured" with the existing agent_id. Running it again is safe.

Error	What to do
Missing required parameters: --name, --client (or set AGENT_NAME, CLIENT_INFO)	Pass both flags, or set both environment variables
Agent registration failed (...)	Retry shortly. If it keeps failing, upgrade the CLI

check-wallet

Checks whether the agent is linked to a user's FluxA Wallet. Most commands need a linked wallet.

fluxa-wallet check-wallet

{ "success": true, "data": { "linked": true } }

{
  "success": true,
  "data": {
    "linked": false,
    "linkUrl": "https://agentwallet.fluxapay.xyz/add-agent?agentId=...&name=..."
  }
}

link-wallet

Same check. If the agent isn't linked, it returns the URL the user opens to approve it.

fluxa-wallet link-wallet

{
  "success": true,
  "data": {
    "linked": false,
    "linkUrl": "https://agentwallet.fluxapay.xyz/add-agent?agentId=...&name=...",
    "message": "Please ask user to open this URL to authorize wallet access."
  }
}

Give the user the complete linkUrl as a clickable link. When they have approved it, run check-wallet again. If already linked, the result is "linked": true with "message": "Agent is already linked to user's wallet."

refreshJWT

The CLI refreshes the agent's JWT automatically before any call when it has expired or expires within 5 minutes. Use refreshJWT only when you need a fresh token outside the CLI, or to see why a refresh is failing.

fluxa-wallet refreshJWT

{
  "success": true,
  "data": {
    "message": "JWT refreshed successfully",
    "agent_id": "ag_xxxxxxxxxxxx",
    "jwt": "eyJhbGciOi..."
  }
}

WARNING

The output contains a live credential. Don't log it, paste it into chats, or commit it.

Error	What to do
FluxA Agent ID not initialized. Run "init" first.	Run init
JWT refresh failed (...)	Retry shortly. If the stored token was revoked or lost, register again with a fresh data directory (see below)

Where credentials are stored

By default the CLI keeps its state in ~/.fluxa-ai-wallet-mcp/:

File	Contents
config.json	Agent ID, agent token, current JWT, agent name and client info
audit.log	A local log of the commands the CLI ran

Set FLUXA_DATA_DIR to use another directory, for example one per agent:

export FLUXA_DATA_DIR="$HOME/.fluxa-agents/research-bot"
fluxa-wallet init --name "Research Bot" --client "cron on server-1"

Treat config.json as a secret. Anyone with it can act as the agent within what the user has authorised.

Environment variables

Variable	Description
AGENT_ID	Pre-configured Agent ID
AGENT_TOKEN	Pre-configured agent token
AGENT_JWT	Pre-configured agent JWT
AGENT_NAME	Agent name used by init when --name is omitted
CLIENT_INFO	Client info used by init when --client is omitted
FLUXA_DATA_DIR	Data directory (default ~/.fluxa-ai-wallet-mcp)
FLUXA_KEY	Optional fxa_live_… API key for market commands. Without it, the CLI authenticates market commands with the agent's own identity

Supplying credentials from the environment

When all three of AGENT_ID, AGENT_TOKEN and AGENT_JWT are set, they take precedence over config.json. This suits containers and CI, where there's no persistent home directory.

export AGENT_ID="ag_xxxxxxxxxxxx"
export AGENT_TOKEN="<agent token>"
export AGENT_JWT="<agent jwt>"
fluxa-wallet status

If only some of the three are set, they're ignored and config.json is used. With environment credentials, a refreshed JWT lasts only for that one command and isn't written back anywhere. Each new command refreshes it again if needed, which is harmless.