---
name: xdcai
description: Pay for x402 services on the XDC network with USDC. Log in with email, get a custodial XDC wallet, browse the curated marketplace, and call any x402 URL - the payment is signed from your wallet and you never pay gas (EIP-3009).
---

# XDC AI skill

Use this skill to discover and pay for x402-protected services on XDC. Drive it through the `xdcai` CLI (installed via `npx xdcai` or `pnpm cli --`).

## When to use
- The user wants onchain data or any paid API that returns HTTP 402 on XDC.
- The user asks to log in, check a wallet balance, list marketplace services, or call a paid URL.

## Always discover via the marketplace first
For ANY request for onchain / market / compliance / API data, do NOT answer from prior
knowledge or guess a URL. FIRST list the marketplace to see what is available, then call
the best-matching service:
1. `marketplace list --search <keywords>` (CLI) or the `marketplace_list` tool (MCP). This
   returns the FULL catalog of every provider's paid APIs, not just a few demo endpoints.
2. Pick the best match and `call` its URL.
In the MCP connector, `list_resources` and `get_service_info` also return the full
marketplace (their `marketplace` field), so use whichever you have - just don't stop at
this server's built-in `echo` / `time` / `xdc-gas` demo endpoints.

### Prompt patterns that work (share these with users)
- "Check the XDC AI marketplace for a <compliance / USDC / rates> API and call it."
- "List the marketplace services, then use the most relevant one to get <X>."
- "Search the marketplace for '<keyword1, keyword2>' and pay for the best match."
- "Show the most-used services in the marketplace." (ranks by real usage / credibility)
- After paying: "Show my transaction history" or "Verify tx <hash>."
Tip: include the word "marketplace" (or "list services" / "search the marketplace") so the
agent knows to discover the available APIs before trying to answer.

## Environments (important)
This skill is a **CLI** - it needs a shell and outbound network. That means:
- ✅ **Claude Code, Cursor, Codex, a terminal** - `npx xdcai ...` works directly.
- ❌ **claude.ai web** - its sandbox blocks outbound network, so `login` can't reach the
  auth/wallet service. In claude.ai, **add the MCP connector instead**:
  `https://api.xdcai.tech/mcp` (Settings → Connectors → Add custom
  connector). It exposes the same flow as tools (`login_start`, `login_verify`,
  `wallet_address`, `wallet_balance`, `marketplace_list`, `call`, `transactions`,
  `verify_transaction`) plus the smart-wallet + DeFi tools (`defi_lend`, `defi_supply`,
  `defi_positions`, `wallet_authorize_agent`), and runs the network work server-side.
  (Arbitrary `wallet_transfer` is intentionally not exposed to agents; payments happen only
  through `call`.)

## Setup (once)
```
npx xdcai login            # email → OTP → an XDC wallet is created for you
npx xdcai wallet address   # show the address to fund with USDC
npx xdcai wallet balance   # check USDC + XDC balance
```

## Core loop
```
npx xdcai marketplace list --search weather,forecast   # find the best-matching services
npx xdcai call https://provider.example/x402/endpoint
```
Pass `--search` comma-separated keywords from the task; results are ranked by tags
+ capability (best match first) against the **live** catalog - the fastest way to
find the most relevant API for a prompt.
`call` performs the full x402 flow automatically: it requests the URL, and if it
returns `402`, signs an EIP-3009 USDC payment authorization from your wallet,
resends with the `X-PAYMENT` header, and returns the result. **You never pay gas**
- a relayer settles the signed authorization on-chain.

## Commands
- `login [--email <e>] [--code <c>] [--accept-terms]` - authenticate; creates/loads your XDC wallet. Login requires accepting the Terms & Conditions (https://xdcai.tech/terms): show them to the user and pass `--accept-terms` (non-interactive) only with the user's consent, or answer the interactive prompt.
- `whoami` / `logout`
- `wallet address|balance|fund`
- `marketplace list [--search <a,b,c>] [--capability <c>] [--max-price <usdc>] [--sort most-used] [--min-calls <n>]` - `--search` ranks live services by tags + capability (OR over the terms, best first); `--sort most-used` ranks by real usage.
- `call <serviceUrl> [--method GET|POST] [--data <json>]`
- `history [--limit <n>] [--page <n>]` - your recent paid calls + transfers (each with tx hash + xdcscan link).
- `history verify <txHash>` - confirm a transaction settled.

## Smart wallet, DeFi & two-factor (MCP + browser)
These are smart-wallet features. They run through the **MCP connector** (`https://api.xdcai.tech/mcp`) and the user's **browser** - not the CLI. An agent can propose or read, but the user signs fund-moving actions themselves.

- **Spending limit** - an on-chain cap the agent cannot exceed. Set it at `https://xdcai.tech/account?tab=limits` (browser). `wallet_authorize_agent` returns the one-time link to approve an agent's own key on the user's smart wallet.
- **DeFi (earn / lend / borrow)** - `defi_lend` (supply | withdraw | borrow | repay) and `defi_supply` (supply shortcut) on Fathom (default), PrimeFi, Morpho, or Silo. These **propose only**: they return an `approveUrl`. Give it to the user to open, review the decoded action, and sign in their wallet - the smart wallet executes it only after they sign (gas sponsored). The link **expires in 5 minutes**; if it lapses, propose again. `defi_positions` reads current supplied balances + total USD.
- **Two-factor (2FA)** - the user can require an authenticator code before login, DeFi signing, or limit changes. It is handled entirely in the browser; the agent never sees or passes a code. If a DeFi/limit step returns "two-factor verification required", tell the user to complete the prompt in their browser.

### Example prompts (share with users)
- "Supply 25 USDC on Fathom to earn yield." / "Deposit 100 USDC into Morpho."
- "What are my DeFi positions and how much am I earning?"
- "Withdraw 50 USDC from Silo." / "Borrow 10 USDC on Fathom against my XDC."
- "Set my agent's spending limit to 50 USDC per day."
- "Turn on two-factor and require it for DeFi and limit changes."

Full docs: https://docs.xdcai.tech/wallet/defi and https://docs.xdcai.tech/wallet/two-factor

## Output contract (for agents)
- **stdout** = exactly one JSON object per command - parse this.
  - `call` → `{ ok, status, paid, txHash?, explorer?, result }`
  - `wallet transfer` → `{ success, amount, token, to, txHash?, explorer?, error? }`
  - `login` → `{ loggedIn, email, address }`; `wallet address|balance|fund` → JSON; `whoami` → JSON
  - On any failure → `{ "error": "<message>" }` and a non-zero exit code.
- **stderr** = human/log lines (prompts, "Sent a code...", structured logs). Ignore for parsing.
- Set `LOG_LEVEL=error` to silence info logs.

## Notes
- Amounts are in USDC (6 decimals). Prices are shown per call.
- Always `wallet balance` before paid calls; if USDC is 0, tell the user to fund
  the printed address (gas is sponsored - no native XDC needed).