Quickstart

Build the contracts, run the test suite, and stand up a demo wallet on Stellar testnet.

Prerequisites

stellar-cli

Rust toolchain + the wasm32v1-none target for building Soroban contracts.

Bun 1.3+

Package manager, native TypeScript runtime, and test runner — no Node/npm needed for development.

1. Build and test the contracts

Rust

stellar contract build
cargo test --workspace

This compiles contracts/example-vault (the canonical demo contract) and contracts/agent-policy (the generalized policy signer), then runs their unit tests — 17 tests total (11 for agent-policy, 6 for example-vault), entirely offline.

2. Install and typecheck the TypeScript layer

Bun

bun install
bun run typecheck
bun test

bun test runs the fast unit suite (40 tests across 6 files, zero network calls, well under a second) covering every hand-rolled Soroban XDR encoder, the MCP arg-filling heuristic, and stellar agentgate init’s flag parsing.

Bare bun test also discovers test/e2e/*.e2e.test.ts if run without a path argument — that’s the test:all script’s job. The scoped, fast command is bun run test (→ bun test test/unit).

3. Stand up a demo wallet on testnet

Bootstrap

bun run reset-demo

This single command:

1. Generates fresh identities

   A local owner (admin) key and an agent-signer (machine/agent) key, both funded via friendbot.

2. Deploys three fresh contracts

   example-vault, agent-policy, and a passkey-kit smart wallet instance, all on Stellar testnet.

3. Wires the policy gate

   Adds agent-signer and agent-policy as wallet signers, configures the allow-list (deposit uncapped, withdraw capped at 1000/24h), then restricts agent-signer to require agent-policy as a co-signer.

4. Writes .env

   Every ID and secret the other scripts and the MCP server need — gitignored, never committed.

4. Watch the policy gate in action

Scripted demo

bun run demo

Runs the exact allow/reject sequence this documentation describes, against the wallet reset-demo just deployed:

-> deposit(wallet, 2000) -- allowed, uncapped
   ALLOWED  tx=...

-> withdraw(wallet, 100) -- allowed, within 1000 window cap
   ALLOWED  tx=...

-> withdraw(wallet, 950) -- REJECTED: 100+950=1050 exceeds 1000 window cap
   REJECTED  re-simulation failed: HostError: Error(Auth, InvalidAction)

-> touch(wallet) -- REJECTED: method not on the allow-list
   REJECTED  re-simulation failed: HostError: Error(Auth, InvalidAction)

5. Run it as an MCP server

stellar-agentgate is published on npm — no clone required to install it:

From npm

npm install -g stellar-agentgate

stellar-cli discovers stellar-agentgate on PATH and runs it as a native subcommand — there is no stellar plugin install; installation is entirely this package’s responsibility, exactly like any other stellar-<name> plugin.

Next: understand the architecture

See exactly how a natural-language request becomes an on-chain decision.

Wire up your own wallet

Everything above uses a disposable demo wallet — stellar agentgate init does the same wiring against your own.