polymarket-analyst_github/REAL_MONEY_ROADMAP.md

# 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.