# Wynncraft API
> Wynncraft — the largest Minecraft MMORPG — as an API, from the official Wynncraft API. Look up any player by username for their support rank, total playtime, current guild, and full global stats: total combined level, mobs killed, chests found, completed quests, wars, dungeons, raids and PvP kills/deaths. Pull any guild by name or prefix with its level, member count and roster by rank, owned territories, war count and creation date. Read the live leaderboards (total combined level, guild level, guild territories, combat level, war completions and each gathering profession like mining, fishing and woodcutting), search the full item database for weapons, armour, accessories and ingredients with their tier/rarity, type, level and class requirement, elements, powder slots and major ids, browse the five playable classes, and get a class\x27s ability-tree size. Perfect for Wynncraft companion apps, guild and player trackers, item and build tools, leaderboards and Discord bots. No accounts, no upstream key.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/wynncraft-api/..."
```

## Pricing
- **Free** (Free) — 3,450 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 45,500 calls/Mo, 5 req/s
- **Pro** ($14/Mo) — 219,000 calls/Mo, 15 req/s
- **Mega** ($39/Mo) — 1,095,000 calls/Mo, 40 req/s

## Endpoints

### Players

#### `GET /v1/player` — Player profile & stats

**Parameters:**
- `username` (query, required, string) — Minecraft username Example: `Salted`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/player?username=Salted"
```

**Response:**
```json
{
    "data": {
        "player": {
            "rank": "champion",
            "uuid": "1ed075fc-5aa9-42e0-a29f-640326c1d80c",
            "guild": {
                "name": "Wynncraft",
                "rank": "OWNER",
                "prefix": "WYNN"
            },
            "stats": {
                "pvp": {
                    "kills": 23,
                    "deaths": 18
                },
                "wars": 7,
                "raids": 1,
                "dungeons": 19,
                "mobs_killed": 6993,
                "total_level": 1562,
                "chests_found": 411,
                "completed_quests": 38
            },
            "online": false,
            "server": null,
            "veteran": true,
            "playtime": 12843.17,
            "username": "Salted",
            "last_join": "2026-05-31T23:42:31.916000Z",
            "first_join": "2013-03-27T13:10:34.000000Z"
        }
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:29.092Z",
        "request_id": "9ed3c7c6-0f5c-4ae7-b93a-3153ae8a491e"
    },
    "status": "ok",
    "message": "Player retrieved",
    "success": true
}
```

### Guilds

#### `GET /v1/guild` — Guild by name/prefix

**Parameters:**
- `name` (query, optional, string) — Guild name Example: `Avicia`
- `prefix` (query, optional, string) — Guild prefix Example: `AVO`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/guild?name=Avicia&prefix=AVO"
```

**Response:**
```json
{
    "data": {
        "guild": {
            "name": "Avicia",
            "uuid": "00ccf9d3-6670-4cd7-a447-f7fec684129d",
            "wars": 221390,
            "level": 129,
            "online": 13,
            "prefix": "AVO",
            "created": "2018-08-01T16:40:45.322000Z",
            "xp_percent": 33,
            "banner_tier": 8,
            "territories": 52,
            "members_total": 149,
            "members_by_rank": {
                "chief": 28,
                "owner": 1,
                "captain": 59,
                "recruit": 6,
                "recruiter": 32,
                "strategist": 23
            }
        }
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:29.328Z",
        "request_id": "d81926cf-9c5a-423a-ad3d-d8b99b2e0571"
    },
    "status": "ok",
    "message": "Guild retrieved",
    "success": true
}
```

### Leaderboards

#### `GET /v1/leaderboard` — A ranked leaderboard

**Parameters:**
- `type` (query, optional, string) — Leaderboard type Example: `totalGlobalLevel`
- `limit` (query, optional, string) — Max 1-100 Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/leaderboard?type=totalGlobalLevel&limit=20"
```

**Response:**
```json
{
    "data": {
        "type": "totalGlobalLevel",
        "count": 20,
        "leaderboard": [
            {
                "xp": 100456382524,
                "name": "redacted",
                "rank": 1,
                "uuid": "redacted",
                "score": 25571,
                "playtime": 12872.83
            },
            {
                "xp": 10935813809,
                "name": "Krokofant",
                "rank": 2,
                "uuid": "7181f903-7849-49b4-9d5c-2f94ecb67313",
                "score": 24522,
                "playtime": 16107.5
            },
            {
                "xp": 3904806923,
                "name": "Rexshell",
                "rank": 3,
                "uuid": "63fac5fc-806d-419a-b715-c1e7c60f3ebb",
                "score": 24166,
                "playtime": 12961.33
            },
            {
                "xp": 1303739906,
                "name": "conniesunshine",
                "rank": 4,
                "uuid": "0026e281-0f15-45d8-a9fa-6bd40ad6681b",
                "score": 23469,
                "playtime": 6706.17
            },
            {
                "xp": 6432285546,
                "name": "nasiuduk",
                "rank": 5,
                "uuid": "3653daf4-be1f-418c-a71c-bfc88c3a9387",
                "score": 23282,
                "playtime": 4375
            },
            {
                "xp": 18540459528,
                "name": "Tannslee",
                "rank": 6,
                "uu
…(truncated, see openapi.json for full schema)
```

