Arbitrage Opportunities API — Session Auth

List and inspect scored arbitrage opportunities using a session JWT. Filter by score, classification, lifecycle status, and policy guarantee class.

The arbitrage opportunities endpoints give web app users access to Predexy’s full cross-platform arbitrage detection output. Opportunities are scored 0–100 using a multi-factor model, classified into tiers, and enriched with fee breakdowns, risk gate states, and governance metadata. These endpoints require a session JWT — if you are building an automated integration, see the external API key endpoint instead.

Endpoints

Method	Path	Description
GET	/api/v1/arbitrage/opportunities	List opportunities with filters
GET	/api/v1/arbitrage/opportunities/{id}	Single opportunity by ID
GET	/api/v1/arbitrage/opportunities/{id}/certificate	Governance certificate bundle
GET	/api/v1/arbitrage/opportunities/{id}/execution-advisory	Execution advisory
GET	/api/v1/arbitrage/opportunities/{id}/policy-decision	Policy decision record

Authentication

All endpoints require a session JWT:

Authorization: Bearer <your_jwt>

---

List opportunities

GET https://api.predexy.com/api/v1/arbitrage/opportunities

Returns a list of scored and classified arbitrage opportunities detected across integrated platforms. Results are sourced from the background pipeline and include lifecycle state, runtime risk-gate information, and execution advisory metrics.

Query parameters

min_score · number · default: "40"

Minimum arbitrage score to include. Range 0–100. The default of 40 excludes noise-tier opportunities.

classification · string

Filter by classification tier. One of actionable, informational, or noise.

• actionable — Score ≥ 70, positive net spread, liquidity above $500.
• informational — Score 40–69 or low liquidity. Worth monitoring but not immediately executable.
• noise — Score below 40. Likely ephemeral or uneconomical.

category · string

Filter by market category, e.g. crypto, politics, sports.

status · string

Filter by lifecycle status: active, stale, or resolved.

guarantee · string

Filter by policy guarantee class: STRICT or QUASI. STRICT indicates the opportunity passed all policy checks cleanly.

risk_gate · string

Filter by runtime risk gate state: allowed, degraded, or blocked.

limit · number · default: "50"

Maximum items to return (1–200).

Example request

cURL

curl "https://api.predexy.com/api/v1/arbitrage/opportunities?classification=actionable&min_score=70&limit=10" \
  -H "Authorization: Bearer <your_jwt>"

Response structure

The response contains a data object with two keys:

• data.opportunities — array of ArbitrageOpportunity objects.
• data.stats — ScanStats for the filtered result set.
• data.stats_all — ScanStats for the unfiltered result set (useful for dashboard summaries).
• meta — pagination state plus source (database, cache, or empty) and a disclaimer note about guarantee interpretation.

---

ArbitrageOpportunity schema

id · string · required

Unique opportunity identifier, e.g. "arb_poly_limit_abc123".

canonical_question_id · string · required

UUID of the canonical question this opportunity belongs to.

question_title · string · required

Human-readable question text, e.g. "Will BTC reach $100k by 2026?".

question_slug · string

URL-safe question slug.

category · string

Market category.

end_time · string

ISO 8601 market expiry timestamp. null for perpetual markets.

type · string · required

Arbitrage strategy: direct (same outcome priced differently across platforms) or dutch_book (buy Yes on one platform and No on another for a combined cost below $1).

buy_platform · object · required

Platform where you buy the outcome. Contains id, slug, and name.

sell_platform · object · required

Platform where you sell (or buy the opposite outcome). Contains id, slug, and name.

buy_price · number · required

Price to buy the outcome, expressed as a probability from 0 to 1.

sell_price · number · required

Price to sell the outcome on the other platform, from 0 to 1.

spread · number · required

Raw price spread (sell_price – buy_price).

spread_bps · number · required

Spread in basis points (1 bps = 0.01%).

net_spread · number · required

Spread after deducting platform fees from both legs.

estimated_profit · number · required

Estimated profit per $100 deployed, in USD.

annualized_return · number

Annualized return based on time remaining to market expiry.

arbitrage_score · number · required

Multi-factor quality score from 0 to 100. Combines execution quality (spread, fees), market quality (liquidity, volume), and temporal quality (time to expiry).

classification · string · required

actionable, informational, or noise.

liquidity · number

Combined available liquidity across both legs in USD.

volume24h · number

Combined 24-hour trading volume across both legs in USD.

platform_count · number

Number of platforms listing this question.

detected_at · string · required

ISO 8601 timestamp when this opportunity was first detected.

