Goblin Exchange API

Let your AI agent read this site's data: the WoW Forever auction house market, the advisor's flip/buy/craft brief, the item index with sources, the talent trees, and your own characters, upgrades and talent builds.

The API only serves what this site already holds. It never talks to Blizzard and cannot log in to the game or the Battle.net API for you. Prices are as fresh as the site (about hourly). Agents can read /llms.txt or /api/openapi.json to set themselves up.

Your keys

Two kinds of routes

public Market, advisor, items and talents are public static JSON. No key needed, and they don't count against any limit.

key Your characters, upgrades, talent builds, item search and import need a key: Authorization: Bearer gex_.... A key only ever sees its own Battle.net account's data.

export GEX_KEY=gex_your_key_here
curl -s -H "Authorization: Bearer $GEX_KEY" https://heyfatguy.com/api/v1/me

Public data (no key)

curl -s https://heyfatguy.com/api/v1/advisor | jq '.brief.picks[] | {action, name, size_gold, confidence}'
curl -s https://heyfatguy.com/api/v1/market | jq '[.items[] | select(.signal=="BUY")] | sort_by(-.flip.profit) | .[:10] | map({id, name, ask, mv, sold_day})'
curl -s https://heyfatguy.com/api/v1/item/2589 | jq '.history[-1]'
curl -s https://heyfatguy.com/api/v1/talents/paladin | jq 'keys'

Your data and search (key)

items/search params

curl -s -H "Authorization: Bearer $GEX_KEY" https://heyfatguy.com/api/v1/characters
curl -s -H "Authorization: Bearer $GEX_KEY" "https://heyfatguy.com/api/v1/upgrades" | jq '.characters[] | .note.text'
curl -s -H "Authorization: Bearer $GEX_KEY" "https://heyfatguy.com/api/v1/items/search?slot=1&min=20&max=30&class=paladin&role=ret&raids=0&limit=10"
curl -s -H "Authorization: Bearer $GEX_KEY" "https://heyfatguy.com/api/v1/items/search?q=lion&onAh=1&sort=price"
curl -s -X POST -H "Authorization: Bearer $GEX_KEY" -H "Content-Type: application/json" \
  --data @chars.json https://heyfatguy.com/api/v1/import

Limits

• Per key: 30 requests a minute and 1,000 a day (UTC day). All keys together: 2,000 a day. Over a limit you get 429 with a Retry-After header in seconds. Responses carry X-RateLimit-Remaining-Minute and X-RateLimit-Remaining-Day.
• Up to 5 keys per account. Public routes are static files with no limit, but cache them: the data changes about hourly (see last in the market).
• Why so low: the site runs on Netlify's free plan, 125,000 function runs a month for everything (the site's own pages spend some) and 100 GB of bandwidth. 2,000 key calls a day is about 60,000 a month, which leaves room for the site.

Errors and CORS

Every error on a key route is JSON: {"error": {"status": 401, "code": "unauthorized", "message": "..."}}. Codes: 400 bad_request, 401 unauthorized (no key, unknown or revoked key), 403 forbidden (missing scope, or the account left the allowlist), 404 not_found, 405 method_not_allowed, 413 too_large, 415 unsupported_media_type, 429 rate_limited, 502 upstream (site data missing). Static public routes give a plain 404 for a missing item.

CORS is open (Access-Control-Allow-Origin: *) on every /api/v1 route and the public data, so a browser-based agent can call it. Keys travel in the Authorization header only, never in the URL and never with cookies.

Getting a key

1. Log in at heyfatguy.com with Battle.net. If you're not on the friends list yet, the header shows your account id: send it to Kewk.
2. Once you're added, come back here and press Create key. Tick import only if your agent should push character snapshots.
3. Copy the key right away; it's shown once. The site stores only a hash.
4. Give it to your agent as Authorization: Bearer gex_.... Revoke it here any time; it stops working on the next request.

Fan site, not affiliated with or endorsed by Blizzard Entertainment. World of Warcraft is a trademark of Blizzard Entertainment.