Stelagent — Agent-First CLI for Stellar

npx stelagent@latest and bunx stelagent@latest always resolve and run the latest published version. The @latest tag is recommended to ensure you never run a stale cached version. No separate upgrade command is needed.

Network Selection

All commands accept -n testnet|pubnet (default: testnet).

• testnet — Horizon: https://horizon-testnet.stellar.org. Accounts auto-funded via Friendbot on wallet creation.
• pubnet — Horizon: https://horizon-mainnet.stellar.org. Real funds. Real consequences.

Parameter Rules

Public Key Format

Stellar public keys start with G, followed by 55 uppercase alphanumeric characters (Base 32): G[A-Z2-7]{55}.

• Validate before passing to any command.
• Display abbreviated as GABCD...WXYZ (first 8 + last 4).

Asset Format

• Native XLM: use native or omit the asset flag (native is default).
• Custom asset: CODE:ISSUER (e.g., USDC:GBTX...). Code is 1–12 alphanumeric characters, issuer is a G... public key.

Amount

• Numeric with up to 7 decimal places (Stellar precision).
• Always display in UI units (1.5 XLM, 100 USDC).

Command Index

CLI Reference: For full parameter tables, return field schemas, and usage examples, see cli-reference.md.

A — Wallet Lifecycle

Login commands (A1–A2) are covered in detail in Authentication below.

B — Payments

C — Account Queries (Public, No Auth)

D — Asset Queries (Public, No Auth)

E — Network

F — Streaming (SSE)

G — MCP

All commands accept -f json (default) or -f text. Most accept -n testnet|pubnet. Account and asset commands support --limit, --cursor, --order asc|desc.

Authentication

The login flow is always a two-step process:

1. wallet login — sends an OTP code to the user's email
2. wallet verify — verifies the code, creates the session, and creates/recoveries the wallet

This applies identically whether using the CLI directly or the MCP server — CLI and MCP have 1:1 parity in functionality and behavior.

Step 1 — Request OTP

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.

Step 2 — Verify OTP

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...WXYZ on testnet.

On testnet, the account is automatically funded via Friendbot.

Check Login Status

npx stelagent@latest wallet address

• Logged in: { ok: true, data: { publicKey: "G...", network: "testnet", email: "..." } }
• Not logged in: { ok: false, error: "No wallet found. Run stelagent wallet login first." }

Logout

npx stelagent@latest wallet logout

Operation Flows

Flow 1: First-Time Wallet Setup

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."

Flow 2: Check Balance and Send Payment

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>"

Flow 3: Research Asset and Send Custom Asset

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>"

Flow 4: Full Account Review

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

Flow 5: X402 Payment

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:

1. CLI fetches the URL. If status ≠ 402, returns response directly — no payment needed.
2. If status = 402, signs Soroban auth entries with the wallet's Ed25519 keypair.
3. Re-fetches with payment headers. Returns the paid content.

Flow 6: Monitor Account Activity

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.

Flow 7: Asset Market Research

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

Flow 8: Portfolio Check

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

MCP Server

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

MCP Tool Surface (16 Tools)

MCP Authentication Flow

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.

MCP Client Configuration

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"]
    }
  }
}

Security Notes

Error Handling

All output follows { ok: true, data } | { ok: false, error: string }.

Environment Variables

Audit Trail

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].

Edge Cases

For detailed troubleshooting, see troubleshooting.md.

Authentication

• OTP expired: Codes expire after a few minutes. Request a new one with wallet login.
• Too many attempts: 5+ wrong guesses locks the session. Request a new OTP.
• API unreachable: Check network and STELAGENT_API_URL env var.

Send / Transfer

• Insufficient balance: Check balance first. Warn if remaining would fall below minimum reserve (1 XLM + 0.5 XLM per subentry).
• Unfunded destination: If the destination account doesn't exist, the transaction will fail. Inform the user.
• Invalid asset format: Custom assets must be CODE:ISSUER. If the format is wrong, the CLI returns a validation error.

Account Queries

• Unfunded account: Horizon returns 404 for accounts that have never received XLM. The CLI translates this to UnfundedAccountError.
• No transactions/payments/effects: Return empty arrays. Display "No results found" — not an error.

X402 Payment

• Non-402 response: Return the response directly. No payment was needed.
• Payment failed (402 after signing): The server rejected the payment. Check settlement header for details.

Monitor (SSE)

• Connection drops: The Horizon SSE stream may disconnect. The CLI handles reconnection internally.
• Cursor usage: Use --cursor <id> to resume from a specific event. Default now starts from new events only.

Global Notes