Tools & commands reference

The same capabilities are available two ways: CLI commands (xdcai …) and MCP tools (the connector). This page is the canonical reference. A machine-readable manifest is served at /skill.json and /SKILL.md.

CLI ↔ MCP mapping

CLI command	MCP tool	Description
login	login_start + login_verify	Email + OTP auth; creates/loads your XDC wallet.
wallet address	wallet_address	Your XDC wallet address (fund with USDC).
wallet balance	wallet_balance	USDC + native XDC balance.
marketplace list	marketplace_list	Search/list the live catalog.
call	call	Pay for and call a service URL (x402).
history	transactions	Recent paid calls + transfers.
history verify	verify_transaction	Confirm a tx settled on-chain.
—	defi_lend, defi_supply	Propose a DeFi action (returns an approval link the user signs).
—	defi_positions	Read the user's supplied DeFi balances + total USD.
—	wallet_authorize_agent	Check/return the one-time link to approve an agent's key on the smart wallet.
—	get_service_info, list_resources, inspect_resource	Service discovery / manifest.

marketplace list / marketplace_list

Discover services on the live catalog. Ranking is by capability + tags + provider name against your search terms (OR semantics, best match first); hard filters are applied first.

Parameter	Meaning
search	Comma-separated keywords, e.g. "rates,defi,usdc" — ranked, best first.
capability	Exact capability filter.
maxPrice / --max-price	Max price in USDC, e.g. "0.05".
--sort most-used	Rank by real usage (credibility).
--min-calls <n>	Only services with at least n calls.

call

Runs the full x402 flow:

npx xdcai call <serviceUrl> [--method GET|POST] [--data '<json>']

Returns:

{ "ok": true, "status": 200, "paid": "0.01", "txHash": "0x…", "explorer": "https://xdcscan.io/tx/0x…", "result": { } }

DeFi (propose, then the user signs)

defi_lend / defi_supply do not move funds. They record the intent and return an approveUrl. Hand that link to the user - they open it, review the decoded action, complete two-factor, and sign in their browser. Only then does the smart wallet execute it (gas sponsored).

defi_lend { amountUSDC: 25, operation: "supply", protocol: "fathom" }
→ { proposed: true, approveUrl: "https://xdcai.tech/approve?defi=..." }

• Protocols: fathom (default), primefi, morpho, silo. Fathom/PrimeFi do all of supply/withdraw/borrow/repay; Morpho/Silo are supply/withdraw only.
• The approval link expires 5 minutes after it is created. If it lapses, propose again.
• After the user signs, call defi_positions to confirm the new balance.
• Full guide: DeFi - earn, lend & borrow.

Two-factor (browser-side)

Changing a spending limit or signing a DeFi action can require two-factor verification. This is handled entirely in the user's browser - an agent never sees or passes a code. If a limit or DeFi step returns "two-factor verification required", tell the user to complete the prompt in their browser; there is nothing for the agent to do with the code.

Output contract (for agents)

• stdout = exactly one JSON object per command — parse this.
  • call → { ok, status, paid, txHash?, explorer?, result }
  • login → { loggedIn, email, address }
  • wallet address|balance → JSON; whoami → JSON
  • Any failure → { "error": "<message>" } + non-zero exit code.
• stderr = human/log lines (prompts, "Sent a code…", logs). Ignore for parsing.
• LOG_LEVEL=error silences info logs.

Notes

• Amounts are in USDC (6 decimals). Prices are shown per call.
• Always check wallet balance before paid calls. If USDC is 0, fund the printed address — gas is sponsored, so no native XDC is needed.
• Payments happen only through call; the value is derived from the service's 402 challenge.