> For the complete documentation index, see [llms.txt](https://polymarks.gitbook.io/polymarks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polymarks.gitbook.io/polymarks-docs/getting-started/readme.md).

# Introduction

**Don't bet blind. Bet smart.**

PolyMarks is a real-time whale tracking and smart money analytics platform for Polymarket prediction markets. Track large trades, analyze market sentiment, and follow the money that actually moves markets.

## Why PolyMarks?

Most Polymarket traders are betting blind. They see current odds, but they don't see **who's moving those odds**.

PolyMarks solves this by:

* 🐋 Tracking every whale trade in real-time ($1K+ customizable)
* 🔔 Sending instant alerts for major moves ($10K+)
* 📊 Analyzing smart money sentiment (STRONG BUY vs BEARISH)
* 📈 Showing market-specific whale activity
* 🎯 Filtering 500+ markets by category and closing date

## Key Features

### 1. **Whale Tracker**

* Real-time feed of large trades ($1K+ configurable)
* Trader profiles with wallet addresses
* Exact trade size, price, and timing
* Direct links to Polygonscan transactions

### 2. **Real-Time Alerts**

* Toast notifications for $10K+ trades
* Auto-refresh every 20 seconds
* "LIVE" indicator when updating
* Optional sound notifications

### 3. **Smart Money Dashboard**

* Markets with unusual activity
* Recent whale trades (top 6)
* Odds shift detection
* Liquidity spike alerts

### 4. **Market Detail Pages**

* Full whale transaction history per market
* Buy vs Sell sentiment analysis
* Unique whale count
* STRONG BUY / BEARISH signals

### 5. **Category Intelligence**

* Auto-categorization via keyword detection
* Politics, Sports, Crypto, Business, Technology
* Color-coded badges
* Smart filtering

## Tech Stack

* **Framework:** Next.js 14 (App Router)
* **Language:** TypeScript
* **Styling:** Tailwind CSS + styled-jsx
* **3D Graphics:** Three.js, @react-three/fiber
* **APIs:**
  * Polymarket Gamma API (markets)
  * Polymarket Data API (trades)
  * Helius RPC (Solana)
* **Notifications:** react-hot-toast
* **Deployment:** Vercel / Railway

## Quick Start

```bash
# Clone the repository
git clone https://github.com/lloydfonterra/polymarks.git
cd polymarks

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Add your Helius API key

# Run development server
npm run dev
```

Visit `http://localhost:3000`

## Documentation

* [Quick Start](/polymarks-docs/getting-started/quick-start.md)
* [Features Overview](/polymarks-docs/getting-started/features.md)
* [Architecture](/polymarks-docs/technical-documentation/architecture.md)
* [API Integration](/polymarks-docs/technical-documentation/api-integration.md)
* [Deployment Guide](https://github.com/lloydfonterra/polymarks/blob/main/docs/deployment/production.md)

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](/polymarks-docs/contributing/contributing.md).

## License

MIT License - see [LICENSE](https://github.com/lloydfonterra/polymarks/blob/main/LICENSE/README.md) for details.

## Links

* **Website:** \[your-domain.com]
* **Twitter:** [@polymarksBSC](https://x.com/polymarksBSC)
* **Telegram Bot:** [@PolyMarksAlerts\_bot](https://t.me/PolyMarksAlerts_bot)
* **Polymarket:** [polymarket.com](https://polymarket.com)

***

Built with 💙 for the Polymarket community


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://polymarks.gitbook.io/polymarks-docs/getting-started/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.