Metadata-Version: 2.4
Name: falcon-polymarket
Version: 0.1.1
Summary: Python client for the Falcon AI Polymarket external analytics API
Author: Falcon AI
License-Expression: MIT
Project-URL: Homepage, https://api.falconai.pro/api/docs
Project-URL: Documentation, https://api.falconai.pro/api/docs/sdks
Project-URL: API Reference, https://api.falconai.pro/api/docs/reference
Keywords: falcon,polymarket,prediction-markets,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# falcon-polymarket

Python client for the [Falcon AI Polymarket external API](https://api.falconai.pro/api/docs).

## Install

```bash
pip install falcon-polymarket
```

Local development:

```bash
pip install -e packages/falcon-polymarket-python
```

## Quick start

Set `FALCON_API_KEY` (from [Developer Keys](https://app.falconai.pro/app/developer/keys)) or pass explicitly:

```python
from falcon_polymarket import FalconPolymarketClient

with FalconPolymarketClient() as client:
    print(client.health())
    for market in client.iter_markets(status="active", limit=10):
        print(market["title"], market.get("yes_price"))
    board = client.get_leaderboard(limit=5, sort_by="total_realized_pnl")
    print(board)
    ticks = client.price_ticks("0x...", hours=1)
    print(len(ticks), "sub-minute ticks")
```

Staging:

```python
client = FalconPolymarketClient(
    api_key="aif_...",
    base_url="https://api-test.falconai.bot/api/v1/external/polymarket",
)
```

## Methods

- `health()`, `usage()`
- `list_markets()`, `iter_markets()`, `get_market()` — `event_slug` filter on list
- `list_events()`, `get_event()`, `list_series()`, `get_series()`
- `get_orderbook()`, `orderbook_history()` — `include_levels` for recent L2 rows
- `price_ticks()` — sub-minute CLOB WebSocket ticks
- `list_trades()`, `get_trader()`, `get_trader_stats()`
- `get_leaderboard()`, `get_copy_picks()`, `get_positions()`
- `run_backtest()`

See the [API reference](https://api.falconai.pro/api/docs/reference) for parameters and tiers.
