Skip to main content

Frequently Asked Questions (FAQ)

Common questions and answers about PolyOracle AI.

General Questions​

What is PolyOracle AI?​

PolyOracle AI is an intelligent trading agent that analyzes Polymarket prediction markets using advanced AI research and makes informed trading decisions. It combines web research, market analysis, and machine learning to identify trading opportunities.

Is PolyOracle AI free to use?​

The software is open source and free to use. However, you'll need:

  • API keys for OpenAI, Exa, and other services (paid usage)
  • USDC for trading on Polymarket
  • Small amounts of MATIC for transaction fees

How much money do I need to start?​

Minimum recommended: $100-500 USDC for testing Comfortable starting amount: $1000-2000 USDC Also need: ~$10 worth of MATIC for gas fees

Start small while you learn the system and gain confidence in the AI's decisions.

Is automated trading safe?​

Automated trading carries risks:

  • ✅ Pros: Removes emotion, 24/7 monitoring, consistent strategy
  • ⚠️ Risks: Technical failures, market volatility, AI errors
  • Recommendation: Start with human approval required, small positions

Technical Questions​

What programming knowledge do I need?​

Basic Usage: None - use the web interface Advanced Usage: Python basics for customization Development: Python + TypeScript for core modifications

Which operating systems are supported?​

  • macOS: Fully supported ✅
  • Linux: Fully supported ✅
  • Windows: Supported via WSL2 ⚡

Can I run this on a VPS or cloud server?​

Yes, PolyOracle AI works well on cloud servers:

  • Recommended: 2+ CPU cores, 4GB+ RAM
  • Popular choices: AWS, DigitalOcean, Google Cloud
  • Benefits: 24/7 operation, stable connectivity

Trading Questions​

How does the AI make trading decisions?​

The AI follows a structured process:

  1. Research: Deep web search on market topics
  2. Analysis: Technical analysis of orderbook/liquidity
  3. Synthesis: Combines fundamental + technical analysis
  4. Decision: BUY/SELL/NO_TRADE with confidence score
  5. Risk Check: Validates against risk management rules

What markets can I trade?​

PolyOracle AI works with Polymarket's binary prediction markets:

  • Politics: Elections, policy outcomes
  • Economics: Market predictions, inflation, etc.
  • Sports: Game outcomes, season winners
  • Crypto: Price predictions, adoption milestones
  • Current Events: News outcomes, social trends

How accurate are the predictions?​

Accuracy varies by market type and conditions:

  • High-confidence trades (over 0.8): ~70-80% win rate typical
  • Medium-confidence (0.6-0.8): ~60-70% win rate
  • Market dependent: Politics often more predictable than sports

Past performance doesn't guarantee future results.

Can I customize the trading strategy?​

Yes, many aspects are configurable:

  • Risk limits: Position sizes, total exposure
  • Confidence thresholds: Minimum confidence for trades
  • Research depth: How thorough the analysis should be
  • Market filters: Which types of markets to consider
  • Position sizing: Fixed, confidence-based, or Kelly criterion

Setup Questions​

Which API keys are absolutely required?​

Essential for basic functionality:

  • OpenAI API Key (for AI analysis)
  • Exa API Key (for research)
  • Polymarket API Key + Secret (for trading)
  • Polygon wallet private key (for transactions)

Optional but recommended:

  • Anthropic (backup LLM)
  • LangChain (monitoring/debugging)

How do I get a Polymarket API key?​

  1. Create account at polymarket.com
  2. Connect your Web3 wallet
  3. Navigate to Account Settings → API
  4. Generate API key and secret
  5. Create proxy contract (required for trading)

What's a proxy contract and why do I need it?​

A proxy contract allows the AI to trade on your behalf without directly controlling your wallet. It's required by Polymarket for API trading and adds a security layer.

How to create:

  1. Visit polymarket.com with your trading wallet
  2. Attempt to place any trade (triggers proxy creation)
  3. Approve the proxy contract transaction
  4. Copy the proxy address for your configuration

Security Questions​

Is it safe to give the AI my private key?​

Security measures:

  • Use a dedicated trading wallet (not your main wallet)
  • Store private key in .env file (not in code)
  • Set file permissions: chmod 600 .env
  • Never commit .env to version control

Best practice: Create a separate wallet just for trading with limited funds.

What if my API keys are compromised?​

