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
`BSC_WS_URL`	Optional websocket RPC for realtime transfer logs; polling runs either way
`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
`COINGECKO_API_KEY`	Optional CoinGecko Demo key for token pages. Limits are then per key; without it the free per-IP limit applies and `/api/market` can answer 503
`AI_BASE_URL`, `AI_API_KEY`, `AI_MODEL`	Optional, any OpenAI-compatible gateway for the assistant and targets in words
`GROQ_API_KEY`	Optional fallback when `AI_*` is not set; powers both the assistant and targets in words
`ANTHROPIC_API_KEY`	Optional, describing a target in words only. The assistant needs `AI_*` or Groq

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