Demo

Run the framework
locally.

The demo proves five complete flows: paid data procurement, payee drift defense, governed paper trading, provenance lookup, and accounting export with blocked live execution.

Quick run

Install and run in under five minutes.

Full demo run 
pnpm install
pnpm typecheck
pnpm test
pnpm dev:api
pnpm demo:paid-data
pnpm demo:paper-trade
pnpm demo:provenance
What each command proves
  • → paid-data: procurement wallet + mock x402
  • → payee-drift: route quarantine on mismatch
  • → paper-trade: risk check + paper execution
  • → provenance: artifact chain lookup
  • → accounting-export: journal records
Snapshot mode

Fastest path to a running demo.

Snapshot mode persists state to a local file. No Docker required. Ideal for running the demo and exploring the flows without infrastructure setup.

Start the API in snapshot mode 
# Start API with snapshot storage
SOVEREIGN_STORAGE_DRIVER=snapshot \
API_PORT=3002 \
node --import tsx/esm apps/api/src/index.ts

# Then seed and run demos
pnpm demo:seed
pnpm demo:paid-data
pnpm demo:payee-drift
pnpm demo:paper-trade
Postgres mode

Durable runtime validation.

Postgres mode is used for integration tests and durable state. Requires Docker. This is the mode used by the full test suite.

Start with Postgres 
# Bring up 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 in Postgres mode
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
Demo scripts

What each script demonstrates.

pnpm demo:paid-data
Shows paid data procurement and artifact creation.
Agent submits EconomicIntent → procurement wallet evaluates → mock x402 → DataArtifact.
pnpm demo:payee-drift
Shows route quarantine when merchant payee changes unexpectedly.
Route fingerprint mismatch → PAYEE_DRIFT_DETECTED → quarantine event recorded.
pnpm demo:paper-trade
Creates a trade plan and executes a governed paper order.
TradePlan → RiskCheck → trading wallet → DecisionPacket → PaperOrder.
pnpm demo:provenance
Returns the provenance chain for a paid data artifact.
GET /v1/provenance/:artifactId → merchant, route, wallet, policy, decision, downstream.
pnpm demo:accounting-export
Exports journal records for settled actions.
GET /v1/accounting/export → CSV with debit/credit entries per settled action.

Need the setup guide?

The quickstart walks through requirements, install, seed, and each demo script.

Quickstart guide → API reference