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, although snapshots already call it. Scheduled routes require CRON_SECRET and server-side Supabase access.

MCP integration

Create a personal token in the app's AI/MCP access dialog. Connect an MCP client to https://<your-app-host>/api/mcp/mcp using Authorization: Bearer <token>. The dialog provides connection details; tokens are shown once, stored as hashes, and revocable.

The server scopes tools to the token owner's accounts. It supports account/holding reads, quotes, price history and indicators, symbol search, transactions, spot trades, and limit orders. Dedicated forex tools open/list/close positions and place/list/cancel pending entry orders. open_crypto_position opens leveraged crypto longs/shorts with mandatory SL/TP, 1–2× leverage, at most 0.5% of free cash in planned stop risk, at most 25% in margin, at least 3:1 planned reward/risk, and a timed exit within six days (72 hours by default). dry_run: true validates without trading. The account may have only one open leveraged position and no pending leveraged entries. The SQL RPC locks the account and saves the brackets/deadline with the position. Apply mcp-crypto-risk.sql before using this tool: it returns an unavailable error if the RPC is missing and never falls back to the legacy fx_open RPC's fixed 30× margin calculation. list_forex_positions reads leveraged positions across markets; status: "closed" returns recent settled positions for realized-loss tracking. Timed and bracket exits depend on the market-check worker running with available market data; they are not guaranteed execution times.

Development reference

Crypto monitoring while your computer is off

.github/workflows/crypto-cloud-monitor.yml calls POST /api/cron/crypto-monitor on GitHub-hosted runners twice per hour. This runs independently of Codex and your PC. GitHub schedules are best-effort and may be delayed or dropped; this is not an exact 30-minute or guaranteed stop-execution service. The existing market-check worker also handles stored brackets and timed exits.

Apply supabase/mcp-crypto-risk.sql, then supabase/crypto-cloud-monitor.sql. Set repository variable CRYPTO_MONITOR_ACCOUNT_ID to the chosen crypto account UUID and CRYPTO_MONITOR_ENABLED to true; the workflow uses the existing CRON_SECRET repository secret. Set the variable to false to stop this workflow, or disable it in GitHub Actions. The global AUTO_TRADE_ENABLED=false server setting blocks new entries while the worker continues checking exits. Turn off the account's legacy AI auto-trading to avoid two bots.

The cloud analyst uses the account owner's Claude API key saved in Poshkan and the app's existing Opus 4.8 model. API usage is billed to that key, separately from any Codex subscription; there is no operator-key fallback. Missing keys/migrations block entries and are reported in the workflow summary. status checks prerequisites without trading, preview analyzes without trading, and run may open a qualifying paper position. No mode forces a test trade.

Only BTC, ETH and SOL leveraged longs/shorts are considered. Closed 15-minute/hourly/daily candles drive the analysis. Server checks enforce 2× leverage, at most 0.5% available-cash planned stop risk, at most 25% cash margin, at least 3:1 planned reward/risk, one leveraged position, mandatory SL/TP and a 72-hour deadline. Existing spot holdings are preserved. The database claims each account's 30-minute scan once and commits the trade receipt with the cash mutation, so retries return the original receipt. Receipts and analysis live in the owner-readable crypto_monitor_runs table. Entry/exit and new actionable failure notices use Poshkan's existing notification center and configured push subscriptions.

Run policy checks with node --experimental-strip-types --test scripts/crypto-monitor-policy.test.mjs.

Useful commands:

npm run dev          # Development server
npx tsc --noEmit      # Type check
npm run lint         # ESLint
npm run build        # Production build
npm start            # Serve a completed production build

Before shipping, run the type check and production build and browser-check public pages. Do not delete .next while a dev server is running. For Next.js changes, read the relevant guide in node_modules/next/dist/docs/; this repository uses Next.js 16 conventions.

See AGENTS.md for contribution rules and docs/ROADMAP.md for planned work. DESIGN.md and docs/OVERVIEW.md provide historical context and may describe earlier versions; current behavior is defined by the code.