last_seen_at · string

Last timestamp when this opportunity was observed in a scan cycle.

status · string

Lifecycle state: active, stale, or resolved.

fees · object · required

Fee breakdown for both legs.

Show FeeBreakdown fields

buy_fee · number

Fee to execute the buy leg as a fraction (e.g. 0.02 = 2%).

sell_fee · number

Fee to execute the sell leg.

total_fees · number

Total round-trip fees.

expected_fill_prob · number

Estimated probability of execution fill, from 0 to 1.

expected_slippage_bps · number

Estimated slippage in basis points.

net_edge_after_execution · number

Net expected edge after accounting for fill probability and slippage.

recommended_notional · number

Advisory position size in USD.

portfolio_weight · number

Advisory portfolio allocation weight from 0 to 1.

risk_gate_state · string

Runtime risk gate: allowed, degraded, or blocked.

risk_gate_reason · string

Machine-readable reason when the gate is degraded or blocked. null when allowed.

guarantee · string

Policy guarantee class: STRICT or QUASI.

certificate_id · string

Certificate identifier when governance evidence exists.

freshness · object

Freshness metadata for this opportunity.

Show OpportunityFreshness fields

age_ms · number

Milliseconds since the detection timestamp.

source_lag_ms · number

Estimated source data lag in milliseconds.

is_stale · boolean

true when the freshness SLO threshold has been exceeded.

stale_reason · string

Machine-readable stale reason. null when fresh.

source_updated_at · string

Upstream source last update timestamp.

quality_breakdown · object

Per-dimension quality scores that feed into the final arbitrage_score.

Show OpportunityQualityBreakdown fields

spread_score · number

Score from the spread magnitude dimension.

liquidity_score · number

Score from the liquidity depth dimension.

volume_score · number

Score from the 24h volume dimension.

activity_score · number

Score from market activity signals.

platform_score · number

Score based on platform reliability.

resolution_score · number

Score based on resolution certainty.

freshness_score · number

Score based on data freshness.

trust_score_component · number

Trust adjustment component.

execution_score · number

Execution quality composite score.

final_score · number

Final integer score (same as arbitrage_score).

primary_drivers · string[]

List of score driver labels for display.

---

Get single opportunity

GET https://api.predexy.com/api/v1/arbitrage/opportunities/{id}

Returns full details for a single opportunity by its identifier.

Path parameters

id · string · required

Opportunity identifier, e.g. arb_poly_limit_abc123.

Example request

cURL

curl https://api.predexy.com/api/v1/arbitrage/opportunities/arb_poly_limit_abc123 \
  -H "Authorization: Bearer <your_jwt>"

---

Get certificate

GET https://api.predexy.com/api/v1/arbitrage/opportunities/{id}/certificate

Returns the governance certificate bundle for an opportunity. Certificates document the policy checks and evidence that determined the guarantee class. Only opportunities with a non-null certificate_id have a certificate.

---

Get execution advisory

GET https://api.predexy.com/api/v1/arbitrage/opportunities/{id}/execution-advisory

Returns execution advisory details — including recommended notional sizing, slippage estimates, and fill probability breakdown — for the specified opportunity.

---

Get policy decision

GET https://api.predexy.com/api/v1/arbitrage/opportunities/{id}/policy-decision

Returns the latest policy decision record, including the policy version used and the decision label applied during evaluation.

---

Sample opportunity response

{
  "data": {
    "id": "arb_poly_limit_abc123",
    "canonical_question_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "question_title": "Will BTC reach $100k by 2026?",
    "question_slug": "will-btc-reach-100k-by-2026",
    "category": "crypto",
    "end_time": "2026-01-01T00:00:00Z",
    "type": "direct",
    "buy_platform": { "id": "...", "slug": "limitless", "name": "Limitless" },
    "sell_platform": { "id": "...", "slug": "polymarket", "name": "Polymarket" },
    "buy_price": 0.58,
    "sell_price": 0.65,
    "spread": 0.07,
    "spread_bps": 700,
    "net_spread": 0.03,
    "estimated_profit": 3.00,
    "arbitrage_score": 78,
    "classification": "actionable",
    "liquidity": 15000.00,
    "volume24h": 52000.00,
    "status": "active",
    "guarantee": "STRICT",
    "risk_gate_state": "allowed",
    "risk_gate_reason": null,
    "detected_at": "2026-04-25T14:22:00Z",
    "fees": {
      "buy_fee": 0.02,
      "sell_fee": 0.02,
      "total_fees": 0.04
    }
  }
}