# FFXIV Market Board Price Checker + Deal Monitor (`nerolabs/ffxiv-market-monitor`) Actor

Returns FFXIV market board prices per item from the official Universalis API (cheapest listing, sale velocity, recent sales) for a world, Data Centre or region, with price-drop alerts in monitor mode. Inputs: item IDs, world/DC/region. Agent-ready: pay per event (x402 and MCP), per item checked.

- **URL**: https://apify.com/nerolabs/ffxiv-market-monitor.md
- **Developed by:** [Adam Pearce](https://apify.com/nerolabs) (community)
- **Categories:** Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 item price checkeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does FFXIV Market Board Price Checker + Deal Monitor do?

Wondering what an item is actually selling for on your Final Fantasy XIV server right now, or which world in your Data Center has it cheapest? This Actor checks live **FFXIV market board prices** for one or more items, scoped to a single world, a whole Data Center, or a whole region, and returns the cheapest current listing, average sale price, and recent sale velocity for each. Turn on **Monitor mode** and it remembers what it saw last time, so a scheduled run only flags an item when the price actually drops, instead of you re-checking Universalis by hand every day.

Data comes straight from [Universalis](https://universalis.app)'s official, MIT-licensed market board API, the same crowdsourced data source the FFXIV trading community already relies on, not a scrape of any website. Run it via the Apify Console, the API, or on a schedule, and export results as JSON, CSV, or Excel.

### Why use this Actor?

- **Crafters and gatherers** checking what their goods are actually worth right now, or scanning a whole Data Center for the best price before listing.
- **Market board flippers** who want to know the moment a good deal appears, without babysitting Universalis in a browser tab all day.
- **Static/FC officers and tool builders** who want live FFXIV price data as structured JSON, on a schedule, feeding a spreadsheet, bot, or dashboard.

### How to use FFXIV Market Board Price Checker + Deal Monitor

1. Click **Try for free** or **Run** on the Actor page.
2. Enter one or more `itemIds` (find an item's ID on [universalis.app](https://universalis.app), it's in the item page's URL, or on [garlandtools.org](https://www.garlandtools.org)).
3. Enter `worldDcRegion`: a single world name (e.g. `Excalibur`) for one server, a Data Center name (e.g. `Aether`, `Chaos`, `Mana`) to check every world in it at once, or a region name (e.g. `North-America`) for the widest scope.
4. For ongoing deal-hunting, turn on `monitorMode`, keep the same `itemIds`, `worldDcRegion`, and `watchlistId`, and schedule the Actor (e.g. hourly). You'll only get billed for a real alert, not for confirming nothing changed.
5. View results in the Console table, or pull them via the API/dataset export.

### Input

See the Input tab for the full schema. Key fields:

| Field | Description |
|---|---|
| `itemIds` | One or more Universalis item IDs to check. |
| `worldDcRegion` | The world, Data Center, or region to check prices in. |
| `listingsPerItem` | How many raw current listings to include per item (default 5). |
| `includeHistory` | Include recent completed sales, not just current listings (default on). |
| `monitorMode` | When true, only reports what changed since the last check. |
| `watchlistId` | Keeps separate Monitor mode price histories if you run more than one watchlist. |
| `priceDropAlertPercent` | Alert when the cheapest price drops by at least this percent (default 10%). |
| `targetPriceGil` | Optional. Always alert the moment the price hits this level or below. |

### Output

Each result includes the item's current cheapest price, average price, sale velocity, and (in Monitor mode) what changed. Example (trimmed):

```json
{
  "itemId": 5333,
  "worldDcRegion": "Aether",
  "scopeType": "dataCenter",
  "hasData": true,
  "minPrice": 5,
  "minPriceNQ": 5,
  "minPriceHQ": 5,
  "averagePrice": 224873.53,
  "regularSaleVelocity": 68.29,
  "cheapestWorld": "Jenova",
  "listings": [{ "pricePerUnit": 5, "quantity": 3, "hq": true, "world": "Jenova" }],
  "universalisItemUrl": "https://universalis.app/market/5333",
  "alertTriggered": false,
  "alertReason": "No price drop since the last check."
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Data table

| Field | What it is |
|---|---|
| `itemId` | The Universalis/game item ID checked. |
| `scopeType` | Whether this was a `world`, `dataCenter`, or `region` check. |
| `hasData` | Whether the item currently has any market data in this scope. |
| `minPrice`, `minPriceNQ`, `minPriceHQ` | Cheapest current listing, overall / NQ only / HQ only. |
| `cheapestWorld` | Which world has the cheapest current listing (useful for DC/region scope). |
| `regularSaleVelocity` | Roughly how many units sell per day, a gauge of how real a listing price is. |
| `listings`, `recentSales` | Raw current listings and recent completed sales, trimmed to your requested count. |
| `previousMinPrice`, `percentChange`, `alertTriggered`, `alertReason` | Monitor mode only: what changed since the last check. |

### Pricing / Cost estimation

Pay-per-event pricing, no subscription. A single price check costs $0.01 per item returned. Watching 10 items hourly in Monitor mode costs roughly $0.50 to $2/day depending on how often anything actually crosses your alert threshold ($0.002 per no-alert confirmation, $0.05 per real alert).

### Tips

- A Data Center scope is usually the realistic buy/sell range, since traveling between Data Centers isn't free in-game. Region scope is wider but includes worlds you may not actually be able to reach easily.
- For ongoing deal-hunting, schedule the Actor (Apify's built-in Schedules) rather than running it manually. Monitor mode is designed for exactly that.
- Keep `watchlistId` consistent across scheduled runs for the same list, changing it starts a fresh price history.
- Set `listingsPerItem` and `historyEntriesPerItem` to 0 if you only need the summary stats (cheapest price, average, velocity), it keeps runs smaller and faster.

### FAQ

**Why doesn't the output include the item's name, just a number?**
Universalis' own API only knows market data, not FFXIV's game text, so item names aren't something this Actor can pull reliably or safely redistribute. Every result links straight to the item's Universalis page for a one-click name check, and item IDs are the same identifier Universalis, Teamcraft, and Garland Tools already use.

**I checked an item and got `hasData: false`. Is the item ID wrong?**
Not necessarily; it means there's currently no market data for that item in the scope you checked, either nobody's selling it right now, or the ID isn't a marketable item at all. This is reported honestly rather than guessed at.

**Does Monitor mode alert on price increases too?**
No, by design. This Actor is built for deal-hunting (buyers watching for a price drop), not for sellers watching for a price rise.

**How current is the data?**
Universalis is crowdsourced from players' own game clients in real time, so freshness depends on how recently someone with the relevant world open uploaded data. Busy items on popular worlds are usually minutes old; quiet items can be older.

If this Actor caught you a real deal, a review on the Actor page helps a lot and helps decide what to build next. Found a bug or have a request? Use the Issues tab, replies are personal, not automated.

# Actor input Schema

## `itemIds` (type: `array`):

Universalis/game item IDs to check, e.g. 5333. Find an item's ID on universalis.app (search the item, the ID is in the page URL) or garlandtools.org. Accepts one or many.

## `worldDcRegion` (type: `string`):

Scopes the price check. A single world (e.g. 'Excalibur') checks that server only. A Data Center (e.g. 'Aether', 'Chaos', 'Mana') checks every world in it and finds the cheapest. A Region (e.g. 'North-America', 'Europe', 'Japan', 'Oceania') is the widest scope. Wider scope means more listings to find a deal in, but a Data Center is usually the realistic buy/sell range since cross-DC travel isn't free in-game.

## `listingsPerItem` (type: `integer`):

How many of the cheapest current listings to include in the output for each item, beyond the summary stats. 0 skips raw listings entirely (smaller, cheaper runs).

## `includeHistory` (type: `boolean`):

Include the most recent completed sales for each item, not just current listings. Useful for gauging real sale velocity, not just asking prices.

## `historyEntriesPerItem` (type: `integer`):

How many recent sales to include per item, if 'Include recent sale history' is on.

## `monitorMode` (type: `boolean`):

When true, the Actor remembers the cheapest price it saw last time for each item and only flags an alert when the price drops meaningfully since then, or crosses your target price. Schedule this Actor to run on the same itemIds, worldDcRegion, and watchlistId (e.g. hourly) for ongoing deal-hunting.

## `watchlistId` (type: `string`):

Only needed if you're running more than one independent watchlist from the same Apify account and want their price history kept separate. Leave as default otherwise.

## `priceDropAlertPercent` (type: `integer`):

Alert when the cheapest listing price for an item drops by at least this percent since the last check.

## `targetPriceGil` (type: `integer`):

If set, also alert the moment the cheapest listing price drops to or below this absolute price, even if the percent-drop threshold isn't met. Only fires once, on the transition into that range, not on every run spent below it. Applies to every item in this run, so it's best used with a single item or items of similar value.

## Actor input object example

```json
{
  "itemIds": [
    "5333",
    "5057",
    "4995"
  ],
  "worldDcRegion": "Aether",
  "listingsPerItem": 5,
  "includeHistory": true,
  "historyEntriesPerItem": 5,
  "monitorMode": false,
  "watchlistId": "default",
  "priceDropAlertPercent": 10
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "itemIds": [
        "5333",
        "5057",
        "4995"
    ],
    "worldDcRegion": "Aether"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nerolabs/ffxiv-market-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "itemIds": [
        "5333",
        "5057",
        "4995",
    ],
    "worldDcRegion": "Aether",
}

# Run the Actor and wait for it to finish
run = client.actor("nerolabs/ffxiv-market-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "itemIds": [
    "5333",
    "5057",
    "4995"
  ],
  "worldDcRegion": "Aether"
}' |
apify call nerolabs/ffxiv-market-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nerolabs/ffxiv-market-monitor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NImpAeWRvHws6Jrq1/builds/cJMSGISyUABef7SMn/openapi.json