### Items

#### `GET /v1/item` — Search the item database

**Parameters:**
- `query` (query, required, string) — Item name Example: `Idol`
- `limit` (query, optional, string) — Max 1-50 Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/item?query=Idol&limit=20"
```

**Response:**
```json
{
    "data": {
        "count": 6,
        "items": [
            {
                "drop": null,
                "name": "Weathered Idol",
                "type": "ingredient",
                "level": 36,
                "rarity": "TIER_3",
                "elements": [],
                "sub_type": null,
                "major_ids": [],
                "average_dps": null,
                "attack_speed": null,
                "powder_slots": null
            },
            {
                "drop": "Aerie of the Recluse",
                "name": "Eidolon",
                "type": "weapon",
                "level": 95,
                "rarity": "rare",
                "elements": [
                    "air"
                ],
                "sub_type": "wand",
                "class_req": "mage",
                "major_ids": [],
                "average_dps": 280,
                "attack_speed": "superSlow",
                "powder_slots": 5
            },
            {
                "drop": "normal",
                "name": "False Idol",
                "type": "armour",
                "level": 37,
                "rarity": "fabled",
                "elements": [
                    "earth",
                    "thunder"
                ],
                "sub_type": "helmet",
                "major_ids": [
                    "Sun Eater"
                ],
                "average_dps": null,
                "attack_speed": null,
                "powder_slots": 2
   
…(truncated, see openapi.json for full schema)
```

### Reference

#### `GET /v1/abilities` — A class ability tree

**Parameters:**
- `class` (query, required, string) — archer|warrior|assassin|mage|shaman Example: `archer`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/abilities?class=archer"
```

**Response:**
```json
{
    "data": {
        "class": "archer",
        "pages": 9,
        "ability_ids": [
            "arrowbomb",
            "bowProficiency",
            "arrowBombCost1",
            "directHit",
            "hastyShots",
            "escape",
            "powerShots",
            "arrowstorm",
            "escapeCost1",
            "arrowshield",
            "windyfeet",
            "archerAirPath",
            "archerThunderPath",
            "archerFirePath",
            "archerWaterPath",
            "archerEarthPath",
            "arrowrain",
            "nimbleString",
            "mossyArrowStorm",
            "fireCreep",
            "phantomDarts",
            "hitToRename",
            "tripleShots",
            "guardianAngels",
            "explodingTrap",
            "focus",
            "windstorm",
            "arrowStormCost1",
            "implosion",
            "tripleshield",
            "betterWindyFeet",
            "arsenalSynergy",
            "timeBomb",
            "grapplingHook",
            "moreFocus",
            "murderFlock",
            "arrowBombDamage1",
            "phantomForce",
            "leap",
            "grapeBomb",
            "ivyrootMamba",
            "concentration",
            "shrapnelBomb",
            "fierceStomp",
            "rocketJump",
            "scorchedEarth",
            "moreTraps1",
            "divineIntervention",
            "arrowShieldCost1",
            "betterArrowShield"
        ],
        "ability
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/classes` — The five classes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/classes"
```

**Response:**
```json
{
    "data": {
        "count": 5,
        "classes": [
            {
                "id": "archer",
                "lore": null,
                "name": "Archer (Hunter)",
                "overall_difficulty": 1
            },
            {
                "id": "warrior",
                "lore": null,
                "name": "Warrior (Knight)",
                "overall_difficulty": 2
            },
            {
                "id": "assassin",
                "lore": null,
                "name": "Assassin (Ninja)",
                "overall_difficulty": 2
            },
            {
                "id": "mage",
                "lore": null,
                "name": "Mage (Dark Wizard)",
                "overall_difficulty": 1
            },
            {
                "id": "shaman",
                "lore": null,
                "name": "Shaman (Skyseer)",
                "overall_difficulty": 3
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:30.156Z",
        "request_id": "3521bab1-76f5-40be-a3a1-2f17542447ee"
    },
    "status": "ok",
    "message": "Classes retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wynncraft-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Wynncraft (the Minecraft MMORPG). /v1/player?username=Salted = a player's rank, playtime, guild and global stats (total level, mobs killed, chests, quests, wars, PvP); /v1/guild?name=Avicia (or prefix=AVO) = a guild's level, members, territories & wars; /v1/leaderboard?type=totalGlobalLevel = a ranked leaderboard (also guildLevel, combatGlobalLevel, warsCompletion, mining/fishing/woodcuttingLevel, …); /v1/item?query=Idol = search the item database (type, rarity, level & class requirement); /v1/classes = the five classes; /v1/abilities?class=archer = a class's ability tree. Official Wynncraft data.",
        "source": "Wynncraft official API (api.wynncraft.com)",
        "endpoints": [
            "/v1/player",
            "/v1/guild",
            "/v1/leaderboard",
            "/v1/item",
            "/v1/classes",
            "/v1/abilities",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:30.221Z",
        "request_id": "a8097eec-0763-40e1-8f00-2eeb88240746"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/wynncraft-api
OpenAPI spec: https://www.oanor.com/api/wynncraft-api/openapi.json