io.github.kaditang/agent-wallet-mcp
Non-custodial Solana MCP: compare yields, buy tokenized US stocks (xStocks) & Ondo USDY. You sign.
Open source Open in the app JSON README (API)
About
Non-custodial Solana MCP: compare yields, buy tokenized US stocks (xStocks) & Ondo USDY. You sign.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- kaditang
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.1
- Stars
- 3
- Last push
- 2026-09-07T22:33:00Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:18
- Updated
- 2026-08-29 04:00:18
- Origin id
io.github.kaditang/agent-wallet-mcp
README
# agent-wallet-mcp
[](https://opensource.org/licenses/MIT)
[](https://solana.com)
[](https://modelcontextprotocol.io)
[](https://solscan.io/tx/55Agf6Dx1DbBTKC5zYdWi9McAUotBQkEiM6AqrAhKCCKBcGByoryTUMQiJuKDbTK5P46GtDCqG6scPnHRxmJEusD)
> A non-custodial RWA service for AI agents on Solana — yield comparison, tokenized US-equity quotes, and ready-to-sign transactions. Funds stay in your wallet; we never sign.
Connect this MCP server to **Claude**, **Cursor**, **Claude Code**, or any MCP-compatible client. Your AI can then:
- Compare USDC lending yields across Solana, Ethereum, Base, Arbitrum (read-only data).
- Quote and build transactions to buy Backed xStocks (16 tickers — NVDAx, TSLAx, SPYx, QQQx, COINx, …) on Solana.
- Snapshot any wallet's portfolio (SOL, USDC, held xStocks valued live via Jupiter).
- Track transaction confirmations.
You sign every transaction in **your own Phantom (or other Solana wallet)**. We do not custody funds, hold keys, or co-sign. Architecturally we are a *service* — closer to Tradingview than to a wallet.
> **Signals to act on:** pair this with [StockWaves](https://stockwaves.net) — pay-per-call quant signals (equities / crypto / cross-asset macro) over the x402 protocol. StockWaves tells an agent *what* to trade; this server lets it *execute* non-custodially.
## Why this exists
Tokenized US equities (Backed's xStocks, Ondo Global Markets) and on-chain treasury products are the fastest-growing real-world-asset (RWA) category. As of mid-2026 these have real liquidity on Solana — NVDAx, TSLAx, SPYx all carry $300K-$3M each, with ~$5/share trades incurring zero detectable price impact.
Coinbase, Phantom, and Crossmint all offer "agent wallets," but they are generic. None opinionated about RWA discovery, yield aggregation, or the boring-but-correct execution that makes idle USDC actually earn. This server fills that gap, distributed via the AI tool layer.
## Install
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude Desktop on macOS) or your editor's MCP config:
```json
{
"mcpServers": {
"agent-wallet": {
"command": "npx",
"args": ["-y", "@kaditang/agent-wallet-mcp"]
}
}
}
```
> The npm package is **published** as [`@kaditang/agent-wallet-mcp`](https://www.npmjs.com/package/@kaditang/agent-wallet-mcp) (and listed in the official MCP Registry) — the config above runs it directly via `npx`, no clone needed. Requires `@kaditang/agent-wallet-mcp` ≥ 0.2.1 (stdio entry).
>
> To run from source instead (for development), clone this repo and run:
> ```bash
> git clone https://github.com/kaditang/agent-wallet-mcp.git
> cd agent-wallet-mcp && npm install
> cp .env.example .env # then fill in SOL_RPC (api keys are minted via Phantom at /account)
> npm run mcp:http # serves on :3030
> ```
> Then point your MCP client at `http://localhost:3030/mcp` with an `Authorization: Bearer <your-api-key>` header.
### Solana RPC endpoint (recommended)
Public RPCs (`api.mainnet-beta.solana.com`) rate-limit aggressively and reject `getTokenAccountsByOwner` in some cases. For any meaningful traffic you want a paid endpoint as primary; public ones are kept as fallback automatically.
Free tier from [Helius](https://helius.dev) is enough for V1:
1. Sign up → New project → copy the RPC URL (looks like `https://mainnet.helius-rpc.com/?api-key=...`)
2. Set in `.env`:
```
SOL_RPC=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
```
3. (Optional) add a second provider as `SOL_RPC_FALLBACK_1` for redundancy.
The pool tries primary first; on transient failures (429, timeouts, 5xx) it falls through to fallbacks, then to the public mainnet-beta + publicnode endpoints.
### Error monitoring (optional)
Set `SENTRY_DSN` to ship server-side errors to Sentry. Disabled by default; no outbound network when unset. Captures 500s and broadcast failures with sanitized context — request bodies, cookies, headers (which can carry api keys) are stripped before send.
```
SENTRY_DSN=https://<key>@oXXXXXX.ingest.sentry.io/XXXXXX
SENTRY_RELEASE=<git-sha> # optional, for release tracking
```
## Tool surface
| Tool | Purpose | Signs anything? |
|------|---------|-----------------|
| `compare_yields` | Rank USDC lending + tokenized-treasury yields across chains, **risk-adjusted** (volatility / TVL / protocol / stability / reward-dependence), not headline APY. Solana protocols tagged `executable: true`. | No |
| `list_yield_tokens` | List supported tokenized treasuries (USDY by Ondo). | No |
| `list_xstocks` | List supported tokenized US equities (Backed xStocks). | No |
| `check_xstock_safety` | **Pre-trade safety check** for a tokenized US stock (any issuer / mint / EVM address): is it the **real** token (not a copycat) and OK to buy now — verified vs the issuer's own registry, plus depeg / liquidity / market-hours / trading-halt. Catches impersonator tokens (the #1 risk). Free, read-only. Auto-run before `build_buy_xstock_tx`. | No |
| `quote_tokenized_stock` | Live Jupiter quote for USDC → xStock + a **best-entry-timing** signal (premium vs the underlying stock, compared against a same-market-regime baseline — US market open vs closed). | No |
| `get_portfolio` | Snapshot a wallet: SOL, USDC, xStocks + yield tokens valued via Jupiter. | No |
| `portfolio_health` | "Should I do anything?" — holdings vs best risk-adjusted yield + per-xStock timing + actionable notes. | No |
| `suggest_rebalance` | Given a target allocation, compute the buy/sell trades to reach it. Read-only; user executes. | No |
| `export_history` | Export tokenized-equity / yield trade history (date, action, price, CSV) — a record for your accountant, not tax advice. | No |
| `track_tx` | Lookup confirmation status for a Solana signature. | No |
| `build_deposit_yield_tx` | Build unsigned USDC → USDY tx + one-click sign URL. | **No** — user signs in Phantom. |
| `build_withdraw_yield_tx` | Build unsigned USDY → USDC tx + sign URL. | **No** |
| `build_buy_xstock_tx` | Build unsigned USDC → xStock tx + sign URL. | **No** |
| `build_sell_xstock_tx` | Build unsigned xStock → USDC tx + sign URL. | **No** |
## Architecture
```
[Claude / Cursor / Claude Code]
↓ MCP (stdio or HTTP)
[agent-wallet-mcp server]
├─ READ tools (DefiLlama, Jupiter quote, RPC reads)
├─ BUILD tools (Jupiter swap → unsigned VersionedTransaction)
└─ MONITOR tools (RPC signature lookup)
↓ returns tx + signUrl
[user's browser]
↓ Phantom signs + sends
[Solana mainnet]
```
Zero custody, zero signing keys held by the server. The service is pure intelligence + transaction construction.
## Quick example
User to Claude:
> "I have a Solana wallet at `7QCg1LegbEE2eYDJZfgeMX7JhjtFVVZx9su3HzncuSh2`. Buy me 5 USDC of NVDA tokenized."
Claude calls `build_buy_xstock_tx` → receives sign URL → shows it to you. You click, Phantom prompts, you approve. ~0.023 NVDAx lands in your wallet.
## Coverage
| Asset class | V1 | V1.5 | V2 |
|---|---|---|---|
| Backed xStocks (Solana) | ✅ | | |
| USDC lending data (cross-chain) | ✅ | | |
| Solana lending execution (Kamino / MarginFi / JLP) | | ✅ | |
| Ethereum-side RWA execution (BUIDL / OUSG / USDY) | | | ✅ |
| Cross-chain rebalance | | | ✅ |
## Caveats
- **You sign every action.** Auto-execution requires V1.5's optional Squads-spending-limit grant (separately, opt-in).
- **Tokenized equities are issued under non-US prospectuses.** Issuers (Backed, Ondo) restrict US persons. We do not onboard or KYC anyone — that's between you and the issuer.
- **Markets move.** Slippage cap is 0.5% by default; widen it carefully on illiquid pairs.
## Security
This service handles a real-money path. We've documented the full security posture, threat model, audit history, and vulnerability-disclosure process in **[SECURITY.md](./SECURITY.md)** — including a verifiable account of what "non-custodial" means here (i.e., what an attacker who controls our backend cannot do).
If you find a security issue, please [open a private Security Advisory](https://github.com/kaditang/agent-wallet-mcp/security/advisories/new) instead of a public issue. See SECURITY.md for the full disclosure process.
## License
MIT
## Status
**Live on Solana mainnet.** First USDC → Ondo USDY transaction signed via Phantom + broadcast through this service:
[`55Agf6...JEusD`](https://solscan.io/tx/55Agf6Dx1DbBTKC5zYdWi9McAUotBQkEiM6AqrAhKCCKBcGByoryTUMQiJuKDbTK5P46GtDCqG6scPnHRxmJEusD)
Building in public.