OrbitSafe

OrbitSafe is our submission for the Stellar Hacks: Agents hackathon.

It gives an AI agent a governed wallet instead of a free-spending hot wallet. The owner signs a policy first. The agent can then spend only inside that policy. Paid calls leave receipts, blocked calls leave policy decisions, and the dashboard makes both visible in one place.

This repository contains the working judge demo. The demo runs on Stellar testnet on purpose so it can be replayed safely and consistently. The architecture is still aimed at mainnet deployment.

What Judges Should See

If you open the app and run the intended flow, these are the proof points that matter:

• The owner connects Freighter and signs the spending policy.
• The policy defines budget, per-request cap, and allowlist.
• The agent runs paid research and summarize calls over x402.
• If MPP is configured, the agent also runs verify through an MPP session.
• OrbitSafe blocks requests that exceed the cap or fall outside the allowlist before payment moves.
• Paid execution trace shows the rail, amount, payer, network, and receipt or transaction reference.
• Activity ledger records both approved spend and blocked policy decisions.

That is the product claim: not just "agents can pay", but "agents can pay under explicit controls".

Repo Layout

• apps/web: Next.js dashboard
• apps/api: Express API with x402, MPP, policy enforcement, and SQLite state

Demo Modes

OrbitSafe adapts to the rails you configure:

• full: paid x402 research, paid x402 summary, then MPP verify
• x402-only: paid research and summary
• verify-only: MPP verify without x402

For the hackathon, the ideal path is full, but the repo can still demonstrate the core product in x402-only mode.

Local Testnet Setup

1. Install dependencies.

npm install

2. Copy the testnet environment file.

cp .env.example .env

3. Prepare three wallets.

• owner: a Freighter wallet used for browser auth and policy signing
• agent: a backend wallet used as AGENT_WALLET_SECRET
• ops: a backend wallet used as X402_RECEIVER_ACCOUNT and, when needed, MPP_FEE_PAYER_SECRET

4. Fund the testnet wallets.

• Fund agent and ops with testnet XLM
• Add a testnet USDC trustline for both
• Fund testnet USDC through the Circle faucet: https://faucet.circle.com/

5. Fill .env.

Minimum values for an x402 run:

• ORBITSAFE_BOOTSTRAP_OWNER_ADDRESS
• AGENT_WALLET_SECRET
• X402_RECEIVER_ACCOUNT

Additional values for the full MPP path:

• MPP_SECRET_KEY
• MPP_CHANNEL_CONTRACT
• MPP_COMMITMENT_PUBLIC_KEY
• MPP_COMMITMENT_SECRET
• MPP_FEE_PAYER_SECRET

6. Start the app.

npm run dev

• Web: http://localhost:3000
• API: http://localhost:3001

Judge Walkthrough

This is the cleanest way to run the hackathon demo:

1. Connect Freighter with the approved owner wallet.
2. Open the policy and confirm budget, cap, and allowlist.
3. Resume the policy if it is paused.
4. Use Prepare recording to clear spend, receipts, and ledger state.
5. Press Run.
6. Show Run summary.
7. Show Paid execution trace.
8. Show Activity ledger.
9. Trigger Blocked by cap.
10. Trigger Blocked by allowlist.

What the judges should walk away with is simple: OrbitSafe lets an agent pay for tools on Stellar, but only inside rules the owner signed first.

Configuration Reference

x402

• STELLAR_NETWORK_LABEL
• STELLAR_HORIZON_URL
• STELLAR_RPC_URL
• STELLAR_NETWORK_PASSPHRASE
• STELLAR_USDC_ISSUER
• X402_NETWORK
• X402_FACILITATOR_URL
• X402_RECEIVER_ACCOUNT
• AGENT_WALLET_SECRET

MPP

• MPP_NETWORK
• MPP_PRICE_VERIFY_CENTS
• MPP_SECRET_KEY
• MPP_CHANNEL_CONTRACT
• MPP_COMMITMENT_PUBLIC_KEY
• MPP_COMMITMENT_SECRET
• MPP_FEE_PAYER_SECRET

Owner Auth

• ORBITSAFE_DB_PATH
• ORBITSAFE_AUTH_TTL_SECONDS
• ORBITSAFE_BOOTSTRAP_OWNER_ADDRESS

Mainnet Notes

The included demo is testnet-first. For a real mainnet deployment, you will need:

• a real pubnet Soroban RPC provider
• a mainnet facilitator
• funded mainnet XLM accounts
• mainnet USDC trustlines and balances
• a deployed and funded mainnet one-way MPP channel contract

Do not reuse a testnet database for mainnet.

Deployment

For orbitsafe.xyz, the repo includes a simple production stack:

• docker-compose.prod.yml
• deploy/web.Dockerfile
• deploy/api.Dockerfile
• deploy/Caddyfile
• .env.production.example
• SECURITY-LAUNCH-CHECKLIST.md

Minimal deploy sequence:

cp .env.production.example .env
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d

Expected DNS for the included Caddy config:

• orbitsafe.xyz
• www.orbitsafe.xyz
• api.orbitsafe.xyz

The containers use Node 25 because OrbitSafe relies on the built-in node:sqlite driver.

Notes

• The policy engine uses cents internally to avoid float drift.
• The API keeps policy, ledger state, auth challenges, and MPP state in SQLite.
• The public /health route stays intentionally minimal.
• Only the API process should receive payment secrets in production.
• The current deploy profile is single-instance. If you scale horizontally, move state off local disk.