CI-tested `examples/` directory (Stellar-first)

[truthixify]

Labels: Stellar Wave, stellar, dx, docs, drips, help-wanted
Tier: L (1–2 weeks)
Type: dx / docs

Context

Today, a developer who wants to see a complete Wraith integration has to:

1. Read the getting-started.mdx snippets,
2. Read the stellar-quickstart.mdx snippets (if issue docs/01 has landed),
3. Look at the demo source for a real wiring.

That's three different mental contexts. We want a self-contained examples/ directory in the SDK repo with complete, runnable, CI-tested sample apps.

Scope

Create sdk/examples/ with subdirectories, starting Stellar-first:

1. examples/stellar-cli-send/

   • Node CLI script: node send.mjs <recipient-meta-address> <amount>
   • ~50 LOC including imports and error handling.

2. examples/stellar-cli-scan/

   • Node CLI script: node scan.mjs <viewing-key>
   • Prints any incoming payments to stdout.

3. examples/stellar-react-receive/

   • Minimal Vite + React app that connects Freighter, derives keys, scans, lists matches.
   • ~150 LOC.

4. examples/stellar-spectre-agent/

   • Shows how to use the agent client to create a Stellar agent and chat with it.

5. examples/multichain-scan/

   • Scans EVM, Stellar, and Solana in parallel using the chain-conformance API.

Each example:

• Has its own package.json with explicit dep on the local SDK build.
• Has a README.md with prerequisites + run command.
• Is CI-tested — a workflow installs deps, runs the example against testnet (or a recorded RPC fixture), asserts on stdout.
• Has a .env.example for any required config.

Tests

• For CLI examples: snapshot stdout against an expected output.
• For browser examples: build verification + Playwright headless smoke test (lands in tests/examples/).

Acceptance criteria

• Five examples committed and runnable.
• Each one CI-tested.
• Top-level examples/README.md indexing them with one-liners.
• Linked from docs/getting-started.mdx.

Why this matters

"Read the docs" is the second-worst onboarding instruction. "Read the code" is the third-worst. "Run this example, then read the code" is the first-best.

[KevinMB0220]

@KevinMB0220 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi, I’m Kevin a full-stack and smart contract engineer building on Stellar. I specialize in designing and shipping scalable, secure systems end-to-end, from Soroban smart contracts to production-ready backend infrastructure and user-facing applications.

I’ve worked on complex architectures involving automated agents, cross-chain logic, and data indexing, focusing on reliability, performance, and clean standards. My approach is very product-driven: I don’t just build contracts, I build complete systems that solve real user problems and can scale in production.

I’m especially interested in infrastructure, security, and automation creating tools and frameworks that make it easier for other developers to build safely and efficiently on Stellar.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @KevinMB0220 to this issue.

[drips-wave]

Congratulations, @KevinMB0220! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @KevinMB0220: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