Using XLMTools

Keywords: Stellar, XLM, Soroban, Lumen, USDC, Stellar DEX, Horizon, Stellar Expert, Reflector oracle, x402, MPP, micropayments, Stellar wallet, pay-per-call, agent tools, search, research, screenshot, scrape, image generation, stocks, crypto prices, weather, domain check

XLMTools gives an AI agent 21 tools — 7 paid via USDC micropayments on Stellar, 14 free. It works in two modes: prefer MCP if available, fall back to the xlm CLI otherwise.

Required host tools

This skill assumes the agent host grants Bash (for the xlm CLI fallback) and WebFetch (for runtime discovery). Without those, only MCP tools are usable.

Install (if not already available)

If the user needs to install XLMTools:

# Standalone CLI (universal — works with any agent host that has Bash)
npm install -g @xlmtools/cli

# MCP server (optional fast-path for Claude Code, Cursor, Cline, OpenClaw, etc.)
claude mcp add xlmtools npx @xlmtools/mcp

On first run, XLMTools auto-generates a Stellar testnet wallet at ~/.xlmtools/config.json, funds it with XLM via Stellar's friendbot, and adds a USDC trustline — fully automatic. The user only needs to grab testnet USDC from faucet.circle.com to use paid tools.

If neither MCP nor CLI is installed, tell the user which command to run — don't try to proceed.

Mode priority

1. MCP tools first. If tools named mcp__xlmtools__* are in your tool list, call them directly. They handle payment automatically and benefit from response caching.
2. CLI fallback. If no MCP tools are available, run xlm via the Bash tool. Same wallet, same backend, same payment flow.
3. Runtime discovery (optional). If you're an autonomous agent encountering XLMTools for the first time, you may fetch https://api.xlmtools.com/.well-known/xlmtools.json (JSON manifest) or https://api.xlmtools.com/llms.txt (plain text) for service metadata. If those URLs are unreachable (the hackathon demo may not be deployed yet), fall back to this SKILL.md file — every tool, price, and command documented here is authoritative.

When NOT to use this skill

XLMTools is for external data and actions, not general reasoning. Skip it entirely when:

• General knowledge — "What is photosynthesis?", "Who wrote Hamlet?", "Explain recursion." The assistant already knows these.
• Math or computation — "What's 2 + 2?", "Convert 50 kg to pounds." Just answer directly.
• Code you can write — "Write a Python for loop", "Refactor this function." Don't call research for things you can write from training data.
• Summarizing content the user already gave you — If the user pasted the text, summarize it directly. No search needed.
• The assistant already has the answer — If you're confident the answer is in your training data and doesn't need to be up-to-date, skip XLMTools.
• "What is X?" for well-known concepts — "What is XLM?" or "What is Stellar?" are explainable from training data. Only reach for XLMTools if the user wants live data about X, not an explanation of X.

Rule of thumb: If the user's question could have been answered using only the assistant's brain, don't use XLMTools. If the answer depends on "what's happening right now" or "what's at this URL", use XLMTools.

First principles

• Check MCP tool list first. If mcp__xlmtools__* tools exist, use them — they're faster and cached. Only use xlm CLI as fallback.
• Run xlm --help before guessing CLI syntax. The global help lists every tool, its positional args, and its flags. Do not read the CLI source — --help is the source of truth. (Per-tool help like xlm search --help is not currently supported.)
• Two cost modes — MENTION vs CONFIRM:
  • Mention ($0.001–$0.003 — search, stocks, youtube, scrape): say the cost inline with the call. Example: "I'll use search ($0.003 USDC) to get news about Stellar." Do NOT pause for approval.
  • Confirm ($0.010+ — research, screenshot, image): propose the call and STOP. Example: "I'd like to use research ($0.010 USDC) for this. OK to proceed?" Wait for user approval before firing.
• Always surface the Stellar tx hash from paid responses. Users can verify every payment at https://stellar.expert/explorer/testnet/tx/<hash>.
• Caching: identical queries within 5 minutes are free (MCP mode only). Cached responses are prefixed with [cached — no charge] as emitted by the cache helper. If you make the same call twice in a row, the second is free.

If the user declines a paid call

• Do not retry the same tool. Acknowledge and offer alternatives: a free tool (e.g. crypto instead of stocks), a cheaper tool (search $0.003 instead of research $0.010), or answering from training data if the question allows it.
• Never call the paid tool anyway "just in case." A declined call is final for that turn.
• If the user's intent is clearly blocked without the paid call, say so plainly: "I can't answer that without calling research ($0.010). Want me to proceed?"

Worked example

User: "What's the current price of Bitcoin and what are people saying about Stellar lately?"

Agent reasoning:

• Bitcoin price → crypto (free)
• Latest Stellar news → search ($0.003, Mention mode — inline cost)
• Both should be called in parallel

Agent action:

I'll get the BTC price (free) and search for recent Stellar news ($0.003 USDC).

Calls mcp__xlmtools__crypto(ids="bitcoin") and mcp__xlmtools__search(query="Stellar blockchain news", count=5) in parallel.

