Back to home
Documentation
Complete reference for the Solobank SDK, CLI, and MCP server — everything you need to give AI agents a bank account on Solana.
Architecture
@solobank/mcp→@solobank/cli→@solobank/sdk→@solobank/mpp-solana→mppx
SDK integrates: Solana web3.js · SPL Token · Jupiter · Kamino · marginfi
Quickstart
Up and running in 30 seconds.
npm i -g @solobank/cli
solobank init
solobank balance
Using with Claude / Cursor
Add to your MCP config:
{
"mcpServers": {
"solobank": {
"command": "npx",
"args": ["-y", "@solobank/mcp"]
}
}
}
Using as a library
npm i @solobank/sdk
import { Solobank } from "@solobank/sdk";
const agent = await Solobank.create();
const balance = await agent.balance();
await agent.send({ amount: 10, to: "9pFr...2kLx" });
await agent.lend({ asset: "USDC", amount: 80 });
await agent.swap({ fromAsset: "USDC", toAsset: "SOL", amount: 50 });
CLI Reference
@solobank/cli — 14 commands wrapping the SDK. Binary: solobank.
solobank init--forceGenerate a new Solana Ed25519 keypair and save it to ~/.config/solobank/id.json.
$ solobank init
solobank addressPrint the wallet's base58 public key.
$ solobank address
solobank balanceShow SOL and USDC balances for the current wallet.
$ solobank balance
solobank send <amount> <to>--asset <SOL|USDC|USDT|JUP>Transfer SOL or SPL tokens to any Solana address. Defaults to USDC.
$ solobank send 10 9pFr...2kLx --asset USDC
solobank pay <url>--method --data --max-pricePay an MPP-protected HTTP endpoint. Handles 402 negotiation automatically.
$ solobank pay https://api.example.com/data --method POST --data '{"q":"hello"}'
solobank swap-quote <amount> <from> <to>--slippage-bps <50>Get a Jupiter swap quote without executing.
$ solobank swap-quote 100 USDC SOL
solobank swap <amount> <from> <to>--slippage-bps <50>Execute a token swap via Jupiter best route.
$ solobank swap 100 USDC SOL
solobank lend-rates <asset>--protocol <auto|kamino|marginfi>List current lending APYs across Kamino and marginfi.
$ solobank lend-rates USDC
solobank lend <amount> <asset>--protocolDeposit to the best lending venue. Auto-routes to highest APY.
$ solobank lend 80 USDC
solobank borrow <amount> <asset>--protocol --market --bank --reserveBorrow against deposited collateral.
$ solobank borrow 20 USDC --protocol kamino
solobank withdraw <amount> <asset>--protocol --market --bank --reserve --allWithdraw from a lending position. Use --all for full withdrawal.
$ solobank withdraw 50 USDC --all
solobank repay <amount> <asset>--protocol --market --bank --reserve --allRepay an outstanding borrow position. Use --all to clear debt.
$ solobank repay 20 USDC --all
solobank rebalance <amount> <asset>--protocol --target-protocol --min-apy-deltaMove funds from one lending venue to a higher-APY venue.
$ solobank rebalance 80 USDC --min-apy-delta 0.5
solobank mcpPrint MCP stdio configuration JSON for Claude / Cursor integration.
$ solobank mcp
SDK Reference
@solobank/sdk — full TypeScript SDK. Exports: ".", "./browser", "./adapters".
Wallet
| Method | Returns | Description |
|---|---|---|
| Solobank.init(options?) | Promise<{address, keypairPath, rpcUrl}> | Generate a new keypair and save to disk. Options: { configDir?, force?, rpcUrl?, keypairPath? }. |
| Solobank.create(options?) | Promise<Solobank> | Load existing wallet or create if createIfMissing: true. |
| Solobank.load(options?) | Promise<Solobank> | Alias for create(). |
| Solobank.fromSecretKey(key, opts?) | Solobank | Instantiate from raw secret key (Uint8Array, base64, or JSON array). |
| .address() | string | Returns the wallet's base58 public key. |
| .balance() | Promise<BalanceSnapshot> | SOL + USDC balances with raw bigint values. |
Transfers
| Method | Returns | Description |
|---|---|---|
| .send(options) | Promise<SendResult> | Transfer SOL or SPL tokens. Options: { amount, to, asset?, mint?, dryRun? }. |
| .pay(options) | Promise<PayResult> | Pay an MPP endpoint. Options: { url, method?, headers?, body?, maxPrice? }. |
Swaps
| Method | Returns | Description |
|---|---|---|
| .getSwapQuote(options) | Promise<SwapQuoteResult> | Get Jupiter quote. Options: { fromAsset, toAsset, amount, slippageBps?, swapMode?, onlyDirectRoutes? }. |
| .swap(options) | Promise<SwapExecutionResult> | Execute Jupiter swap. Returns quote fields + signature + explorerUrl. |
Lending
| Method | Returns | Description |
|---|---|---|
| .getLendingRates(options) | Promise<LendingRate[]> | APYs across Kamino + marginfi. Options: { asset, protocol? }. |
| .lend(options) | Promise<LendResult> | Deposit to best venue. Options: { asset, amount, protocol?, dryRun? }. |
| .borrow(options) | Promise<LendingActionResult> | Borrow from lending protocol. Options: { asset, amount, protocol?, marketAddress?, bankAddress?, reserveAddress?, dryRun? }. |
| .withdraw(options) | Promise<LendingActionResult> | Withdraw from position. Options: { asset, amount, withdrawAll?, protocol?, dryRun? }. |
| .repay(options) | Promise<LendingActionResult> | Repay a borrow. Options: { asset, amount, repayAll?, protocol?, dryRun? }. |
| .rebalance(options) | Promise<RebalanceResult> | Move funds to higher-APY venue. Options: { asset, amount, targetProtocol?, minApyDelta?, dryRun? }. |
Key Types
interface BalanceSnapshot {
address: string;
sol: number; solRaw: bigint;
usdc: number; usdcRaw: bigint;
rpcUrl: string;
}
interface SendOptions {
amount: number;
to: string;
asset?: "SOL" | "USDC" | "USDT" | "JUP";
mint?: string; // custom mint address
dryRun?: boolean;
}
interface PayOptions {
url: string;
method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
headers?: Record<string, string>;
body?: unknown;
maxPrice?: number;
}
interface SwapQuoteOptions {
fromAsset: string;
toAsset: string;
amount: number;
slippageBps?: number; // default 50
swapMode?: "ExactIn" | "ExactOut";
onlyDirectRoutes?: boolean;
}
interface SwapExecutionResult extends SwapQuoteResult {
signature: string;
explorerUrl: string;
}
interface LendOptions {
asset: string;
amount: number;
protocol?: "auto" | "kamino" | "marginfi";
dryRun?: boolean;
}
interface BorrowOptions {
asset: string;
amount: number;
protocol?: "auto" | "kamino" | "marginfi";
marketAddress?: string;
bankAddress?: string; // marginfi
reserveAddress?: string; // Kamino
dryRun?: boolean;
}
interface WithdrawOptions extends BorrowOptions {
withdrawAll?: boolean;
}
interface RepayOptions extends BorrowOptions {
repayAll?: boolean;
}
interface RebalanceOptions extends BorrowOptions {
targetProtocol?: "auto" | "kamino" | "marginfi";
minApyDelta?: number;
}
interface RebalanceResult {
status: "rebalanced" | "skipped";
asset: string; amount: number;
from: LendingRate; to: LendingRate;
apyDelta: number;
withdrawSignature?: string;
lendSignature?: string;
}
Browser Client
Lightweight MPP client for wallet-adapter integration:
import { createBrowserClient } from "@solobank/sdk/browser";
const client = createBrowserClient({
connection,
signer: walletAdapter, // { publicKey, signTransaction }
});
const response = await client.pay({ url, maxPrice: 0.01 });
Utility Functions
| Function | Description |
|---|---|
| resolveAsset(input) | Resolve asset symbol or mint to { symbol, mint, decimals } |
| truncateAddress(addr, prefix?, suffix?) | Truncate address: 7xKp...3mNq |
| formatUsd(amount) | Format number as $1,234.56 |
| formatAssetAmount(amount, asset) | Format with asset-specific decimals |
| formatPercent(value, digits?) | Format as percentage string |
| walletExists(configDir?, keypairPath?) | Check if wallet file exists on disk |
| keypairFromPrivateKey(key) | Parse base64, JSON array, or Uint8Array to Keypair |
MCP Server
@solobank/mcp — Model Context Protocol server for Claude, Cursor, Windsurf, and other MCP-compatible AI platforms.
Tools
solobank_addressnoneReturns the current Solana wallet address.
solobank_balancenoneReturns wallet balance snapshot — SOL + USDC with raw values.
solobank_sendto, amount, asset?, dryRun?Send SOL or SPL tokens. Validates address format. Enforces per-tx spending cap (maxAmountPerTx, default 1.0).
solobank_payurl, method?, body?, maxPrice?, headers?Pay an MPP-protected HTTP endpoint. Handles 402 negotiation. Blocks internal/private network URLs.
Programmatic Usage
import { startMcpServer, createMcpServer } from "@solobank/mcp";
// Start with stdio transport:
await startMcpServer({ rpcUrl: "https://..." });
// Or get server instance for custom transport:
const server = await createMcpServer({
agent: myAgent,
maxAmountPerTx: 5.0, // spending cap per call (default 1.0)
});
Payments
@solobank/mpp-solana — Solana USDC payment method for the Machine Payments Protocol (MPP). Handles 402 negotiation, multi-account transfers, and on-chain verification.
Client (payer)
import { solanaClient } from "@solobank/mpp-solana/client";
const handler = solanaClient({
connection,
signer, // { publicKey, signTransaction }
commitment: "confirmed",
});
Server (verifier)
import { solanaServer } from "@solobank/mpp-solana/server";
const handler = solanaServer({
recipient: "Abcd...wxyz",
rpcUrl: "https://...",
commitment: "finalized", // default
tryConsumeReference: async (sig) => {
// atomic check-and-mark (e.g. Redis SETNX)
return redis.set(sig, "1", "NX");
},
});
Utility Functions
| Function | Description |
|---|---|
| fetchTokenAccounts(conn, owner, mint) | Fetch SPL token accounts sorted by balance |
| buildTransferPlan(accounts, amount) | Greedy multi-account spend plan |
| sumReceivedTokenAmount(pre, post, mint, owner) | Compute token delta for verification |
| parseAmountToRaw(amount, decimals) | Convert decimal string to bigint (e.g. "1.50" → 1500000n) |
Constants
SOLANA_USDC_MINT: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDC_DECIMALS: 6
Environment Variables
Optional configuration via environment variables.
| Variable | Default | Description |
|---|---|---|
| SOLOBANK_CONFIG_DIR | ~/.config/solobank | Wallet config directory. |
| SOLOBANK_KEYPAIR_PATH | id.json | Keypair filename within config dir. |
| SOLOBANK_RPC_URL | devnet RPC | Solana RPC endpoint. |
| SOLOBANK_JUP_BASE_URL | https://lite-api.jup.ag | Jupiter API base URL. |
| SOLOBANK_JUP_API_KEY | none | Jupiter Pro API key for higher rate limits. |