Poshkan Paper Trading

Poshkan — Paper Trading

Practice trading US stocks, ETFs, crypto, and forex with virtual money. Poshkan combines paper accounts, research beside each trade, performance tracking, and a Strategy Lab for building and testing your own trading rules.

All balances, trades, and returns are simulated. The app uses market data to price paper trades.

Live app: www.poshkan.com.

Features

• Accounts for each market — independent portfolios, configurable virtual starting cash, watchlists, and cash adjustments.
• Beginner onboarding — create a paper account, research a company, make a paper trade, and review the decision in History. Account/trade completion is automatic; research and review are self-confirmed, with progress saved per user in the current browser. Strategy Lab lives under Advanced in dashboard navigation.
• Spot and leveraged trading — stock/crypto market and limit orders, plus leveraged long/short positions across all three markets with per-trade leverage and stop-loss/take-profit. Forex covers seven major pairs, pending entry orders, scaled exits, and timed auto-close. Pending orders support DAY/GTC time in force.
• Research before buying — company fundamentals, historical price context, charts, news, stock discovery, and a crypto market map. Public research pages, market scans, trading explainers, and calculators are available without an account.
• Performance and leaderboard — realized/unrealized P&L, allocation, account-value history, transaction history, and account rankings by percentage return with activity and drawdown stats.
• Strategy Lab — combine entry rules, choose symbols and timeframes, define stops/targets and holding limits, then backtest against completed candles with estimated trading costs. Backtested strategies can run live paper alerts; custom strategies currently do not place trades.
• Optional AI tools — an AI Scanner with custom instructions, optional automatic paper trading within account risk limits, and position analysis, using each user's own Anthropic API key. Keys are encrypted before storage.
• Notifications and mobile access — in-app notifications, Web Push, email alerts, a weekly digest endpoint, and an installable PWA with light/dark themes.
• Claude/MCP access — personal tokens let compatible MCP clients inspect accounts and market data, place spot trades, and manage forex positions and pending orders.

The old SMC, OTE, trend, mean-reversion, and candle-range scanner switches have been retired. Their strategy explainers remain as educational content; the current tools are user-built strategies and the AI Scanner.

Stack and architecture

Quotes are Yahoo-first: a batched request resolves multiple symbols, with Twelve Data filling unresolved quotes when configured. Quotes are cached in memory and in the shared market_quotes table. Candles are Twelve Data-first when configured, with Yahoo fallback; Yahoo also supplies discovery and news. The app can run on Yahoo alone, without a market-data key. Historical coverage and quote freshness depend on the provider and available cache.

Trade actions obtain prices on the server. Postgres RPCs validate balances and update trading state atomically; pending-order execution uses a status = 'pending' claim. The leveraged position engine is shared by stocks, crypto, and forex, despite its fx_* database names.

Local setup

1. Install dependencies

Use Node.js 20.9 or newer, npm, and a Supabase project.

git clone https://github.com/afrazja/poshkan-v2.git

cd poshkan-v2 npm ci

2. Configure the environment

Copy .env.local.example to .env.local and replace the placeholders. For PowerShell:

Copy-Item .env.local.example .env.local

Optional settings can be added to .env.local; the example file contains only the basic setup:

Generate an encryption key locally with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Keep .env.local private. Only variables intended for the browser should use NEXT_PUBLIC_; service-role, cron, encryption, provider, and private push keys must stay server-side. AI features use keys saved by users in the app; there is no shared operator Anthropic-key fallback. The AI Scanner currently also requires the user to have a push subscription.

3. Apply the database scripts

SQL lives in supabase/ and is applied manually through the Supabase SQL editor. There is no automatic migration step in npm run dev or npm run build.

For a fresh database, apply this base sequence in order (each name is a .sql file):

schema → orders → upgrades → forex → forex-sltp → orders-tif

→ leaderboard → hardening → mcp → push-journal → ai-limits → login-stats → market-quotes → leaderboard-stats

Then apply the remaining scripts in the order below, left to right within each row:

The legacy scanner tables are included because scanner-position-cap.sql and per-trade-leverage.sql alter them and add fields used by current features. Applying those scripts without the legacy tables can fail. On an existing database, inspect what has already been applied and the prerequisites in each file before running outstanding scripts. Some optional features hide or show an unavailable state until their migrations are present.

4. Configure authentication

Enable email/password authentication with email confirmation in Supabase. Set the Supabase Auth Site URL to your app origin and allow the following local redirect URLs, plus the equivalent URLs for each deployed origin:

http://localhost:3000/auth/confirm

http://localhost:3000/auth/callback http://localhost:3000/auth/reset

The email-confirmation handler expects token_hash and type query parameters. Configure the confirmation email link to target /auth/confirm, for example:

<a href="{{ .RedirectTo }}?token_hash={{ .TokenHash }}&type=email">Confirm your email</a>

The signup form supplies /auth/confirm as RedirectTo. Google sign-in uses the separate /auth/callback route to exchange the authorization code; password recovery uses /auth/reset.

For Google sign-in, apply google-auth.sql, configure a Google OAuth web client with your app origins, and register the Supabase provider callback as its authorized redirect URI:

https://YOUR-PROJECT-REF.supabase.co/auth/v1/callback

Add the Google client ID and secret to the Supabase Google provider and enable it. The Google provider callback and the app's /auth/callback are different steps of the same flow.

5. Start the app

npm run dev

Open localhost:3000, create an account, and create a paper portfolio. Background scans, order monitoring, and daily history require the scheduled jobs below.

Scheduled jobs and deployment

The project deploys on Vercel from main. Configure the environment variables there and set NEXT_PUBLIC_SITE_URL and Supabase Auth redirects to the deployed origin. Database scripts are applied separately from app deployments.

vercel.json currently schedules two jobs (UTC):

For ongoing order monitoring and strategy scans, configure an external scheduler to call GET /api/cron/scanners every 1–5 minutes, with the header:

Authorization: Bearer <CRON_SECRET>

This endpoint bundles custom-scan, scan-opportunities (AI), and market-check. The two schedules in vercel.json alone do not provide frequent monitoring. The old smc-scan, ote-scan, trend-scan, meanrev-scan, and candlerange-scan routes no longer exist.

/api/cron/weekly-digest is available but is not scheduled in vercel.json; add a weekly external schedule if email digests are wanted. /api/cron/daily-scans can also be invoked separately, alt