xstocks-mcp

v0.1.4

Published

5 hours ago

MCP server to buy/sell tokenized US stocks (xStocks by Backed) on Solana, paying directly in USDC via Jupiter DEX. Hard daily USD cap guard. Dry-run by default; opt-in for real-money swaps.

0High
0Medium
0Low

evidai_lemoncake

mcp model-context-protocol xstocks tokenized-stocks solana jupiter usdc agentic-trading ai-agent spending-cap guard lemoncake claude cursor

🟣 xstocks-mcp

MCP server to buy/sell tokenized US stocks (xStocks by Backed Finance) on Solana, paying directly in USDC via Jupiter DEX. Daily USD cap guard built in. Dry-run by default — real-money swaps require explicit opt-in.

npx -y xstocks-mcp

What this is

You give your AI agent the ability to buy real US stocks paying in USDC — fully on-chain on Solana, via Backed's xStocks (1:1-backed regulated tokenized equities) routed through Jupiter DEX. A hard daily USD cap in ~/.xstocks/cap.json survives MCP restarts and the agent literally cannot exceed it.

✅ No broker account needed — pure on-chain
✅ No partnership / KYB wait — Jupiter is public, xStocks are public mints
✅ Production-ready today (Solana mainnet)
✅ Pay Token pass-through model: your own Solana wallet signs the swap; LemonCake never custodies USDC
✅ Sibling MCPs: works alongside agent-payment-mcp (USDC for APIs), alpaca-guard-mcp (Alpaca brokerage guard), tokenized-stock-mcp (Dinari dShares)

Quickstart

1. Install

{
  "mcpServers": {
    "xstocks": {
      "command": "npx",
      "args":    ["-y", "xstocks-mcp"],
      "env": {
        "SOLANA_WALLET_PRIVATE_KEY": "<<<your base58 private key (Phantom export) — OR keep empty for dry-run>>>",
        "XSTOCKS_ALLOW_LIVE":        "yes-i-understand",
        "SOLANA_RPC_URL":            "https://api.mainnet-beta.solana.com"
      }
    }
  }
}

Leave both SOLANA_WALLET_PRIVATE_KEY and XSTOCKS_ALLOW_LIVE unset → server stays in dry-run mode (all reads work, no swap is sent).

2. Fund your wallet

USDC on Solana mainnet (mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) — the amount you want to spend on stocks
~0.01 SOL (~$2) for transaction gas

Best UX: use Phantom or Solflare, fund via Coinbase / Kraken / on-ramp service.

3. Set the daily cap

Set my xstocks daily limit to $25.

→ Agent calls guard_set_limit({ dailyLimitUsd: 25 }). The first-ever default is $25 as a safety floor.

4. Let the agent trade

Buy $5 of AAPL via xstocks.

→ Agent calls guarded_buy_stock({ symbol: "AAPL", amountUsd: 5 }). The guard preflights against your cap + Jupiter quote, and only if everything passes does the swap go live.

If the agent tries amountUsd: 1000:

{
  "allowed": false,
  "status": "BUDGET_EXCEEDED",
  "hint": "This swap would cost ~$1000.00 but only $25.00 remains under today's $25.00 cap. ..."
}

Tools

| Tool | Read-only? | Notes | | --------------------- | :--------: | ----- | | setup | ✅ | Env state, mode (live / dry-run), cap status, fee policy | | wallet_status | ✅ | Public key, SOL balance (gas), USDC balance | | guard_status | ✅ | Daily limit / used / remaining / lifetime swaps / recent 10 | | guard_set_limit | ❌ | Set the daily USD cap | | find_xstock | ✅ | Resolve ticker → verified Backed mint (filters out pump.fun scams) | | get_quote | ✅ | Jupiter quote for USDC → xStock, with price-impact safety check | | guarded_buy_stock | ❌ | Preflight + Jupiter swap. Dry-run unless XSTOCKS_ALLOW_LIVE=yes-i-understand |

Configuration

