A Stellar wallet for AI agents, built by AI agents: autonomous transactions inside rules you define, approvals you grant, and an audit trail you can verify.
Stellar Agent Wallet is a community experiment. AI agents write most of the code, a maintainer reviews every pull request, and anyone who works with agents on Stellar can contribute. Soneso maintains the project under GOVERNANCE.md.
stellar-agent-wallet lets an AI agent transact on Stellar under guardrails. It
ships two surfaces over one shared core: the stellar-agent CLI, which also runs
as stellar agent inside the Stellar CLI, and the stellar-agent-mcp MCP stdio
server. Both sit on a policy engine, an operator-approval spine, and a
tamper-evident hash-chained audit log, so an autonomous agent can act while a
human keeps control of what it is allowed to do.
The architecture shows the trust boundaries, payment flow,
and key custody.
New to the project? What is the Stellar Agent Wallet? is the non-technical tour: what it is, what an agent can do with it, and how a first session with Claude Code looks.
Public alpha, under active development. The milestones list the planned work per release.
- testnet (
stellar:testnet) is the default network: a command with no named profile and nodefault.tomlruns on the zero-config testnet profile. - mainnet (
stellar:mainnet) is read-only in this alpha. Every write or signing command refuses a mainnet profile, and the submit layer refuses a mainnet endpoint after asking it which network it serves. Mainnet is refused for writes lists the commands, the layers, and the wire codes. - Friendbot funding is testnet/futurenet only; mainnet is structurally refused.
Release archives are published on the releases page for each tagged release, and the workspace crates are published to crates.io with each release (features merged since the last tag ship from source until the next one).
- Payments and assets: send payments, check balances, manage trustlines, and claim claimable balances on Stellar.
- DeFi: swap tokens on Soroswap, and deposit into or withdraw from DeFindex vaults.
- Smart accounts: deploy and govern OpenZeppelin smart accounts with WebAuthn passkey signers. Delegate to an agent that holds its own key, within scoped rules and spending limits the contract enforces.
- SEP protocols: the wallet exposes SEP-6, SEP-7, SEP-24, SEP-43, SEP-47, SEP-48, and SEP-53 for anchor flows, payment URIs, wallet signing, message signing, and contract interfaces. SEP-10 serves the x402 identity gate; SEP-45 is library-only and has no CLI command or MCP tool.
- Machine payments: pay as an x402 client, and authorize Machine Payments Protocol (MPP) sponsored charges on testnet.
- Operator control: approve or reject pending agent actions from a terminal or a web inbox, enroll passkeys for the approval inboxes, install signed toolsets, and sign with a Ledger device.
Concepts explains the policy engine, approval spine, audit log, and toolset model. Agent payments with MPP documents the supported MPP flow, its trust boundary, the CLI commands, and the five MCP tools. Protocols and integrations details the SEPs, x402, and the DeFi venues.
Give your coding agent AGENTS.md; it tells the agent where to
start. Issues labeled
agent-ready
state Where and Acceptance as commands. They list Gates only for checks beyond
bash .github/scripts/preflight.sh. Claim an unassigned
good first issue
or
help wanted
by commenting "I'll take this". Merged pull requests get release-note credit.
CONTRIBUTING.md has a starter
prompt for your agent and describes the review path, and questions and ideas go
to Discussions.
Each tagged release publishes prebuilt archives on the
releases page and the
crates on crates.io. While only prerelease (alpha) versions exist,
cargo install and cargo binstall need the version spelled out, because a
bare crate name matches stable versions only.
cargo binstall downloads the prebuilt release archive for your platform:
cargo binstall --locked --disable-strategies quick-install,compile stellar-agent-cli@0.1.0-alpha.13 stellar-agent-mcp@0.1.0-alpha.13cargo install builds both binaries from the sources on crates.io:
cargo install --locked stellar-agent-cli@0.1.0-alpha.13 stellar-agent-mcp@0.1.0-alpha.13Clone the release tag and build with its committed Cargo.lock:
git clone --branch v0.1.0-alpha.13 https://github.com/Soneso/stellar-agent-wallet.git
cd stellar-agent-wallet
cargo build --release --lockedThe CLI is also discoverable as stellar agent ... through the stellar-cli
external-binary plugin convention when stellar-agent is on your PATH.
Install covers the direct download with its checksum check, the Windows PowerShell steps, and the macOS Gatekeeper note. Verifying releases shows how to check an archive against its checksums, its cosign signature, and its SLSA provenance.
Generate and fund an account, check its balances, and send a payment. These commands take an explicit account on the flags and need no profile.
Generate a fresh testnet keypair and fund it from Friendbot in one step:
stellar-agent accounts create --generate --fund-with-friendbotThe JSON output carries the new G-strkey and its secret (data.secret_key).
Save the printed secret; the payment in this quickstart reads it. The command
output holds the seed, so do not write it to a log or a shared terminal.
Read the new account's XLM and trustline balances:
stellar-agent balances --account GABC...WXYZThe payment reads the seed from WALLET_SK. Run this line on its own, paste
the saved secret when prompted, and press Enter:
printf 'WALLET_SK seed: ' && read -rs WALLET_SK && echo && export WALLET_SKSend a payment (the asset is positional and defaults to native), then
remove the seed from the shell:
stellar-agent pay GDEST...WXYZ "10 XLM" --source GABC...WXYZ --secret-env WALLET_SK
unset WALLET_SKPass a secret seed covers PowerShell and the cleanup of a seed typed into a command line.
By default, commands print one JSON envelope on stdout and exit 0 on success
or 1 on any error. stellar-agent profile init creates a persistent profile,
which policies and MCP signing need, as
Set up a profile describes.
See docs/getting-started.md for the full walkthrough and docs/cli-reference/index.md for every command, flag, and output shape.
stellar-agent-mcp is an MCP server spoken over stdio. Point an MCP client at
the binary:
stellar-agent-mcpThe server exposes payments, DeFi, SEP protocols, x402, MPP, smart-account rules, transaction status, and toolsets. Payment handlers use the shared policy, approval, and audit libraries. See the MCP reference for configuration and tool calls.
- Documentation for users: getting started, concepts, architecture, the CLI and MCP references, protocols, toolsets, profiles, and remote approval.
- Documentation for maintainers: architecture, building and testing, security internals, and the review checklist.
An Agent Skill that teaches an AI agent how to operate
the wallet (CLI and MCP) without cloning this repository ships in
skills/. Install it manually from
skills/stellar-agent-wallet.zip or, in Claude
Code, via the marketplace:
/plugin marketplace add Soneso/stellar-agent-wallet
/plugin install stellar-agent-wallet@soneso-stellar-agent-walletThis is distinct from the wallet's built-in
toolsets feature (signed, capability-restricting packages
the wallet enforces at runtime), demonstrated in
examples/toolsets/.
See SECURITY.md for the supported versions and how to report a vulnerability.
Apache-2.0. See LICENSE.
"Stellar" is a trademark of the Stellar Development Foundation. This is an independent project, not affiliated with, sponsored or endorsed by the Stellar Development Foundation.