Run it locally

Run the frontend on its own in mock mode, or the full stack against BNB Chain.

Frontend only (mock mode)

Mock mode keeps every screen working in the browser with sample data. Sign-in is still real Privy, but nothing is signed or sent.

bash

cd sama-frontend
pnpm install
cp .env.example .env.local   # set NEXT_PUBLIC_PRIVY_APP_ID, keep NEXT_PUBLIC_SAMA_API_MODE=mock
pnpm dev                     # http://localhost:3200

Full stack

bash

# 1. Shared packages
cd sama-packages && bun install

# 2. API on :3300
cd ../sama-backend
bun install
cp .env.example .env         # PRIVY_*, BINANCE_WEB3_*, SESSION_SECRET, BSC_RPC_URL, VERIFIER_RPC_URL
bun run dev                  # http://localhost:3300/api/health

# 3. Frontend in live mode
cd ../sama-frontend
# .env.local: NEXT_PUBLIC_SAMA_API_MODE=live, NEXT_PUBLIC_SAMA_API_URL=http://localhost:3300
pnpm dev

Environment

Variable	Purpose
`SAMA_CHAIN_ID`, `SAMA_ENABLE_MAINNET`	56 or 97; mainnet must be switched on explicitly
`SAMA_SETTLEMENT_ADDRESS`	Override the recorded deployment
`BSC_RPC_URL`, `VERIFIER_RPC_URL`	Executor RPC, and a different provider with archive state for the verifier
`PRIVY_APP_ID`, `PRIVY_APP_SECRET`	Verify sign-in tokens
`BINANCE_WEB3_API_KEY`, `BINANCE_WEB3_API_SECRET`	Stock prices
`DATABASE_URL`, `SAMA_PGLITE_DIR`	Postgres, or PGlite for local work
`SESSION_SECRET`, `SAMA_ALLOWED_ORIGINS`, `SAMA_APP_ORIGIN`, `SAMA_CROSS_SITE_COOKIE`	Sessions and CORS
`SAMA_MAX_PLAN_USD`, `SAMA_SWAP_SLIPPAGE_BPS`	Plan value cap (500) and leftover swap slippage (50)
`SAMA_CRON_INTERVAL_SEC`	How often the background loop runs
`ANTHROPIC_API_KEY`, `GROQ_API_KEY`	Optional, for describing a target in words

Tests

bash

cd sama-packages && bun test        # matcher, reference matcher, settlement, verifier, …
cd sama-backend && bun test         # offline API tests (fake prices, in-memory PGlite)
SAMA_FORK=1 bun test test/e2e.fork.test.ts   # a full round on a BSC mainnet fork
cd sama-contract && forge test
cd sama-frontend && pnpm typecheck