Quickstart

This guide walks through installing the framework, starting the API, seeding demo data, and running each demo script end-to-end.

Requirements

• Node.js 20+ (LTS recommended)
• pnpm 9+ (npm install -g pnpm)
• Docker (only for Postgres mode)
• Git

Install

Clone the repository and install dependencies.

git clone https://github.com/ntwrkd-labs/sovereign-wallet-os
cd sovereign-wallet-os
pnpm install

Verify the TypeScript types compile correctly:

pnpm typecheck

Snapshot mode

Snapshot mode is the fastest way to run the local demo. State is persisted to a local file. No Docker required.

SOVEREIGN_STORAGE_DRIVER=snapshot \
API_PORT=3002 \
node --import tsx/esm apps/api/src/index.ts

The API is now available at http://localhost:3002.

Postgres mode

For durable runtime validation and integration tests, use Postgres mode.

# Start Postgres
docker compose down -v
docker compose up -d postgres

# Run migrations
DATABASE_URL=postgres://sovereign:sovereign@127.0.0.1:5432/sovereign \
pnpm db:migrate

# Start API
SOVEREIGN_STORAGE_DRIVER=postgres \
DATABASE_URL=postgres://sovereign:sovereign@127.0.0.1:5432/sovereign \
API_PORT=3003 \
node --import tsx/esm apps/api/src/index.ts

Seed the demo

Seed creates the demo wallets, merchants, routes, and agent identities. Run once after starting the API.

curl -X POST http://localhost:3002/v1/demo/seed
# or
pnpm demo:seed

Run paid data demo

The paid data demo shows a full procurement flow: EconomicIntent → constitution evaluation → mock x402 payment → DataArtifact creation.

pnpm demo:paid-data

Run paper trade demo

Creates a trade plan from paid data, runs a deterministic risk check, and requests paper execution through the trading wallet.

pnpm demo:paper-trade

Inspect provenance

Returns the full provenance chain for the data artifact created in the paid data demo.

pnpm demo:provenance
# or
curl http://localhost:3002/v1/provenance/:artifactId

Export accounting

Exports journal records for all settled economic actions in the demo session.

pnpm demo:accounting-export
# or
curl http://localhost:3002/v1/accounting/export

Run the full test suite

pnpm typecheck
pnpm test
pnpm test:integration
pnpm test:postgres    # requires Docker