DOCSEARCHbyAlgolia
Submit Docs

PolyTerm

repository·main·Indexed 43 days ago

https://github.com/nytemodeonly/polyterm

A terminal-based tool and TUI for monitoring Polymarket markets. It provides real-time dashboards for order books, trade prints, and market resolution status without requiring private keys. Features include a comprehensive CLI for market analysis, risk assessment, whale tracking, and arbitrage detection, as well as an API layer that aggregates data from Gamma, CLOB, and the Data API.

Tokens
196.9K
Snippets
720
Records
1.2K
Agent score
51%

What's inside PolyTerm

  1. Overview of PolyTerm CLI Commands

    main

    PolyTerm provides a wide range of CLI commands for prediction market analysis, trading, and monitoring. Commands are categorized by their functionality, such as market research, risk assessment, and real-time monitoring. Each command has its own dedicated documentation page for specific usage, options, and examples.

    Key Command Categories:

    • Market Analysis: analyze, arbitrage, calibrate, correlate, ev, risk, sentiment, stats.
    • Monitoring & Alerts: alerts, live-monitor, monitor, pricealert, watchdog, watch.
    • Wallet & Portfolio: mywallet, pnl, portfolio, position, wallets, follow.
    • Research & Data: archive, digest, history, lookup, research, summary.
    • Trading Tools: backtest, exit, fees, orderbook, quicktrade, size, trade.

  2. Overview of PolyTerm TUI Screens

    main

    PolyTerm features a Terminal User Interface (TUI) with various screens for interactive data exploration. Users can navigate between screens using specific keyboard shortcuts.

    Common TUI Navigation Examples:

    • Dashboard: d
    • Market Search/Picker: market_picker (dialog)
    • Help: h or /?
    • Settings: 8/s
    • Live Monitor: 2/l
    • Order Book: 13/ob

    Each screen is designed for a specific task, such as viewing price charts (ch), checking the resolution calendar (cal), or managing saved markets (17/bm).

  3. Use DataAPIClient for wallet data

    main

    The DataAPIClient class provides access to the Polymarket Data API at https://data-api.polymarket.com. It is used to retrieve wallet positions, trading activity, trade history, and profit/loss summaries.

    Important: Data Lag Warning All data retrieved via this client is lagged and is not the live CLOB fill tape. When displaying this data in a CLI, TUI, or JSON output, you must include the labels source=data_api and lag=true (or lagged=true). Do not attempt to estimate or invent a specific lag duration.

    This client replaces the deprecated SubgraphClient for wallet-related data.

    from polyterm.api import DataAPIClient

client = DataAPIClient()
# Use client methods to fetch data
client.close()

  4. Overview of the Database Manager

    main

    The Database class (located in polyterm/db/database.py) provides a SQLite-based persistent local storage system for all PolyTerm data. It manages data for wallets, trades, alerts, market snapshots, bookmarks, positions, and more.

    Key Characteristics

    • Storage Location: By default, the database is stored at ~/.polyterm/data.db. You can override this by passing a db_path to the constructor.
    • Transaction Safety: All operations use a context-managed connection (_get_connection()) that enables foreign keys, performs auto-commits on success, and automatically rolls back on errors.
    • Self-Maintenance:
      • Auto-migration: On initialization, the schema is inspected and updated (e.g., adding the wallet_address column to the positions table if missing).
      • Auto-cleanup: The database runs _auto_cleanup() at startup. If total rows across core tables exceed 10,000, it prunes old snapshots (30 days), acknowledged alerts (7 days), and non-open arbitrage records.

  5. Overview of Sentiment Screen data and signals

    main

    The Sentiment screen provides a composite view of market sentiment by aggregating data from multiple sources. It analyzes the following signal categories:

    • Momentum signals
    • Volume signals
    • Order book analysis
    • Trade activity
    • Whale activity

    Data Sources:

    • Gamma REST API: Provides market data.
    • CLOB API: Provides order book and trade activity data.

  6. Understand Wallet Intelligence data quality and lag

    main

    Data returned by analyze_wallet, live_whales, and whale_trades is lagged and is not the live CLOB (Central Limit Order Book) tape.

    Returned profiles include quality_flags to help determine data completeness. Always check for these flags before making decisions based on trade direction or volume.

    Key Quality Flags:

    • lagged_data_api: Indicates the data is from the lagged Data API.
    • partial_data: Data is incomplete.
    • no_public_positions / no_public_trades: Missing specific data types.
    • local_db_only: Data is sourced only from local observations.
    • requires_recent_refresh_for_live_flow: The profile needs a refresh to be considered current for live flow analysis.

  7. How price and print rules work in the Alert Engine

    main

    The Alert Engine handles two distinct types of local alerts using different data sources and storage mechanisms:

    Price Rules

    • Logic: Resolves a market via Gamma, reads current probability, and compares it against above or below thresholds.
    • Data Source: Gamma API.
    • Storage: Saved rules are stored in the local SQLite price_alerts table.

    Print Rules

    • Logic: Uses PrintScanner to read Data API /trades, filters for non-trade rows, and matches against min_notional and optional market/wallet filters.
    • Data Source: Data API /trades (lagged, not live CLOB).
    • Storage: Saved rules are stored in the local SQLite alert_rules table. Triggered events are recorded in the alerts table with alert_type=print.

  9. Understand the role of Shortcuts vs. Screen Routes

    main

    The shortcuts.py module is considered a legacy utility. While it provides a way to resolve keys to action names, it is not the authoritative dispatch table for the TUI.

    For actual screen dispatch and runtime routing, the system uses SCREEN_ROUTES located in controller.py. SCREEN_ROUTES is more comprehensive and maps directly to screen functions. Use shortcuts.py only when you need to resolve a key press to a logical action name without performing the actual navigation.

  11. Use the Position Tracker to manage trades manually

    main
    The Position Tracker allows you to record and manage trades locally without connecting a wallet. All data is stored in a local SQLite database located at ~/.polyterm/data.db. You can use this screen to add positions with entry prices, track open or closed positions, and view P&L summaries.