# Poe.ninja — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access real-time Path of Exile economy data from poe.ninja, including item prices, currency exchange rates, divination card values, market trends, and build statistics by class.

**Category:** Entertainment | **Website:** [poe.ninja/](https://poe.ninja/) | **Docs:** [parse.bot/marketplace/c5021715-7468-40f7-b591-c724ce322558/poe-ninja-api](https://parse.bot/marketplace/c5021715-7468-40f7-b591-c724ce322558/poe-ninja-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-poe-ninja-api-c5021715/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_build_classes_and_dps

Retrieve character class build statistics for a given league. Returns classes ordered by popularity percentage along with their top skills. Build data availability depends on the league having an active ladder; newer leagues may have empty statistics until data is populated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league` | string | No | League name. Leagues with populated build data include Allflame, Hardcore Allflame. Newer leagues like Mirage may not yet have build statistics available. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-poe-ninja-api-c5021715/get_build_classes_and_dps \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league":"<string>"}'
```

### get_currency_prices

Retrieve currency exchange rates and chaos equivalents for a given league. Returns all tracked currencies with their chaos equivalent values and buy/sell prices. Covers orbs, catalysts, lifeforce, and other tradeable currency items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league` | string | No | League name. Active economy leagues include Mirage, Hardcore Mirage, Standard, Hardcore, Allflame, Hardcore Allflame. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-poe-ninja-api-c5021715/get_currency_prices \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league":"<string>"}'
```

### get_divination_cards

Get divination card details including names, stack sizes, and prices in chaos and divine orbs for a given league.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league` | string | No | League name. Active economy leagues include Mirage, Hardcore Mirage, Standard, Hardcore. Defaults to the current active league. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-poe-ninja-api-c5021715/get_divination_cards \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league":"<string>"}'
```

### get_item_prices

Retrieve current prices of Path of Exile items from poe.ninja for a given league and item category. Returns items with chaos orb and divine orb valuations, base types, link counts, and item classes. When category is SkillGem, each item also includes gem_level, gem_quality, and corrupted fields, and results can be filtered by gem level and/or gem quality using either single values or multiple combinations via gem_combinations, and by corruption status via the corrupted parameter. Quality 0 matches gems with no explicit quality set. Categories that no longer exist on poe.ninja (e.g. DivinationCard) return an upstream 404.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Item category. Accepted values include UniqueWeapon, UniqueArmour, UniqueAccessory, UniqueFlask, UniqueJewel, SkillGem, Map, Incubator. |
| `corrupted` | boolean | No | Filter by corruption status when category is SkillGem. When true, returns only corrupted gems; when false, returns only non-corrupted gems. Omit to return both. Ignored for non-SkillGem categories. |
| `gem_combinations` | string | No | JSON array of objects specifying multiple gem level/quality filter combinations when category is SkillGem. Each object may have 'level' and/or 'quality' keys (e.g. [{"level": 21, "quality": 20}, {"level": 20, "quality": 0}]). Items matching ANY combination are returned. Use quality 0 for gems with no explicit quality. Takes precedence over gem_level/gem_quality when provided. Ignored for non-gem categories. |
| `gem_level` | integer | No | Filter by gem level when category is SkillGem (e.g. 21). Ignored for non-gem categories. Overridden by gem_combinations when both are provided. |
| `gem_quality` | integer | No | Filter by gem quality when category is SkillGem (e.g. 20). Use 0 for gems with no explicit quality. Ignored for non-gem categories. Overridden by gem_combinations when both are provided. |
| `league` | string | No | League name. Active economy leagues include Mirage, Hardcore Mirage, Standard, Hardcore, Allflame, Hardcore Allflame. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-poe-ninja-api-c5021715/get_item_prices \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","corrupted":"<boolean>","gem_combinations":"<string>","gem_level":"<integer>","gem_quality":"<integer>","league":"<string>"}'
```

### get_market_trends

Extract economic trend data including sparkline price history for items or currencies in a given league and category. Each trend entry includes the current chaos value and 7-point sparkline arrays showing recent price movement percentages. When category is SkillGem, each trend item also includes gem_level, gem_quality, and corrupted fields, and results can be filtered by gem level and/or gem quality using either single values or multiple combinations via gem_combinations, and by corruption status via the corrupted parameter. Quality 0 matches gems with no explicit quality set.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category name. Accepted values include Currency, UniqueWeapon, UniqueArmour, UniqueAccessory, UniqueFlask, UniqueJewel, SkillGem, Map, Incubator. |
| `corrupted` | boolean | No | Filter by corruption status when category is SkillGem. When true, returns only corrupted gems; when false, returns only non-corrupted gems. Omit to return both. Ignored for non-SkillGem categories. |
| `gem_combinations` | string | No | JSON array of objects specifying multiple gem level/quality filter combinations when category is SkillGem. Each object may have 'level' and/or 'quality' keys (e.g. [{"level": 21, "quality": 20}, {"level": 20, "quality": 0}]). Items matching ANY combination are returned. Use quality 0 for gems with no explicit quality. Takes precedence over gem_level/gem_quality when provided. Ignored for non-gem categories. |
| `gem_level` | integer | No | Filter by gem level when category is SkillGem (e.g. 21). Ignored for non-gem categories. Overridden by gem_combinations when both are provided. |
| `gem_quality` | integer | No | Filter by gem quality when category is SkillGem (e.g. 20). Use 0 for gems with no explicit quality. Ignored for non-gem categories. Overridden by gem_combinations when both are provided. |
| `league` | string | No | League name. Active economy leagues include Mirage, Hardcore Mirage, Standard, Hardcore, Allflame, Hardcore Allflame. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-poe-ninja-api-c5021715/get_market_trends \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","corrupted":"<boolean>","gem_combinations":"<string>","gem_level":"<integer>","gem_quality":"<integer>","league":"<string>"}'
```