---
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`) 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.

## 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).