Immediate actions:

  1. Rotate all API keys immediately
  2. Check recent trading activity
  3. Monitor wallet transactions
  4. Enable 2FA on all accounts
  5. Review access logs

Prevention:

  • Regular key rotation (monthly for high usage)
  • Monitor API usage dashboards
  • Use separate keys for different environments

Can the AI lose all my money?​

Risk management features:

  • Position size limits (configurable)
  • Maximum total exposure limits
  • Confidence thresholds
  • Stop-loss functionality
  • Human approval requirements (optional)

Additional protection:

  • Start with small amounts
  • Use paper trading first
  • Monitor performance closely
  • Set conservative risk limits

Performance Questions​

Why is analysis taking so long?​

Common causes:

  • High research depth setting
  • Poor internet connectivity
  • API rate limiting
  • Complex market topics

Solutions:

  • Reduce research depth temporarily
  • Check network connection
  • Verify API quotas
  • Use cached research when available

How can I improve trading performance?​

Analysis improvements:

  • Focus on liquid markets (over $10K volume)
  • Increase confidence threshold for trades
  • Specialize in certain market categories
  • Use longer research depth for larger positions

Risk management:

  • Diversify across market types
  • Use proper position sizing
  • Set stop-losses consistently
  • Review and adjust parameters regularly

What's a good win rate to expect?​

Realistic expectations:

  • Beginner: 55-60% win rate with proper risk management
  • Experienced: 65-75% with optimized settings
  • Expert: 70-80% with specialized focus areas

More important metrics:

  • Risk-adjusted returns (Sharpe ratio)
  • Maximum drawdown
  • Profit factor (avg win / avg loss)

Troubleshooting Questions​

The backend won't start - what do I do?​

Check in order:

  1. Python version: python --version (need 3.11+)
  2. Dependencies: pip list | grep langgraph
  3. Environment variables: Check .env file exists
  4. Port availability: Try different port if 2024 is used
  5. Logs: Look for specific error messages

My trades aren't executing - why?​

Common issues:

  • Insufficient USDC balance
  • Missing MATIC for gas fees
  • Proxy contract not configured
  • Market moved significantly since analysis
  • Order size exceeds limits

Debug steps:

  1. Check wallet balances
  2. Verify proxy address in config
  3. Test with smaller order size
  4. Check current market prices

The AI is making bad decisions - how do I fix it?​

Adjustment strategies:

  • Increase confidence threshold (only trade over 0.8)
  • Focus on market categories you understand
  • Reduce position sizes while learning
  • Enable human approval for all trades
  • Analyze losing trades for patterns

Remember: No system is perfect. Focus on long-term performance and risk management.

Cost Questions​

How much do the API calls cost?​

Typical monthly costs (100 analyses):

  • OpenAI: $20-50 (depending on model usage)
  • Exa: $10-30 (depending on research depth)
  • Other APIs: $5-15

Cost optimization:

  • Use GPT-4o-mini for simpler tasks
  • Reduce research depth for smaller trades
  • Cache frequently used research
  • Monitor usage dashboards

What are the trading costs?​

Polymarket fees:

  • Trading fee: ~0.1-0.2% per trade
  • No withdrawal fees for on-chain assets

Blockchain costs:

  • Gas fees: $0.01-0.10 per transaction (Polygon)
  • Bridge fees: If moving funds to Polygon

Is there a way to paper trade first?​

Yes! Enable paper trading mode:

# In configuration
paper_trading = {
    "enabled": True,
    "starting_balance": 1000,
    "track_performance": True
}

This simulates trades without real money while tracking would-be performance.

Integration Questions​

Can I integrate with TradingView?​

Currently not directly supported, but you can:

  • Export trade signals to CSV
  • Use webhooks to send signals to TradingView
  • Build custom integration using the API

Does it work with other exchanges?​

Currently designed specifically for Polymarket. The architecture could be adapted for other prediction markets, but would require development work.

Can multiple people use the same instance?​

The current setup is designed for single-user operation. Multi-user support would require:

  • User authentication system
  • Separate wallet management
  • Portfolio isolation
  • Additional security measures

Still Have Questions?​

Documentation: Check other sections of this guide GitHub Issues: For technical problems or feature requests
Community Discord: For real-time help and discussion Email Support: For sensitive security-related questions

When asking for help, include:

  • Operating system and version
  • Python/Node.js versions
  • Error messages (with API keys redacted)
  • Steps to reproduce the issue