| Env var | Required | Default | Notes | | ----------------------------- | :------: | ------- | ----- | | SOLANA_WALLET_PRIVATE_KEY | live only | — | Base58 (Phantom/Solflare export) or [u8;64] JSON (Solana CLI keypair). 64 raw bytes. | | XSTOCKS_ALLOW_LIVE | live only | — | Must literally be yes-i-understand | | SOLANA_RPC_URL | — | https://api.mainnet-beta.solana.com | Use Helius / QuickNode for better reliability | | JUPITER_API_BASE | — | https://lite-api.jup.ag | Override for higher rate limits | | XSTOCKS_LEDGER_DIR | — | ~/.xstocks | Where cap.json lives | | XSTOCKS_MAX_PRICE_IMPACT_PCT| — | 2 | Refuse swaps where price impact exceeds this % | | LEMONCAKE_STOCK_FEE_USD | — | 0.10 | LemonCake fee per trade |

How verification works

Jupiter's token search returns lots of imitators (pump.fun copycats, mislabeled tokens). To find the real Backed-issued xStock for a ticker, find_xstock:

Searches Jupiter for the ticker (e.g. AAPLx)
Filters to results where tags includes BOTH "verified" AND "xstocks"
Verifies the icon is hosted at xstocks-metadata.backed.fi
Confirms it's Token-2022 program (Backed uses Token-2022 for transfer hooks)

Result: only the real mint gets returned. Scams are silently dropped.

Architecture

┌──────────────────────────────────────┐
│  Agent (Claude / Cursor / Cline)     │
└────────────┬─────────────────────────┘
             │ tool: guarded_buy_stock(symbol, amountUsd, slippageBps?)
             ▼
┌─────────────────────────────────────────────────────────────────────┐
│  xstocks-mcp                                                          │
│                                                                       │
│  1. find_xstock — resolve ticker → real Backed mint                   │
│  2. ledger.preflight — check today's cap                              │
│  3. Jupiter /quote — get expected output + price impact               │
│  4. price-impact safety (XSTOCKS_MAX_PRICE_IMPACT_PCT)                │
│  5. (dry-run: STOP HERE) OR (live: Jupiter /swap → sign → send)       │
│  6. Record charge in local ledger + emit x402-shaped receipt          │
└──────────────────┬──────────────────┬─────────────────────────────────┘
                   │                  │
                   ▼                  ▼
┌──────────────────────┐   ┌──────────────────────────┐
│ Jupiter Aggregator   │   │  ~/.xstocks/cap.json     │
│ (DEX router on       │   │  daily-cap ledger        │
│  Solana mainnet)     │   │                          │
└──────────────────────┘   └──────────────────────────┘

Pricing

| Component | $5 buy | $1,000 buy | |---|---|---| | Stock notional | $5.00 | $1,000.00 | | Jupiter / pool spread | ~0% (built into AMM curve) | ~0.1-0.5% (depends on liquidity) | | Solana network gas | ~$0.001 | ~$0.001 | | LemonCake fee (flat) | $0.10 | $0.10 | | User pays | ~$5.10 | ~$1,000.60 |

Industry-leading: lower than Dinari ($0.20 + 0.50%), much lower than Coinbase / Robinhood spreads.

Sibling MCPs (same team, composable patterns)

| MCP | What it does | |---|---| | agent-payment-mcp | USDC for any HTTP API (Tavily, Hunter, NTA, gBizINFO) | | alpaca-guard-mcp | Daily-cap guard for traditional Alpaca brokerage | | tokenized-stock-mcp | Dinari dShares (centralized, regulated US BD wrapper) | | xstocks-mcp (this one) | Fully on-chain Solana DEX path — no partnership, no KYB wait |

Four different agent-spending vectors, one consistent KYA-style cap model.

Status & roadmap

| Phase | Status | Notes | | ----- | ------ | ----- | | Phase A: local-ledger guard + Jupiter swap + dry-run default | ✅ this release | | | Phase B: LemonCake-managed wallet (USDC charged to LemonCake → on-chain swap) | ⏳ | Replaces user-provided wallet with multi-tenant hot wallet | | Phase C: Multi-source (xStocks + Backed bAssets + Ondo) | ⏳ | Provider abstraction | | Phase D: Anthropic Connectors Directory submission | ⏳ | |

License

MIT. Source at github.com/evidai/lemon-cake/tree/main/xstocks-mcp.

Backed Finance — the regulated issuer
Jupiter — the DEX aggregator we route through
xStocks Risk Disclosure (Kraken)
LemonCake — interactive playground & docs