# Tarsier Alpha — AI/LLM Access Guide
# https://tarsieralpha.com/llms.txt
# Last updated: 2026-03-31

## What Tarsier Alpha Is

Tarsier Alpha is an adaptive trading-intelligence platform for retail traders.
The live platform now combines:

- a stock scanner covering 500+ names
- long and short paper-trade tracking
- an adaptive learning engine
- an orchestrator brief / control layer
- a Polymarket beta with two lanes:
  - `stock_price` for individual-stock price/threshold contracts
  - `macro_futures` for crypto, broad market, oil, and volatility contracts

The core stock engine remains the main product. The Polymarket stack is live in
paper-mode beta and is intentionally limited to markets where the system has a
defined edge or a testable macro/risk-regime thesis.


## Public Website Surfaces

Base URL: https://tarsieralpha.com

- `/` — landing page describing the live platform and current beta status
- `/about` — product architecture and platform explanation
- `/pricing` — launch timing and plan structure
- `/blog/*` — free options education
- `/polymarket/` — public-facing beta dashboard for prediction-market scanning
- `/llms.txt` — this machine-readable guide


## Public API (no authentication required)

GET `/api`
  Discovery document for public and paid surfaces.

GET `/api/v1/health`
  x402 readiness and status.

GET `/api/v1/info`
  Product, pricing, wallet, and payment metadata.

GET `/api/chart/<ticker>`
  Chart payload with candles plus indicator data.
  Examples:
  - `/api/chart/AAPL`
  - `/api/chart/BTC?interval=5m&period=7d&polymarket=1`

GET `/api/market-regime`
  Current regime, VIX, and SPY posture.


## Paid Intelligence — x402

Tarsier Alpha supports pay-per-call machine payments via the x402 protocol.

Primary paid endpoints:

- `GET /api/v1/candidates`
  Top scored stock candidates using current learned thresholds

- `GET /api/v1/watchlist`
  Developing stock setups below the current surfacing threshold

- `GET /api/v1/paper-trades`
  Closed paper-trade P&L history

- `GET /api/v1/snapshot`
  Daily state snapshot: candidates, paper trades, market regime, adaptive config

See `/api/v1/info` for current network, wallet, and pricing details.


## Agent API (X-Agent-Key required)

For recurring machine access, request an `X-Agent-Key`.

Available agent routes:

- `GET /api/agent/scans`
  Active candidates with scores, entry zones, and option-chain context

- `GET /api/agent/pnl`
  Paper-trade performance and P&L summaries

- `POST /api/agent/paper-trade`
  Simulate a paper-trade entry


## Polymarket Beta Truth

The Polymarket implementation is live in beta and currently runs in paper mode
by default.

Current behavior:

- dual candidate lanes:
  - `stock_price`
  - `macro_futures`
- Market Lens with 5-minute directional charting
- crypto lens prefers Coinbase Exchange public intraday candles for:
  - `BTC`
  - `ETH`
  - `XRP`
  - `SOL`
- approved `signal_buy` rows can auto-enter as paper trades
- learning is calibration-first through `pm_learning.py`

Current Polymarket routes:

- `GET /polymarket/`
- `GET /polymarket/api/markets`
- `GET /polymarket/api/trades`
- `GET /polymarket/api/portfolio`
- `GET /polymarket/api/status`
- `POST /polymarket/api/scan`

Important presentation rule:
Do not describe maker/rebate logic, hybrid execution, or full belief-vol
overlays as fully live defaults unless the code has been explicitly upgraded to
that state.


## Local Operator CLI

Local and Replit operators can use the Python CLI:

- `python3 tarsier_cli.py health`
- `python3 tarsier_cli.py config list`
- `python3 tarsier_cli.py config get <key>`
- `python3 tarsier_cli.py config set <key> <value>`
- `python3 tarsier_cli.py learning run`
- `python3 tarsier_cli.py learning stats`
- `python3 tarsier_cli.py orchestrator run --force`
- `python3 tarsier_cli.py orchestrator show`
- `python3 tarsier_cli.py scan run --type manual`
- `python3 tarsier_cli.py paper-trades summary`
- `python3 tarsier_cli.py polymarket status`
- `python3 tarsier_cli.py polymarket scan`
- `python3 tarsier_cli.py polymarket portfolio-refresh`
- `python3 tarsier_cli.py polymarket learning-run`
- `python3 tarsier_cli.py moltbook status`
- `python3 tarsier_cli.py moltbook publish --limit 1`

If installed from `pyproject.toml`, the console script is:

- `tarsier health`
- `tarsier orchestrator show`
- `tarsier polymarket status`


## Crawl Policy

See `/robots.txt` for the full crawler policy.

High-level intent:

- public pages and docs are crawlable
- private dashboards and account-specific trading surfaces are not
- agent guidance should be consumed from `/llms.txt`


## Contact

- X: @TarsierAlpha
- Telegram: https://t.me/+O33-6I3hUX5kNDRh
- TikTok: @tarsieralpha
- Instagram: @tarsieralpha