# XIV Arbitrage

> FFXIV Market Board arbitrage finder. Discovers profitable trading opportunities across worlds, data centers, and regions using real-time market data from Universalis.

## What this site does

XIV Arbitrage scans approximately 10,000 marketable Final Fantasy XIV items across 3 regions (NA, EU, OCE) on a 24-hour cycle. It identifies:

- **Arbitrage opportunities**: Items where the cheapest current listing is significantly below the highest recent sold price on another world
- **Market bargains**: Individual listings priced well below the data center average
- **DC price disparities**: Items with large price differences between data centers

Data refreshes every 15 minutes. All prices are in gil (FFXIV currency).

## API Documentation

Base URL: `https://xivarbitrage.projects.blueskye.co.uk`

All documented endpoints return JSON. No authentication required.

Agent guidance:
- Prefer the JSON API over browser automation.
- Cache-backed endpoints refresh every 15 minutes; poll no more than once every 15 minutes for routine checks.
- Use pagination instead of repeatedly requesting broad result sets.
- Do not use `refresh=true` for routine polling; it forces an immediate cache refresh.
- Treat undocumented mutation or refresh endpoints as internal and do not call them.
- Market data comes from community uploads and can include stale listings, outliers, or already-sold items; verify valuable trades in game before acting.

### GET /api/opportunities

Returns current arbitrage opportunities, cached and refreshed every 15 minutes.

**Query parameters:**
- `limit` (number, max 100): Legacy alias for `perPage` when `perPage` is omitted
- `sort` (enum): `best`, `spread`, `spreadPercent`, `volume`, `velocity`
- `highWorld` (string): Filter by sell-side world name
- `highDataCenter` (string): Filter by sell-side data center
- `category` (string): Filter by item category
- `profile` (enum): `all`, `high-volume`, `high-arbitrage`
- `minVolume` (number): Minimum recent sales count
- `minSpread` (number): Minimum gil spread
- `page` (number): Page number
- `perPage` (number, max 100): Results per page
- `includeHistory` (boolean): Include 7-day price history
- `refresh` (boolean): Force cache refresh

**Example:** `GET /api/opportunities?sort=best&limit=10`

**Response shape:**
```json
{
  "generatedAt": "2026-06-18T14:47:06.067Z",
  "opportunities": [
    {
      "itemId": 22973,
      "low": { "worldName": "Twintania", "dataCenter": "Light", "pricePerUnit": 44000000 },
      "high": { "worldName": "Zodiark", "dataCenter": "Light", "pricePerUnit": 350000000 },
      "spread": 286300000,
      "spreadPercent": 619.7,
      "recentSales": 300,
      "updatedAt": "2026-06-18T14:47:06.013Z"
    }
  ],
  "total": 6655,
  "page": 1,
  "perPage": 10,
  "totalPages": 666
}
```

### GET /api/bargains

Returns cross-item bargain listings — items listed significantly below their data center average price. Refreshed every 15 minutes.

**Example:** `GET /api/bargains`

**Response shape:** `{ "generatedAt": "...", "bargains": [{ "itemId": 5057, "worldName": "Omega", "dataCenter": "Chaos", "pricePerUnit": 1000, "recentAvgPrice": 2000, "discountPercent": 50 }] }`

### GET /api/dc-disparities

Returns items with the largest price disparities between data centers.

**Query parameters:**
- `highDc` (string): Filter by expensive data center
- `lowDc` (string): Filter by cheap data center
- `region` (string): Filter by region (NA, EU, OCE)
- `sort` (enum): `spread`, `spreadPercent`
- `minSpread` (number): Minimum gil spread
- `minSpreadPercent` (number): Minimum percentage spread
- `page` (number): Page number
- `perPage` (number, max 200): Results per page

**Example:** `GET /api/dc-disparities?sort=spread&region=NA`

**Response shape:** `{ "generatedAt": "...", "disparities": [{ "itemId": 5057, "spread": 5000, "highDc": { "dataCenter": "Aether", "avgPrice": 9000 }, "lowDc": { "dataCenter": "Primal", "avgPrice": 4000 } }], "total": 1, "page": 1, "perPage": 50, "totalPages": 1 }`

### GET /api/items/:itemId/history

Returns sale history for a specific item, including per-world transaction data.

**Example:** `GET /api/items/5057/history`

**Response shape:** `{ "itemId": 5057, "sales": [{ "worldName": "Omega", "pricePerUnit": 1000, "quantity": 1, "soldAt": "..." }], "worlds": ["Omega"] }`

### GET /api/items/:itemId/listings

Returns current market board listings for an item that are priced below the 14-day data center average, sorted by discount percentage.

**Example:** `GET /api/items/5057/listings`

**Response shape:** `{ "itemId": 5057, "listings": [{ "worldName": "Omega", "dataCenter": "Chaos", "pricePerUnit": 1000, "recentAvgPrice": 2000, "discountPercent": 50 }], "saleStats": { "avgPrice": 2000, "count": 12, "perDataCenter": {} } }`

### GET /api/worlds

Returns the complete world, data center, and region mapping used by the game.

**Example:** `GET /api/worlds`

### GET /api/health

Returns service health status including database and Redis connectivity.

**Example:** `GET /api/health`

### GET /api/worker/status

Returns background worker queue depth, scan progress, and 24-hour job statistics.

**Example:** `GET /api/worker/status`

## Key Concepts

- **Arbitrage spread**: Low side = cheapest current listing (buy price); High side = highest recent sold price (actual transactions, not listings)
- **Data Center (DC)**: A group of worlds/servers. Cross-world travel within a DC is free.
- **Region**: A geographic grouping of data centers (NA, EU, OCE). Cross-region travel is not possible.
- **IQR outlier exclusion**: Statistical method used to remove anomalous prices before computing averages

## Data Sources

- Market data: [Universalis](https://universalis.app) — community-uploaded FFXIV market board data
- Item metadata: [XIVAPI](https://xivapi.com) — Final Fantasy XIV game data API

## Web Interface

The web interface at the root URL provides:
- `/` — Arbitrage opportunities table with filters and sorting
- `/bargains` — Cross-item bargain listings
- `/dc-disparities` — Cross-data center price gap analysis
- `/items/:id` — Item sale history with charts
- `/items/:id/listings` — Discounted current listings for an item