> ## Documentation Index
> Fetch the complete documentation index at: https://polyquantlab.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Arb signals & audit

> The four signal tiers our engine surfaces, and how we publicly reconcile each one against resolution.

PolyQuantLab continuously scans the Polymarket book for mispricings.
Every signal we surface is logged to `arb_audit_log` (Postgres) at
detection time, then **reconciled** to resolution outcome the instant
the market closes. The aggregate is queryable via
[`GET /v1/arb/audit/aggregate`](/docs/api-reference/arb/audit-aggregate)
or browsable at the public [audit page](https://polyquantlab.com/audit).

## Four tiers

| Tier      | Trigger                                                           | Direction           | What it claims                                             |
| --------- | ----------------------------------------------------------------- | ------------------- | ---------------------------------------------------------- |
| `logical` | `yes_ask + no_ask < $1.00`                                        | BUY\_BOTH           | Math-guaranteed profit at resolution.                      |
| `endgame` | model says near-certain + dual-oracle agreement, in final 0–120 s | BUY\_YES or BUY\_NO | High empirical hit-rate from book-lag in the last seconds. |
| `stable`  | probability-arb on the maker-zone book (fill ≥ \$0.30)            | BUY\_YES or BUY\_NO | Where the maker bot is parked — usually well-calibrated.   |
| `stale`   | probability-arb on a thin / deep book (fill \< \$0.30)            | BUY\_YES or BUY\_NO | Deep mispricings, often already arbed by HFT.              |

The [`/v1/arb/live`](/docs/api-reference/arb/live) endpoint returns currently-
firing opportunities across all four tiers in real time.

## Audit record per detection

When the detector emits an opportunity, the following is logged
**before any user sees it**:

| Column                  | Type        | Notes                                    |
| ----------------------- | ----------- | ---------------------------------------- |
| `detected_at`           | timestamptz | Wall-clock at detection.                 |
| `market_id`             | text        | The CLOB market hash.                    |
| `ticker` / `event_type` | text        | `BTC` / `5m`, etc.                       |
| `tier`                  | text        | `logical`, `endgame`, `stable`, `stale`. |
| `direction`             | text        | `BUY_YES`, `BUY_NO`, `BUY_BOTH`.         |
| `fill_price`            | numeric     | Real ask we'd hit.                       |
| `model_yes_prob`        | numeric     | Our log-normal model's P(YES).           |
| `model_ev_per_share`    | numeric     | Net EV after entry fees.                 |
| `est_fee_per_share`     | numeric     | Polymarket 2026 taker fee.               |
| `resolution_at`         | timestamptz | When the market will resolve.            |

On resolution the settler joins to `events.resolution_outcome` and
fills in:

| Column                   | Type        | Notes                                                                                                  |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------ |
| `resolved_at`            | timestamptz | Reconciliation time.                                                                                   |
| `resolved_outcome`       | text        | `yes_won` / `no_won`.                                                                                  |
| `realized_pnl_per_share` | numeric     | `payoff − fill_price − est_fee`, computed correctly for each direction (BUY\_YES, BUY\_NO, BUY\_BOTH). |

**Nothing is deleted**. The aggregate you read from `/v1/arb/audit/aggregate`
is unfiltered `count(*)`, `avg(realized_pnl_per_share)`, etc.

## Calibration

The aggregate returns both `avg_model_ev` and `avg_realized` per tier
so you can compare. A model whose `avg_realized ≈ avg_model_ev` is
well-calibrated; the gap is the engine's honest blind-spot.

For BTC/ETH/SOL Up/Down markets across our entire log, the probability
arb (stable + stale) tiers have realised \~zero edge — Polymarket's
maker bots are well-calibrated for crypto. The logical tier is
positive by construction, and the endgame tier has shown \~95 %
empirical win rate from book lag in the final seconds.

Read more on the [public audit page](https://polyquantlab.com/audit) —
same numbers, no signin required.