Getting started

Quickstart

Run the full stack locally — the hyperscaled-api backend plus this vanta-starter frontend — in about ten minutes.

What you'll need

Python 3.11+, Node 20+ with pnpm, Docker Desktop, and the Stripe CLI (only for testing payments/payouts locally).

1. Start Postgres & Redis

The API persists tenants, users, and payments in Postgres and uses Redis for caching/rate-limits.

hyperscaled-api

# from the hyperscaled-api repo root
docker compose up -d        # Postgres (5433) + Redis (6379)
docker compose ps

Port 5433, not 5432

The compose file maps Postgres to host port 5433 to avoid colliding with a native Postgres on 5432. Make sure V2_DATABASE_URL points at 5433.

2. Configure & migrate the API

hyperscaled-api

conda activate hyperscaled        # or your venv
pip install -e .

cp .env.example .env              # then fill in the values below
alembic upgrade head              # create all tables

hyperscaled-api/.env (essentials)

V2_DATABASE_URL=postgresql+asyncpg://hyperscaled:hyperscaled@localhost:5433/hyperscaled_api
V2_REDIS_URL=redis://localhost:6379/0
# 64 hex chars = a 32-byte AES-256-GCM key. Generate with:
#   python -c "import secrets; print(secrets.token_hex(32))"   (or: openssl rand -hex 32)
# base64 will NOT work: the API boots fine and then 500s on the first encrypt.
SESSION_ENCRYPTION_KEY=<64 hex chars>

# Stripe (test mode)
V2_STRIPE_SECRET_KEY=sk_test_...
V2_STRIPE_PUBLISHABLE_KEY=pk_test_...
# Comma-separated: a Connect platform needs a second Stripe endpoint (and
# secret) for connected-account events. All configured secrets are tried.
V2_STRIPE_WEBHOOK_SECRET=whsec_account,whsec_connect

# Sumsub KYC
V2_SUMSUB_APP_TOKEN=...
V2_SUMSUB_SECRET_KEY=...

# Email OTP (SMTP relay)
V2_SMTP_HOST=smtp-relay.gmail.com
V2_SMTP_USERNAME=...
V2_SMTP_PASSWORD=...

# Validator / trading network
HYPERSCALED_VALIDATOR_API_KEY=...

3. Run the API

hyperscaled-api

uvicorn hyperscaled_api.main:app --reload --port 8000

The interactive API reference (Swagger UI) is now live at http://localhost:8000/docs.

4. Create an admin + register your app (tenant)

Each app that integrates is a tenant with its own OAuth client credentials. Create them from the admin dashboard — no production terminal required.

hyperscaled-api

# Create the first admin. Run from the hyperscaled-api repo root.
# The password is prompted for interactively (hidden, 12 chars minimum) —
# do not pass it on the command line or in an env var.
python scripts/create_admin.py --email you@taoshi.io --name "You"

# Alternatively, for local auto-seed: set V2_ADMIN_EMAIL and V2_ADMIN_PASSWORD
# (optionally V2_ADMIN_NAME) before starting uvicorn. The API seeds a superadmin
# on startup only when both are set and the admins table is empty. Settings use
# env_prefix="V2_", so unprefixed ADMIN_EMAIL / ADMIN_PASSWORD do nothing.

# Sign in, enroll TOTP (forced on first login), then "Register app"
open http://localhost:8000/admin/login

Save the client secret

Registering an app returns a client_id and a client_secret shown once. Copy them into the frontend env below.

Give the operator your Connect return URLs

Stripe sends your users back to your site after Connect onboarding, so the return and refresh URLs are stored per tenant on your app row — they are not an API-wide setting. When you register the app, set both to this app's payouts page:
connect_return_url = <your-origin>/dashboard/payouts?onboarding=return
connect_refresh_url = <your-origin>/dashboard/payouts?onboarding=refresh
An operator sets them in the admin console or via PATCH /v2/admin/apps/{app_id}. Until they are set, POST /v2/connect/accounts returns 409 V2_CONNECT_URLS_NOT_CONFIGURED and no user can link a bank account.

5. Configure & run this app

vanta-starter/.env.local

HSC_API_BASE_URL=http://localhost:8000
HSC_CLIENT_ID=hsc_...
HSC_CLIENT_SECRET=hsk_...
HSC_SCOPE=api

SESSION_COOKIE_NAME=hsc_starter_session
SESSION_COOKIE_SECRET=<32+ char secret>

NEXT_PUBLIC_HSC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

vanta-starter

pnpm install
pnpm dev          # http://localhost:3000

6. (Optional) Forward Stripe webhooks

Payments and Connect status updates arrive via webhook. Forward them to the API while developing.

terminal

# use --api-key so the CLI listens on the SAME Stripe account as your keys
stripe listen \
  --api-key sk_test_... \
  --forward-to localhost:8000/v2/webhooks/stripe

# copy the whsec_... it prints into V2_STRIPE_WEBHOOK_SECRET, then restart uvicorn

Restart after changing .env

uvicorn --reload does not reload environment variables. Restart the process after editing .env.

Next steps

Authentication — how tokens and sessions work.
Identity / KYC — verify a trader.
Checkout — sell your first challenge.