# Real Money Enablement Roadmap This public app is currently paper trading only. The public site hides live trading controls. The `/personal` route opens a private cockpit for your own wallet, your own money, manual approval, and audit logging. ## What is configured now - `.env.example` lists the environment variables the production app needs. - `/api/live` reports which live-money providers are configured or missing. - `/api/live` accepts public order intents only as dry-runs and returns an audit event. Personal-mode intents are staged for manual review, not executed. - `/api/live?action=tickets` and `/api/live` ticket actions store non-custodial manual trade tickets. These tickets contain the market, side, amount, limit, rationale, Polymarket link, and review instructions, but never a private key or signed order. - `/api/live` manual-fill actions record trades that you placed yourself on Polymarket, then update tracked real positions and P&L. These records are for reconciliation only: Poly Arena still does not sign or submit the trade. - `/api/live` personal-capital actions track money you control outside Poly Arena and bookkeeping allocations to agent return streams. This is not a deposit system, custody account, public investment product, or order router. - `/api/accounts` creates, logs into, and saves password-backed paper accounts through Vercel Blob storage. - `/api/config` exposes safe public provider configuration, including the Sentry browser DSN and Clerk publishable key once configured. - `/api/live` now checks the selected provider stack: Clerk, Neon, Veriff, Circle, and Sentry. - `/api/webhooks/clerk`, `/api/webhooks/veriff`, and `/api/webhooks/circle` receive provider events and store them in Neon. - `/api/provider-events` reports provider event counts for a quick health check. - `/api/policies` exposes the active policy/readiness state. - `/api/consent` records versioned user consent after approved versions are configured. - `/api/risk-profile` stores wallet, jurisdiction, allocation, and agent permission settings server-side. - `/api/incident` records incident events and can notify the configured incident webhook after `RISK_ADMIN_TOKEN` is set. - The public site hides the live-money tab. `/personal` shows wallet/deposit settings, personal risk limits, provider webhook URLs, a manual intent console, and an audit preview. The app still refuses to place live orders. Personal mode stages manual intents only until your own deposit wallet, CLOB credentials, and tiny test flow are ready. ## Personal-use path Personal mode is narrower than the public business launch: - Your own money only. - Your own Polymarket/deposit wallet only. - No outside investors, deposits, pooled funds, or copy-trading customers. - No unattended agent trading. - Every live trade starts as a staged manual intent and must be reviewed before you do anything in Polymarket. - Trade execution happens outside Poly Arena through your own Polymarket wallet or UI. Poly Arena remains the analyst/ticketing layer. - Personal agent shares are allocation notes for your own tracking only. They do not represent pooled investor shares, securities, or money held by Poly Arena. - After you manually trade, record the actual shares, price, fees, and note in Poly Arena so the personal cockpit can track real position value and P&L. - Public `LIVE_TRADING_ENABLED` stays `false`. Personal mode still needs: - `DEPOSIT_WALLET_ADDRESS` - `POLYMARKET_SIGNATURE_TYPE=3` - `POLYMARKET_CLOB_API_KEY` - `POLYMARKET_CLOB_SECRET` - `POLYMARKET_CLOB_PASSPHRASE` - `RISK_ADMIN_TOKEN` - `PERSONAL_TRADING_ENABLED=true` only after your own tiny manual test flow ## Required before live deposits or trading 1. Legal and eligibility - Terms, risk disclosures, privacy policy, and jurisdiction policy. - KYC / KYB provider. - Age, location, sanctions, and restricted-market checks. - Market category policy for elections, sports, finance, crypto, geopolitical events, manipulated markets, disputed markets, and restricted outcomes. - Record of user consent to every active terms, privacy, and risk-disclosure version. 2. Account and wallet - Real authentication for live-money users. - Production account database. The current backend account API is enough for paper portfolios, but live money should use a real database with admin, audit, and compliance tooling. - Password reset, sign-out, session expiry, and optional MFA path. - Non-custodial wallet connection or Polymarket deposit-wallet flow. - User-controlled permissions for each agent. - Revocation path so a user can stop agent trading immediately. 3. Funds - Deposit provider. - Withdrawal provider. - Payment webhooks and failure handling. - Balance reconciliation, statements, support, and accounting exports. - Withdrawal review rules for fraud, sanctions, chargeback, and settlement edge cases. 4. Execution - Backend order router. - Polymarket CLOB API credentials. - EIP-712 order-signing flow. - Order placement, cancellation, fill tracking, and position reconciliation. - Idempotency keys, retry policy, rate limits, and stale-order protection. - Server-side enforcement of user permissions and risk limits. 5. Risk and controls - Per-agent max allocation. - Per-market max position size. - Category exclusions. - Manual approval mode. - Emergency pause and cancel-all. - Always-available withdrawal path. - Admin kill switch. - Market blacklist and category exclusion controls. 6. Audit and monitoring - Durable append-only audit log. - Signal, approval, order, fill, cancellation, deposit, and withdrawal events. - Admin monitoring and incident response. - Error tracking, uptime monitoring, webhook monitoring, and alert routing. - Customer support process and data retention policy. 7. Testing and launch operations - Paper-to-live parity tests. - Test wallets and dry-run order intents. - KYC, payments, wallet, CLOB, and webhook integration tests. - Reconciliation tests for partial fills, cancellations, market resolution, withdrawals, failed deposits, and duplicate webhooks. - Rollback plan and incident response drill. ## Environment variables expected by `/api/live` Copy `.env.example` into your local environment for development, then add the same variables in Vercel Project Settings -> Environment Variables for production. - `KYC_PROVIDER` - `KYC_API_KEY` - `KYC_WEBHOOK_SECRET` - `SANCTIONS_PROVIDER` - `SANCTIONS_API_KEY` - `GEOIP_PROVIDER` - `GEOIP_API_KEY` - `RESTRICTED_JURISDICTIONS` - `TERMS_VERSION` - `PRIVACY_VERSION` - `RISK_DISCLOSURE_VERSION` - `MARKET_POLICY_STORE` - `AUTH_PROVIDER` - `DATABASE_URL` - `SESSION_SECRET` - `ENCRYPTION_KEY` - `PAYMENTS_PROVIDER` - `PAYMENTS_API_KEY` - `PAYMENTS_WEBHOOK_SECRET` - `WEBHOOK_BASE_URL` - `WALLET_PROVIDER` - `WALLET_PROJECT_ID` - `WALLET_API_KEY` - `DEPOSIT_WALLET_ADDRESS` - `POLYMARKET_SIGNATURE_TYPE=3` - `POLYMARKET_CHAIN_ID=137` - `SETTLEMENT_ASSET=pUSD` - `SETTLEMENT_CHAIN=polygon` - `POLYMARKET_CLOB_API_KEY` - `POLYMARKET_CLOB_SECRET` - `POLYMARKET_CLOB_PASSPHRASE` - `RECONCILIATION_STORE` - `ACCOUNTING_EXPORT_STORE` - `RATE_LIMIT_STORE` - `AUDIT_LOG_STORE` - `MONITORING_DSN` - `INCIDENT_WEBHOOK_URL` - `ADMIN_ALERT_EMAIL` - `CUSTOMER_SUPPORT_EMAIL` - `LIVE_TRADING_ENABLED=true` only after final approval and end-to-end testing Even when all variables are present, live order placement remains intentionally unimplemented until wallet signing, compliance approval, and safe order routing are completed. ## Polymarket integration notes Polymarket's public docs describe trading as non-custodial. Orders are signed and matched through the CLOB, and new API users generally use the deposit-wallet flow with signature type `3`. Useful official docs: - Trading overview: https://docs.polymarket.com/trading/overview - Trading quickstart: https://docs.polymarket.com/trading/quickstart - Deposit wallets: https://docs.polymarket.com/trading/deposit-wallets ## Final setup checklist 1. Choose and contract the KYC / eligibility provider. 2. Choose and contract the sanctions/watchlist and geo-IP/geofencing providers. 3. Choose the deposit and withdrawal provider. 4. Choose the wallet or embedded-wallet provider and create a deposit wallet. 5. Build production accounts: auth, sessions, password reset, sign-out, account database, consent records, and portfolio history storage. 6. Derive or create Polymarket CLOB credentials for the approved signing flow. 7. Build the live order router with signing, submission, cancellation, fill tracking, idempotency, rate limits, and stale-order protection. 8. Build continuous reconciliation for cash, open orders, fills, positions, withdrawals, fees, and resolved markets. 9. Enforce every user permission and risk limit on the server, not only in the browser. 10. Create durable append-only audit storage, statements, exports, monitoring, alerting, and support procedures. 11. Complete legal review, terms, privacy policy, risk disclosures, restricted jurisdiction rules, market category policy, and incident response plan. 12. Add all environment variables in Vercel. 13. Run dry-runs and test-wallet trades; verify webhooks, audit events, reconciliation, and user withdrawal paths. 14. Only then set `LIVE_TRADING_ENABLED=true`. ## What still cannot be completed from code alone - Legal approval and jurisdiction-specific advice. - KYC/KYB, sanctions, payments, wallet, and support vendor contracts. - Real provider API keys, webhook secrets, CLOB credentials, and deposit wallet addresses. - Bank, stablecoin, or payment settlement relationships. - Production security review and incident-response ownership. - Final decision to enable live trading.