Stellar Agent Wallet

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.

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.

Status

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 no default.toml runs 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).

Highlights

• 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 supports SEP-6, SEP-7, SEP-10, SEP-24, SEP-43,
  SEP-45, SEP-47, SEP-48, and SEP-53. They cover anchor flows, payment URIs,
  web authentication, wallet signing, message signing, and contract interfaces.
• 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.

Contribute with your agent

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.

Install

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 (prebuilt binaries)

cargo binstall downloads the prebuilt release archive for your platform:

cargo binstall --locked --disable-strategies quick-install,compile [email protected] [email protected]

cargo install (from crates.io)

cargo install builds both binaries from the sources on crates.io:

cargo install --locked [email protected] [email protected]

Build from source

Clone the release tag and build with its committed Cargo.lock:

git clone --branch v0.1.0-alpha.12 https://github.com/Soneso/stellar-agent-wallet.git
cd stellar-agent-wallet
cargo build --release --locked

The 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.

60-second quickstart

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-friendbot

The 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...WXYZ

The 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_SK

Send 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_SK

Pass 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.

Running the MCP server

stellar-agent-mcp is an MCP server spoken over stdio. Point an MCP client at
the binary:

stellar-agent-mcp

The server registers its tool families (payments, DeFi, SEP protocols, toolsets)
behind the same policy engine, approval spine, and audit log as the CLI. See
docs/mcp.md for client configuration and the tool catalogue.

Documentation

• Documentation for users: getting started,
  concepts, the CLI and MCP references, protocols, toolsets, profiles, and
  remote approval.
• Documentation for maintainers:
  architecture, building and testing, security internals, and the review
  checklist.

Agent skill

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-wallet

This is distinct from the wallet's built-in
toolsets feature (signed, capability-restricting packages
the wallet enforces at runtime), demonstrated in
examples/toolsets/.

Security

See SECURITY.md for the supported versions and how to report a
vulnerability.

License

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.