Use this skill when the user wants to set up a Stellar wallet, log in, verify OTP, check wallet balance, send XLM or assets, make X402 payments, view wallet address, query account data, search assets, check fees, stream live events, start an MCP server, or any other interaction with the stelagent CLI for Stellar. Triggers on mentions of stelagent, Stellar wallet, X402 payments on Stellar, Stellar account queries, XLM transfers, Stellar testnet/pubnet operations, Horizon API queries, Stellar asset search, Stellar fee estimation, Stellar transaction history, Stellar payment history, Stellar streaming, or MCP server for Stellar.
Manage Stellar wallets, send payments, make X402 HTTP payments, query on-chain data, and expose everything via MCP — all from the terminal or through AI agent orchestration.
This document uses tagged blocks to indicate rule severity. In case of conflict, higher priority wins:
<NEVER> — Absolute prohibition. Violation may cause irreversible fund loss. Never bypass.<MUST> — Mandatory step. Skipping breaks functionality or safety.<SHOULD> — Best practice. Follow when possible; deviation acceptable with reason.Before the first stelagent command this session, verify the CLI is available:
npx stelagent@latest --version
If not installed, inform the user: "stelagent is not installed. Run npm install -g stelagent or use to run without installing."
npx stelagent@latest
npx stelagent@latestandbunx stelagent@latestalways resolve and run the latest published version. The@latesttag is recommended to ensure you never run a stale cached version. No separate upgrade command is needed.
All commands accept -n testnet|pubnet (default: testnet).
https://horizon-testnet.stellar.org. Accounts auto-funded via Friendbot on wallet creation.https://horizon-mainnet.stellar.org. Real funds. Real consequences.Stellar public keys start with G, followed by 55 uppercase alphanumeric characters (Base 32): G[A-Z2-7]{55}.
GABCD...WXYZ (first 8 + last 4).native or omit the asset flag (native is default).CODE:ISSUER (e.g., USDC:GBTX...). Code is 1–12 alphanumeric characters, issuer is a G... public key.1.5 XLM, 100 USDC).CLI Reference: For full parameter tables, return field schemas, and usage examples, see cli-reference.md.
Login commands (A1–A2) are covered in detail in Authentication below.
| # | Command | Description | Auth |
|---|---|---|---|
| A1 | npx stelagent@latest wallet login -e <email> | Request OTP (sends code to email) | No |
| A2 | npx stelagent@latest wallet verify -e <email> -o <code> | Verify OTP, create/recover wallet | No |
| A3 | npx stelagent@latest wallet address | Show public key, network, email (no secret) | Yes |
| A4 | npx stelagent@latest wallet balance | Show all asset balances | Yes |
| A5 | npx stelagent@latest wallet transfer -t <addr> -a <amount> | Send XLM | Yes |
| A6 | npx stelagent@latest wallet logout | Clear local session | Yes |
| # | Command | Description | Auth |
|---|---|---|---|
| B1 | npx stelagent@latest pay <url> | X402 micropayment (detects 402, signs, pays) | Yes |
| B2 | npx stelagent@latest send <addr> <amount> [-a asset] [-m memo] | Send any asset (XLM or custom) | Yes |
| B3 | npx stelagent@latest preflight <addr> <amount> [-a asset] | Validate a payment before sending | Yes |
| # | Command | Description | Auth |
|---|---|---|---|
| C1 | npx stelagent@latest account details <addr> | Account info: balances, signers, thresholds, flags | No |
| C2 | npx stelagent@latest account transactions <addr> | Transaction history | No |
| C3 | npx stelagent@latest account payments <addr> | Payment history | No |
| C4 | npx stelagent@latest account effects <addr> | Effect history | No |
| # | Command | Description | Auth |
|---|---|---|---|
| D1 | npx stelagent@latest assets search [-c code] [-i issuer] | Search assets by code/issuer | No |
| D2 | npx stelagent@latest assets orderbook -s <asset> -b <asset> | View orderbook for asset pair | No |
| # | Command | Description | Auth |
|---|---|---|---|
| E1 | npx stelagent@latest fee | Current fee statistics from Horizon | No |
| # | Command | Description | Auth |
|---|---|---|---|
| F1 | npx stelagent@latest monitor transactions <addr> | Stream transactions in real-time | No |
| F2 | npx stelagent@latest monitor payments <addr> | Stream payments in real-time | No |
| F3 | npx stelagent@latest monitor effects <addr> | Stream effects in real-time | No |
| # | Command | Description | Auth |
|---|---|---|---|
| G1 | npx stelagent@latest mcp | Start MCP server on stdio | No |
All commands accept -f json (default) or -f text. Most accept -n testnet|pubnet. Account and asset commands support --limit, --cursor, --order asc|desc.
The login flow is always a two-step process:
wallet login — sends an OTP code to the user's emailwallet verify — verifies the code, creates the session, and creates/recoveries the walletThis applies identically whether using the CLI directly or the MCP server — CLI and MCP have 1:1 parity in functionality and behavior.
Ask the user for their email, then run:
npx stelagent@latest wallet login -e <email>
Success: { ok: true, data: { message: "OTP sent to [email protected]" } }
Then tell the user:
A verification code has been sent to {email}. Please check your inbox and tell me the code.
Once the user provides the code, run:
npx stelagent@latest wallet verify -e <email> -o <code>
Success:
{
"ok": true,
"data": {
"wallet": {
"email": "[email protected]",
"publicKey": "GABCD...WXYZ",
"network": "testnet",
"createdAt": "2026-04-13T..."
}
}
}
After successful verification, show:
Wallet ready! Your Stellar address is
GABCD...WXYZon testnet.
On testnet, the account is automatically funded via Friendbot.
npx stelagent@latest wallet address
{ ok: true, data: { publicKey: "G...", network: "testnet", email: "..." } }{ ok: false, error: "No wallet found. Run stelagent wallet login first." }npx stelagent@latest wallet logout
User: "Set up my Stellar wallet"
1. Ask email: "What is your email address?"
2. Login: npx stelagent@latest wallet login -e <email>
↓ "OTP sent to <email>"
3. Ask code: "Check your inbox and tell me the code."
4. Verify: npx stelagent@latest wallet verify -e <email> -o <code>
↓ { wallet: { publicKey, network, ... } }
5. Confirm: "Wallet ready! Your address is GABCD...WXYZ on testnet."
User: "Send 10 XLM to GDXYZ..."
1. Check auth: npx stelagent@latest wallet address
↓ if not logged in → Flow 1
2. Preflight: npx stelagent@latest preflight GDXYZ... 10
↓ verify canProceed is true, review warnings
3. Check balance: npx stelagent@latest wallet balance
↓ verify sufficient balance (include 1 XLM minimum reserve)
4. Send: npx stelagent@latest send GDXYZ... 10
↓ returns { from, to, amount, asset, txHash }
5. Confirm: "Sent 10 XLM to GDXYZ...WXYZ. Tx: <hash>"
User: "Send 100 USDC to GDXYZ..."
1. Search asset: npx stelagent@latest assets search -c USDC
↓ verify asset exists, note issuer
2. Check auth: npx stelagent@latest wallet address
↓ if not logged in → Flow 1
3. Preflight: npx stelagent@latest preflight GDXYZ... 100 -a "USDC:GAXYZ..."
↓ verify canProceed is true
4. Send: npx stelagent@latest send GDXYZ... 100 -a "USDC:GAXYZ..."
↓ returns { from, to, amount, asset, txHash, ledger }
5. Confirm: "Sent 100 USDC to GDXYZ...WXYZ. Tx: <hash>"
User: "Show me everything about my account"
1. Check auth: npx stelagent@latest wallet address
↓ get publicKey
2. Account details: npx stelagent@latest account details <publicKey>
↓ show balances, signers, thresholds, flags
3. Transactions: npx stelagent@latest account transactions <publicKey> --limit 5
↓ show recent activity
4. Effects: npx stelagent@latest account effects <publicKey> --limit 5
↓ show recent effects
User: "Fetch https://api.example.com/premium — it needs payment"
1. Check auth: npx stelagent@latest wallet address
↓ if not logged in → Flow 1
2. Pay: npx stelagent@latest pay https://api.example.com/premium
↓ detects 402 → signs auth entries → re-fetches with payment
3. Result: { url, status, paymentRequired: true, settlement, bodyPreview }
The X402 flow:
User: "Watch for new transactions on GDXYZ..."
1. Stream: npx stelagent@latest monitor transactions GDXYZ...
↓ SSE stream prints each transaction as it arrives
2. User presses Ctrl+C to stop
Monitor commands accept --cursor (default: now) to resume from a position.
User: "What's the USDC orderbook look like?"
1. Search: npx stelagent@latest assets search -c USDC
↓ find the USDC asset and issuer
2. Orderbook: npx stelagent@latest assets orderbook -s native -b "USDC:<issuer>"
↓ show bids and asks
3. Fee check: npx stelagent@latest fee
↓ show current network fees
User: "What do I hold?"
1. Check auth: npx stelagent@latest wallet address
2. Balance: npx stelagent@latest wallet balance
↓ for each non-native asset:
3. Enrich: npx stelagent@latest assets search -c <code>
↓ add market context
The MCP server provides 1:1 parity with the CLI — every CLI command has a corresponding MCP tool with identical behavior and output format. The only exception is monitor commands (SSE streaming doesn't fit request/response).
npx stelagent@latest mcp
| Category | Tool | CLI Equivalent | Description | Auth |
|---|---|---|---|---|
| Wallet | wallet_login | wallet login -e | Request OTP to email | No |
| Wallet | wallet_verify | wallet verify -e -o | Verify OTP, create session + wallet | No |
| Wallet | wallet_address | wallet address | Get public key, network, email | Yes |
| Wallet | wallet_balance | wallet balance | Get all asset balances | Yes |
| Wallet | wallet_transfer | wallet transfer -t -a | Send XLM to another address | Yes |
| Wallet | wallet_logout | wallet logout | Clear session | Yes |
| Account | account_details | account details | Full account info from Horizon | No |
| Account | account_transactions | account transactions | Transaction history | No |
| Account | account_payments | account payments | Payment history | No |
| Account | account_effects | account effects | Effect history | No |
| Assets | assets_search | assets search | Search assets by code/issuer | No |
| Assets | assets_orderbook | assets orderbook | View orderbook for asset pair | No |
| Assets | fee_stats | fee | Current fee statistics | No |
| Payment | send_payment | send | Send any asset payment | Yes |
| Payment | pay_url | pay | X402 payment to a URL | Yes |
| Payment | preflight_check | preflight | Validate a payment before sending | Yes |
MCP tools use the same two-step authentication as the CLI:
1. wallet_login({ email: "[email protected]" })
→ { ok: true, data: { message: "OTP sent to [email protected]" } }
2. Ask the user for the code, then:
wallet_verify({ email: "[email protected]", otp: "123456", network: "testnet" })
→ { ok: true, data: { wallet: { email, publicKey, network, createdAt } } }
After wallet_verify, the session is saved to ~/.stelagent/session.json and all authenticated tools work.
Claude Code (~/.claude/settings.json):
{
"mcpServers": {
"stelagent": {
"command": "npx",
"args": ["stelagent@latest", "mcp"]
}
}
}
Cursor (.cursor/mcp.json):
{
"mcpServers": {
"stelagent": {
"command": "npx",
"args": ["stelagent@latest", "mcp"]
}
}
}
OpenCode (.opencode.json):
{
"mcp": {
"stelagent": {
"command": "npx",
"args": ["stelagent@latest", "mcp"]
}
}
}
All output follows { ok: true, data } | { ok: false, error: string }.
| Error | Cause | Resolution |
|---|---|---|
"No wallet found. Run stelagent wallet login first." | Not logged in or expired session | Run npx stelagent@latest wallet login -e <email> then wallet verify |
"Could not reach auth server." | API unreachable | Check network, verify STELAGENT_API_URL |
"OTP verification failed." | Wrong or expired code | Run npx stelagent@latest wallet login -e <email> again |
"Too many attempts" | 5+ wrong OTP guesses | Request a new OTP |
"StellarAccountError" | Account not found on network | Fund testnet account via login (auto-funded) |
"InsufficientBalanceError" | Not enough balance | Fund the account or reduce amount |
"UnfundedAccountError" | Account not yet activated | Send at least 1 XLM to activate it |
| Variable | Default | Purpose |
|---|---|---|
STELAGENT_API_URL | https://stelagent.noval.me | API base URL for auth/wallet |
STELAGENT_HORIZON_TESTNET_URL | https://horizon-testnet.stellar.org | Horizon testnet |
STELAGENT_HORIZON_PUBNET_URL | https://horizon-mainnet.stellar.org | Horizon mainnet |
All CLI commands are logged to ~/.stelagent/audit.jsonl with timestamp, command, duration, and redacted arguments. This is enabled by default.
Format:
{
"ts": "2026-04-13T10:30:00.123Z",
"source": "cli",
"command": "account details",
"ok": true,
"duration_ms": 234,
"args": ["stelagent", "account", "details", "--network", "testnet"]
}
Sensitive flags (--secret, --email, --otp, --wallet) have their values redacted to [REDACTED].
For detailed troubleshooting, see troubleshooting.md.
wallet login.STELAGENT_API_URL env var.CODE:ISSUER. If the format is wrong, the CLI returns a validation error.UnfundedAccountError.settlement header for details.--cursor <id> to resume from a specific event. Default now starts from new events only.