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

# Understanding Arbitrage 

> Discover how Arbitrage detects, scores, and classifies cross-platform price discrepancies — and what each opportunity field tells you before you act.

When the same prediction market outcome trades at different prices on different platforms, you can theoretically buy where the price is low and sell where it is high, locking in a risk-free profit. Arbitrage continuously scans all seven integrated platforms and surfaces these discrepancies as structured, scored opportunities — giving you the intelligence to act, without executing any trades on your behalf.

<Warning>
  Predexy is a market intelligence tool. It identifies and scores potential arbitrage opportunities but does **not** execute trades, manage positions, or move any funds. All execution decisions and actions are entirely your responsibility.
</Warning>

## Two types of Arbitrage

Predexy detects two structural patterns:

**Direct arbitrage (`direct`)** — The same Yes outcome is priced differently on two platforms. You buy Yes where it is cheap and sell Yes where it is expensive.

**Dutch-book arbitrage (`dutch_book`)** — You buy Yes on one platform and No on another, and the combined cost of both is less than $1.00. Because one of them must resolve to $1.00, you are guaranteed a profit if both positions fill.

The `type` field on every `ArbitrageOpportunity` object is either `direct` or `dutch_book`.

## How opportunities are scored

Each opportunity receives an `arbitrage_score` between 0 and 100. The score combines three dimensions:

* **Execution quality** — spread magnitude, net profit after fees, fee efficiency across both legs
* **Market quality** — liquidity depth and 24-hour trading volume on both sides
* **Temporal quality** — time remaining until market expiry (longer runways score higher)

The score is designed to rank practically useful opportunities above ones that look attractive on paper but are undermined by thin liquidity, high fees, or imminent expiry.

<Tip>
  Use `min_score` when querying the opportunities endpoint to filter out low-quality signals before they reach your workflow. The default is 40 (informational and above).
</Tip>

## Classifications

Based on the score and supporting conditions, every opportunity is assigned a `classification`:

| Classification  | Score | Additional conditions                           |
| --------------- | ----- | ----------------------------------------------- |
| `actionable`    | ≥ 70  | Positive net spread, combined liquidity > \$500 |
| `informational` | 40–69 | Below score threshold or low liquidity          |
| `noise`         | \< 40 | Not recommended for further review              |

## Lifecycle states

Opportunities are not deleted when they age — they move through a state machine so you always know whether a signal is fresh, fading, or historical:

| Status     | Meaning                                                       |
| ---------- | ------------------------------------------------------------- |
| `active`   | Recently re-observed in the latest scan cycle                 |
| `stale`    | Missed one or more scan cycles; treat with caution            |
| `resolved` | Hard-expired or missed the maximum consecutive miss threshold |

The `consecutive_misses` counter tells you how many scan cycles have passed since the opportunity was last confirmed. Use `stale_after_at` and `expire_after_at` as the soft and hard lifecycle boundaries.

## Key fields

The `ArbitrageOpportunity` object carries all the data you need to evaluate a signal:

| Field               | Type                     | Description                                    |
| ------------------- | ------------------------ | ---------------------------------------------- |
| `type`              | `direct` \| `dutch_book` | Arbitrage strategy detected                    |
| `buy_price`         | number (0–1)             | Price to buy the outcome on `buy_platform`     |
| `sell_price`        | number (0–1)             | Price to sell the outcome on `sell_platform`   |
| `net_spread`        | number                   | Raw spread minus platform fees                 |
| `estimated_profit`  | number                   | Estimated profit per \$100 deployed            |
| `annualized_return` | number                   | Return annualized based on time to expiry      |
| `arbitrage_score`   | integer (0–100)          | Multi-factor quality score                     |
| `classification`    | string                   | `actionable`, `informational`, or `noise`      |
| `status`            | string                   | `active`, `stale`, or `resolved`               |
| `risk_gate_state`   | string                   | `allowed`, `degraded`, or `blocked`            |
| `fees.buy_fee`      | number                   | Fee fraction on the buy leg (e.g. `0.02` = 2%) |
| `fees.sell_fee`     | number                   | Fee fraction on the sell leg                   |
| `fees.total_fees`   | number                   | Combined round-trip fee fraction               |

## Risk gate states

The `risk_gate_state` field reflects Predexy's runtime assessment of whether an opportunity should be acted upon:

| State      | Meaning                                                             |
| ---------- | ------------------------------------------------------------------- |
| `allowed`  | No runtime flags; opportunity passes all checks                     |
| `degraded` | Data quality or platform-level concerns; proceed with extra caution |
| `blocked`  | Opportunity is suppressed; do not act                               |

When `risk_gate_state` is `degraded` or `blocked`, the `risk_gate_reason` field provides a machine-readable explanation.

<Accordion title="Example opportunity object">
  ```json theme={null}
  {
    "id": "arb_poly_limit_abc123",
    "question_title": "Will BTC reach $100k by 2026?",
    "type": "direct",
    "buy_platform": { "slug": "limitless", "name": "Limitless" },
    "sell_platform": { "slug": "polymarket", "name": "Polymarket" },
    "buy_price": 0.42,
    "sell_price": 0.48,
    "spread": 0.06,
    "spread_bps": 600,
    "net_spread": 0.02,
    "estimated_profit": 2.00,
    "annualized_return": 24.5,
    "arbitrage_score": 78,
    "classification": "actionable",
    "status": "active",
    "risk_gate_state": "allowed",
    "fees": {
      "buy_fee": 0.02,
      "sell_fee": 0.02,
      "total_fees": 0.04
    }
  }
  ```
</Accordion>