{
  "openapi": "3.0.3",
  "info": {
    "title": "Pokemon Dusk Reborn Stock Market API",
    "version": "1.0",
    "description": "Read-only prices for colored Pokemon variants (Shadow, Haunted, Frost, Glitter, Demon, Golden, Eternal, Baby) in Pokemon Dusk Reborn, a free fan-made Pokemon browser MMORPG. Every amount is in GC coins, the game's fictional in-game currency: not real money and not financial data. A reference price is what a level 5 copy has recently sold for between players, rebuilt about once an hour from completed trades, Auction House sales and Marketplace sales. No key is needed. Each client address may make about 60 requests a minute; over that the API answers 429 with Retry-After. The /pokedex endpoints list which forms of a Pokemon are registered in the game (names, form type, color, artwork) and use the same limits. The market and Pokedex data is available to AI clients through the MCP server at https://pkmnreborn.com/mcp (connection details: https://pkmnreborn.com/mcp/server-card). Not affiliated with Nintendo, Game Freak, Creatures or The Pokemon Company.",
    "contact": { "name": "Pokemon Dusk Reborn", "url": "https://pkmnreborn.com/" }
  },
  "servers": [{ "url": "https://pkmnreborn.com/api/v1" }],
  "externalDocs": { "description": "The Stock Market pages", "url": "https://pkmnreborn.com/stock-market" },
  "paths": {
    "/market": {
      "get": {
        "operationId": "listMarket",
        "summary": "List colored Pokemon with their reference prices",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 40, "pattern": "^[A-Za-z0-9 :.'-]{1,40}$" }, "description": "Part of a form name, with or without spaces." },
          { "name": "color", "in": "query", "schema": { "type": "string", "enum": ["Shadow", "Haunted", "Frost", "Glitter", "Demon", "Golden", "Eternal", "Baby"] }, "description": "Case-insensitive." },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "A Pokemon type such as Fire or Water. Case-insensitive." },
          { "name": "generation", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9 } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["trending", "price_desc", "price_asc", "change_desc", "change_asc", "name"], "default": "trending" }, "description": "trending = most sales in the last 30 days first, then most recorded sales, then name (the Stock Market page's default)." },
          { "name": "priced_only", "in": "query", "schema": { "type": "integer", "enum": [0, 1], "default": 0 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }
        ],
        "responses": {
          "200": { "description": "One page of forms.", "content": { "application/json": { "schema": { "type": "object", "required": ["api_version", "data", "pagination", "meta"], "properties": {
            "api_version": { "type": "string" },
            "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } },
            "pagination": { "$ref": "#/components/schemas/Pagination" },
            "meta": { "$ref": "#/components/schemas/Meta" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/NotReady" }
        }
      }
    },
    "/market/summary": {
      "get": {
        "operationId": "getMarketSummary",
        "summary": "Market totals, the last 30 days, and how prices are made",
        "responses": {
          "200": { "description": "Summary.", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "api_version": { "type": "string" },
            "data": { "$ref": "#/components/schemas/Summary" },
            "meta": { "$ref": "#/components/schemas/Meta" } } } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/NotReady" }
        }
      }
    },
    "/market/trending": {
      "get": {
        "operationId": "getMarketTrending",
        "summary": "The last 30 days: biggest risers, fallers and most traded",
        "description": "The same report as https://pkmnreborn.com/stock-market?tab=month.",
        "responses": {
          "200": { "description": "Monthly report.", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "api_version": { "type": "string" },
            "data": { "$ref": "#/components/schemas/Trending" },
            "meta": { "$ref": "#/components/schemas/Meta" } } } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/NotReady" }
        }
      }
    },
    "/market/{name}": {
      "get": {
        "operationId": "getPokemon",
        "summary": "One colored Pokemon form",
        "parameters": [{ "$ref": "#/components/parameters/Name" }],
        "responses": {
          "200": { "description": "The form.", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "api_version": { "type": "string" },
            "data": { "$ref": "#/components/schemas/Detail" },
            "meta": { "$ref": "#/components/schemas/Meta" } } } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/market/{name}/history": {
      "get": {
        "operationId": "getPokemonHistory",
        "summary": "One form's recorded sales and daily reference price",
        "parameters": [
          { "$ref": "#/components/parameters/Name" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "How many of the newest sales to return. The price series is always complete." }
        ],
        "responses": {
          "200": { "description": "Sales and price series.", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "api_version": { "type": "string" },
            "data": { "$ref": "#/components/schemas/History" },
            "meta": { "$ref": "#/components/schemas/Meta" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/pokedex/{species}/variants": {
      "get": {
        "operationId": "getPokedexSpeciesVariants",
        "summary": "Every registered form of one Pokemon species",
        "description": "Lists the forms registered in the game for a base species (Normal, Mega, Shiny and the colored forms Shadow, Haunted, Frost, Glitter, Demon, Golden, Eternal and Baby), with exact in-game names, form type, color and artwork URL. This is what exists in the game, not how many players own. Cached for an hour.",
        "parameters": [
          { "name": "species", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 }, "description": "The base species name, for example Mew or Lugia (not a colored form such as ShadowMew)." }
        ],
        "responses": {
          "200": { "description": "The registered forms.", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "api_version": { "type": "string" },
            "data": { "type": "object", "properties": {
              "species": { "type": "string" },
              "dex_number": { "type": "integer" },
              "page": { "type": "string", "format": "uri" },
              "count": { "type": "integer" },
              "variants": { "type": "array", "items": { "$ref": "#/components/schemas/PokedexVariant" } } } },
            "meta": { "type": "object" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/pokedex/variants": {
      "get": {
        "operationId": "lookupPokedexVariants",
        "summary": "Check whether named forms exist",
        "description": "Exact-name lookup for 1 to 25 in-game names such as FrostMegaLugia. Each result says registered, registered_artwork_missing (the record exists but its sprite file was not found) or not_registered (no record).",
        "parameters": [
          { "name": "names", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated exact in-game names, 1 to 25, for example FrostMegaLugia,GlitterMegaRegice." }
        ],
        "responses": {
          "200": { "description": "One result per requested name.", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "api_version": { "type": "string" },
            "data": { "type": "object", "properties": {
              "count": { "type": "integer" },
              "results": { "type": "array", "items": { "type": "object", "properties": {
                "requested": { "type": "string" },
                "status": { "type": "string", "enum": ["registered", "registered_artwork_missing", "not_registered"] },
                "name": { "type": "string", "nullable": true },
                "artwork_status": { "type": "string", "nullable": true, "enum": ["present", "missing_file", "external_unchecked", null] },
                "artwork_url": { "type": "string", "nullable": true, "format": "uri" } } } } } },
            "meta": { "type": "object" } } } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Name": { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 60 }, "description": "The form name, with or without the space: ShadowShellder or Shadow Shellder (URL-encoded). Case-insensitive." }
    },
    "responses": {
      "BadRequest": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "No such form, page or endpoint, or the Stock Market is not public.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotReady": { "description": "Market data is being prepared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "PokedexVariant": { "type": "object", "properties": {
        "name": { "type": "string", "description": "The exact in-game name, for example FrostMegaLugia." },
        "label": { "type": "string", "description": "A readable label, for example Frost Mega Lugia." },
        "species": { "type": "string" },
        "color": { "type": "string", "description": "Normal, Shiny, or one of the colored lines." },
        "form_type": { "type": "string", "enum": ["base", "mega", "mega_x", "mega_y", "unbound"] },
        "irregular_name": { "type": "boolean", "description": "True for names outside the usual pattern, such as EternalMewtwo(God)." },
        "artwork_url": { "type": "string", "nullable": true, "format": "uri" },
        "artwork_status": { "type": "string", "enum": ["present", "missing_file", "external_unchecked"] } } },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": {
        "code": { "type": "string", "enum": ["invalid_parameter", "not_found", "page_out_of_range", "method_not_allowed", "rate_limited", "not_ready"] },
        "message": { "type": "string" } } } } },
      "Currency": { "type": "object", "properties": {
        "code": { "type": "string", "enum": ["GC"] },
        "name": { "type": "string" },
        "fictional": { "type": "boolean", "enum": [true] },
        "note": { "type": "string" } } },
      "Meta": { "type": "object", "properties": {
        "currency": { "$ref": "#/components/schemas/Currency" },
        "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the prices were last rebuilt (UTC)." },
        "latest_sale": { "type": "string", "format": "date", "nullable": true, "description": "The newest sale included." },
        "refresh": { "type": "string", "enum": ["hourly"] },
        "source": { "type": "string", "format": "uri" },
        "docs": { "type": "string", "format": "uri" } } },
      "Pagination": { "type": "object", "properties": {
        "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } },
      "Price": { "type": "object", "nullable": true, "description": "Null when the form has no counted sale.", "properties": {
        "amount": { "type": "integer", "description": "GC coins (fictional)." },
        "currency": { "type": "string", "enum": ["GC"] },
        "basis": { "type": "string", "enum": ["level_5_copy"] } } },
      "Bonus": { "type": "object", "nullable": true, "properties": {
        "amount": { "type": "string", "example": "15%" }, "stat": { "type": "string", "example": "Attack" }, "text": { "type": "string", "example": "+15% Attack" } } },
      "Item": { "type": "object", "properties": {
        "name": { "type": "string", "example": "ShadowShellder", "description": "The game's form name (canonical id)." },
        "display_name": { "type": "string", "example": "Shadow Shellder" },
        "color": { "type": "string" },
        "dex": { "type": "integer", "nullable": true, "description": "National Dex number." },
        "generation": { "type": "integer", "nullable": true },
        "types": { "type": "array", "items": { "type": "string" } },
        "url": { "type": "string", "format": "uri" },
        "reference_price": { "$ref": "#/components/schemas/Price" },
        "change_30d_pct": { "type": "number", "nullable": true, "description": "Reference price now against 30 days earlier, in percent. Null when there is not enough history." },
        "recorded_sales": { "type": "integer", "description": "Counted sales on record (observed transactions)." },
        "sales_last_30d": { "type": "integer" },
        "copies_in_game": { "type": "integer", "nullable": true },
        "color_bonus": { "$ref": "#/components/schemas/Bonus" } } },
      "Detail": { "allOf": [{ "$ref": "#/components/schemas/Item" }, { "type": "object", "properties": {
        "price_status": { "type": "string", "enum": ["priced", "no_price_yet"] },
        "first_recorded_sale": { "type": "string", "format": "date", "nullable": true },
        "latest_recorded_sale": { "type": "string", "format": "date", "nullable": true },
        "promo": { "type": "object", "nullable": true, "properties": { "cost": { "type": "integer" }, "currency": { "type": "string", "enum": ["GC"] }, "started": { "type": "string", "format": "date", "nullable": true } } },
        "in_game_since_no_later_than": { "type": "string", "format": "date", "nullable": true },
        "image": { "type": "string", "format": "uri" } } }] },
      "Sale": { "type": "object", "properties": {
        "date": { "type": "string", "format": "date" },
        "date_kind": { "type": "string", "enum": ["completed", "listed"], "description": "Trades keep the day they went through; Auction House and Marketplace logs keep the listing day." },
        "venue": { "type": "string", "enum": ["trade", "auction_house", "marketplace"] },
        "level": { "type": "integer" },
        "coins": { "type": "integer", "description": "What this copy sold for, in GC coins (fictional)." } } },
      "History": { "type": "object", "properties": {
        "name": { "type": "string" }, "display_name": { "type": "string" }, "url": { "type": "string", "format": "uri" },
        "sales_total": { "type": "integer" },
        "sales": { "type": "array", "items": { "$ref": "#/components/schemas/Sale" } },
        "reference_price_series": { "type": "array", "description": "The estimated reference price of a level 5 copy after each day with evidence (the Stock Market chart line), plus the latest build.", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "reference_price": { "type": "integer" } } } } } },
      "Mover": { "type": "object", "properties": {
        "name": { "type": "string" }, "display_name": { "type": "string" }, "url": { "type": "string", "format": "uri" },
        "reference_price": { "type": "integer", "nullable": true },
        "reference_price_30d_ago": { "type": "integer", "nullable": true },
        "change_30d_pct": { "type": "number", "nullable": true },
        "sales_last_30d": { "type": "integer" },
        "coins_traded_last_30d": { "type": "integer", "nullable": true },
        "recorded_sales": { "type": "integer", "nullable": true } } },
      "Trending": { "type": "object", "properties": {
        "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } },
        "risers": { "type": "array", "items": { "$ref": "#/components/schemas/Mover" } },
        "fallers": { "type": "array", "items": { "$ref": "#/components/schemas/Mover" } },
        "most_traded": { "type": "array", "items": { "$ref": "#/components/schemas/Mover" } } } },
      "Summary": { "type": "object", "properties": {
        "forms_listed": { "type": "integer" },
        "forms_with_reference_price": { "type": "integer" },
        "colors": { "type": "array", "items": { "type": "string" } },
        "last_30_days": { "type": "object", "nullable": true, "properties": {
          "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" },
          "recorded_sales": { "type": "integer" }, "forms_traded": { "type": "integer" }, "coins_traded": { "type": "integer" },
          "forms_up": { "type": "integer" }, "forms_down": { "type": "integer" }, "forms_flat": { "type": "integer" }, "forms_new": { "type": "integer" } } },
        "updated_at": { "type": "string", "format": "date-time", "nullable": true },
        "latest_sale": { "type": "string", "format": "date", "nullable": true },
        "methodology": { "type": "object", "additionalProperties": { "type": "string" } } } }
    }
  }
}