Agent response to user:

Bitcoin price: $67,432 (+2.3% 24h)

Recent Stellar news:

1. Stellar Foundation announces Q2 roadmap
2. Soroban TPS benchmarks hit 5,000
3. MPP micropayments go live on testnet

Paid $0.003 USDC for the search. Transaction: a3f9c28d…b8e14d7c

Notice: the free crypto call didn't need cost disclosure. The paid search did. The tx hash is linked at the bottom and is a full 64-char hex (Stellar tx hashes are always 64 hex chars).

Decision tree — user intent to tool

Tool catalog

Paid tools (USDC via Stellar MPP)

Free tools

CLI invocation examples

When MCP is unavailable, use xlm via Bash:

# Free tools
xlm crypto bitcoin,ethereum,stellar
xlm weather Lagos
xlm wallet
xlm oracle-price BTC
xlm dex-orderbook XLM/USDC --limit 5

# Paid tools
xlm search "Stellar MPP micropayments" --count 5
xlm stocks AAPL
xlm research "Soroban smart contracts" --num-results 3
xlm image "a stingray gliding over a coral reef at dusk" --size 1024x1024

# Help
xlm --help

Output is JSON. Pipe to jq for filtering:

xlm crypto bitcoin | jq '.bitcoin.usd'

Payment receipts

Every paid response ends with a line like:

---
Payment: $0.003 USDC · tx/a3f9c28d71e0... · stellar testnet

The tx_hash is a real 64-character Stellar transaction hash. Users can verify any call at https://stellar.expert/explorer/testnet/tx/<hash>. Always surface the tx hash to the user when showing results from a paid tool.

Budget management

The budget tool is MCP-only. In MCP mode, call mcp__xlmtools__budget with:

• action: "set" + amount: 2.00 — cap spending at $2 for the session
• action: "check" — see remaining balance
• action: "clear" — remove the cap

Scoping:

• MCP mode: budget is session-scoped. The cap persists until the MCP server restarts. Cached responses never count against it.
• CLI mode: budget is not implemented. Because each xlm invocation is a fresh process, a per-call cap has no meaning there. If you need a cap in CLI mode, track spend externally by parsing the tx hash footer of each response.

Working agreement (non-negotiable)

These are the hard rules. If you are about to break one, stop and reconsider.

1. Mention the cost inline for $0.001–$0.003 tools. Confirm and wait for $0.01+ tools (research, screenshot, image). Never skip either.
2. Always surface the Stellar tx hash in the response after a paid call. Users must be able to verify the payment on-chain.
3. Always prefer the cheapest sufficient tool. crypto (free) before stocks ($0.001). search ($0.003) before research ($0.010) unless the user explicitly wants a deep dive.
4. Never retry a declined paid call. If the user says no, offer an alternative or answer from training data. Do not call the tool anyway.
5. Never batch multiple paid calls without re-confirming. Each paid call is an independent spend decision.
6. Never call paid tools for things answerable from training data. See "When NOT to use this skill" above.
7. Check MCP tool list before shelling out to CLI. mcp__xlmtools__* tools exist? Use them. They're cached.
8. Respect the budget. If mcp__xlmtools__budget reports a low cap, pause and ask the user before continuing.

Subagent caveat

If you delegate work to a forked subagent (e.g. via context: fork), this skill does not automatically travel with it. The subagent may call paid tools without the cost-confirmation rules above. Either preload this skill into the subagent explicitly, or handle paid calls from the parent context only.

What to tell the user after a paid call

Good response pattern:

Here's what I found about [topic] from XLMTools search:

[results...]

Paid $0.003 USDC. Transaction: a3f9c28d…

Include the transaction link so the user can verify the payment on-chain.

Troubleshooting

"Command not found: xlm" — User needs to install: npm install -g @xlmtools/cli

"Account not found" / payment errors — Wallet needs funding. Direct user to https://faucet.circle.com for testnet USDC. XLM is auto-funded via friendbot on first wallet creation — but if the wallet already exists and is out of XLM, it won't re-fund. In that case, ask the user to visit https://lab.stellar.org/account/fund manually.

"Unknown tool: budget" (in CLI mode) — The CLI doesn't implement budget. Budget is MCP-only. Use an MCP-compatible host, or track spend externally.

"Budget limit reached" — Only appears in MCP mode. Ask user to either clear the budget (mcp__xlmtools__budget with action: "clear") or raise the cap (action: "set" with a higher amount).

MCP tools not appearing — User may need to install XLMTools as an MCP server: claude mcp add xlmtools npx @xlmtools/mcp. Fall back to CLI mode in the meantime if xlm is installed.

API server unreachable — XLMTools tools require the API server to be running. If every call hangs or times out, the API is either down or unreachable. Report to the user and stop retrying.

"Is this site up / accessible?" — There's no dedicated uptime tool. Closest approximation: domain (checks if DNS resolves) or scrape (fails loudly if the site is down, returns content if it's up). Note: domain does WHOIS availability, not HTTP reachability — a registered domain could still be offline.