polymarket-analyst_github/REAL_MONEY_ROADMAP.md

Real Money Enablement Roadmap

This app is currently paper trading only. The Live Money tab and /api/live endpoint are readiness scaffolding: they make the required product and backend interfaces visible without moving funds or placing orders.

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 order intents only as dry-runs and returns an audit event.
• /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 Live Money tab shows launch checks, wallet/deposit settings, agent risk limits, provider webhook URLs, a dry-run order console, and an audit preview.

The app still refuses to place live orders. That is intentional until the legal, provider, wallet-signing, reconciliation, and monitoring steps below are done.

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.