Docs

Three steps put the layer between your agent and the chain. Then a few things worth knowing. The long version lives in the repo: getting started, tools, errors.

1. Install

Pick one. Both give you a single solos binary with Bun embedded.

$ npm i -g @solos-sh/cli
$ curl -fsSL https://raw.githubusercontent.com/GuiBibeau/solos/main/install.sh | sh

macOS (Apple silicon, Intel) and Linux (x64, arm64).

2. Connect a wallet

$ solos login

Asks two things and saves a profile in ~/.config/solos: which wallet (a Solana CLI keypair on this machine, Privy, or a pay account) and which RPC URL. There is no default endpoint. The free tiers at Helius, QuickNode and Triton all work. SOLANA_RPC_URL in the environment always wins.

3. Connect your agent

$ solos connect claude    # Claude Code
$ solos connect codex     # Codex CLI
$ solos connect cursor    # Cursor

Writes the solos mcp serve entry into the client config, keeps a backup, and ends with the solos doctor report. Restart the client and ask: what is my SOL balance?

Any other client: solos doctor prints the entry to paste. --print shows it without writing.

4. First calls

The server starts with three tools: search, wallet balance, portfolio. When the agent needs more, it searches and the matching tools appear. The CLI shows the same thing.

$ solos mcp list
$ solos mcp call solana_wallet_get_balance --args '{}'
$ solos mcp call solana_swap_get_quote --args '{"inputMint":"So111...","outputMint":"EPjF...","amount":"10000000"}'

Two optional keys: JUPITER_API_KEY for prices and swap quotes, ELFA_API_KEY for market research. Without them the tools still list and fail with a reason and a remedy.

5. The ceiling

By default the server offers read and simulate tools only. A simulate tool builds the real transaction and sends only a simulation request. Nothing lands on chain. Execute tools do not exist until you raise the ceiling:

$ solos connect claude --tier execute

Every execute tool has a simulate twin, and execution simulates first unless the caller opts out. solOS has no spending policy of its own. If you run the execute tier in an unattended loop, size the wallet for it. --tier read goes the other way.

The CLI

Every command prints JSON and exits non-zero on a domain error with { code, reason, remedy }. solos --help lists every group.

$ solos wallet balance
$ solos swap quote --input-mint So111... --output-mint EPjF... --amount 10000000
$ solos swap simulate --input-mint So111... --output-mint EPjF... --amount 10000000
$ solos lend reserve --mint EPjF...
$ solos perp position --market SOL-PERP
$ solos portfolio state --owner <owner>

When something is missing

$ solos doctor

Reports every problem at once with a reason and a remedy: no signer, no RPC URL, two signers set. It never prints a secret. Logs are JSON on stderr; SOLOS_LOG_LEVEL=debug turns them up.

From source

$ git clone https://github.com/GuiBibeau/solos && cd solos
$ bun install
$ bun run solos login
$ bun run solos mcp list

Bun 1.3 or later. AGENTS.md is the contributor guide.

How it's built

• A thin layer, no policy. Tools in, transactions out. Bounds and approvals live in the harness you run it in. The Operator sets one boundary: the tier ceiling.
• Ports and adapters. Core slices hold the tools and use cases and do no I/O. Adapters for Kit, Jupiter, Kamino, Orca, Raydium, Meteora, Pump and Phoenix live behind ports.
• Venues draft, Submission sends. A venue builds instructions and never signs. One path seals, simulates, guards and delivers every transaction. Simulation never carries a real signature.
• Discovery is just in time. Tools are registered but withheld until the agent asks. The signer is the secret, not the tool list.
• Plain JavaScript, Effect, Zod, Bun. Tests run on Surfpool, an offline mainnet fork. Live rounds are separate and recorded.

Every decision has a record in the ADRs.