Epic: Improve Agent UX for Wallets

[aristidesstaffieri]

Context

The Agentic Wallet CLI Spec describes how to help an AI agent hold funds, trade, and pay for x402/MPP services on Stellar. Today the CLI lacks first-class wallet primitives and protocol discoverability: agents must hand-assemble contract invoke calls, scrape human-formatted output, and have no guided path to popular Soroban protocols.

This epic closes that gap with the smallest possible net-new surface: two new commands (stellar token, stellar checkout), a relayer integration, CLI-wide structured output/errors, and a skills package that composes existing commands.

Goals (priority order)

1. New commands — add stellar token and stellar checkout to the CLI.
2. Skills to discover protocols available on the network.
3. Relayer integration — make transaction sponsorship seamless
4. Knowledge pushed outward — the "wallet" is a skills package over existing commands; only the token client and the x402 client are new binary surface.

Tasks

Phase 1 — token client + first skill path

• stellar token: typed SEP-41 + SAC client #2620 — stellar token: typed SEP-41 + SAC client
• Wallet skills package (stellar-wallet-skills) #2624 — Wallet skills package (stellar-wallet-skills)
• DeFi skill: Blend playbook #2625 — DeFi skill: Blend playbook

Phase 2 — checkout + remaining DeFi skills

• stellar checkout: x402 / MPP client #2621 — stellar checkout: x402 / MPP client
• DeFi skill: Aquarius playbook #2626 — DeFi skill: Aquarius playbook
• DeFi skill: DefiIndex playbook #2627 — DeFi skill: DefiIndex playbook

Phase 3 — CLI API hardening

• Structured output & CLI API hardening (output + errors + --describe) #2622 — Structured output & CLI API hardening (output + errors + --describe)

Phase 4 — relayer

• Relayer integration for transaction submission #2623 — Relayer integration

[tupui]

Are these going to be separate binaries or included in the API? I think these things should be modules you add, i.e. a different binary stellar-checkout. This way you keep a lean CLI and you show how everyone can compose and build on top of the CLI. (You could even have a page with pluggins from the community, instructions on how to add yours, etc. [EDIT] thanks Zac for pointing out that page.)

[zachfedor]

Yeah, these new binaries seem like perfect use cases for the plugin system that already exists: https://developers.stellar.org/docs/tools/cli/plugins-list

[aristidesstaffieri]

@tupui @zachfedor we considered adding these as external plugins but ultimately decided they would be a better fit as new commands in the main cli binary for a few reasons:

1. Plugins are child processes, in order to inherit the transaction construction pipeline the new token command would have to import the soroban_cli library anyway and rebuild the pipeline in it's own process.
2. A token client and x402 client add no new dependencies, one wraps existing functionality with a new interface and the other uses the existing http stack. Relative to the existing 43 commands and decisions to include other heavy deps(the docker client, key ring, full tokio, etc) the cost of this addition in terms of the binary are minimal.
3. The token client and x402 payment primitives aren't experimental or non-standard features. One key goal of this effort is to lower the barrier for agents to use the cli as a wallet and interact with the network with the lowest friction possible and these features were a common theme when we surveyed agent usage of the cli.

Let me know if none of this changes your mind and we can continue to consider this before we start the work.

[tupui]

I am mostly thinking in terms of API design and what service it provides. The token command refers to something "fundamental" so ok, but checkout is less obvious and more adjacent to me. (Not even considering the fact that IMHO it's too early to calls either of these 2 standards because things are moving fast.)

I hear you though on the discoverability even though this could be solved with a skill as you are doing for the other DeFi protocol. If checkout gets in, that opens the door to more adjacent things to me and it's less clear what the API scope should be. (Saying this as someone who is maintaining SciPy which does way too many things and has plagged us for years.)

Ultimately your call, I am just sharing some thoughts.

[oceans404]

I agree that token belongs in the CLI

I think @tupui's point of checkout as a plugin is fair. The current blocker for going the plugin route is that plugins don't currently have keyring access, which checkout would need for onchain signing leg. If we went the plugin route, we'd have to do a key management extraction first and make that the opening step of Phase 2 before building the command. Worth discussing whether that's the right tradeoff.

[tupui]

The keyring is actually a great point and might be a worthy consideration if we wanted external plugins to support this. Though I suppose this would be hard to support any kind of plugin, eg if I do a Python executable (not impossible as I could do some lower level calls, even use Maturin, etc.)

[aristidesstaffieri]

@oceans404 @tupui yeah it seems like there could be a different line work here to pull out some of the internals into another package to make it more approachable to use for plugins. @oceans404 we could consider blocking the checkout command on that work in case it seems like a better fit for a plugin given that change.

[tupui]

I mean, you could also do this later depending on your prios. We can keep a consistent public API, and I don't think there would be many users really relying on the internals if you do the change in a few months.

[oceans404]

I did some digging into what checkout would need to exist as a plugin rather than being built in to the cli. I identified 4 primitives we'd need to add to the cli to support this here: https://github.com/oceans404/cli-plugin-checkout Would love any feedback or notes if I missed anything!