MSU OpenAPI Builder Guide - MapleStory Universe

Version: v1rc1
Audience: Builders (external service/app developers) calling MSU OpenAPI

Start with AIPaste this prompt into your AI assistant (ChatGPT, Claude, Cursor, etc.) to load this guide as context:

Read from https://docs.msu.io/msu-open-api/ai-assistant/msu-openapi-builder-guide.md so I can ask questions about it.

1. Overview

MSU OpenAPI provides external builders with character, item, account, and search data from the MSU Marketplace.

Item	Value
Base URL	`https://openapi.msu.io`
Protocol	HTTPS
Encoding	JSON (camelCase field names)
Version path prefix	`/v1rc1/`

asset_key vs token_id

Identifier	Description
`asset_key`	Internal identifier that always exists regardless of minting status
`token_id`	Issued only after NFT minting. Calling a `by-token-id` endpoint on an unminted target returns `NOT_FOUND(3)`

2. Authentication

Pass your API key in the request header for all requests.

x-nxopen-api-key: <YOUR_API_KEY>

Endpoints requiring user authentication (account, search, etc.) additionally require a Bearer token.
Token issuance is done through a separate MSU OAuth authentication flow.

msu-authorization: <access_token>

3. Response Format

All APIs respond in the following format.

Success Response

{
  "success": true,
  "data": { ... },
  "traceId": "69faa56c000000006debcf3d9f4e0119"
}

Error Response

{
  "success": false,
  "error": {
    "code": 3,
    "message": "character not found"
  },
  "traceId": "69faa56c000000006debcf3d9f4e0119"
}

Field	Type	Always Present	Description
`success`	boolean	✅	Whether the request succeeded
`data`	object	On success only	Response data per endpoint
`error.code`	integer	On failure only	Error code (see table below)
`error.message`	string	On failure only	Error description (human-readable)
`traceId`	string	✅	Request trace ID. Always provide when contacting support

Note: All response field names are camelCase (proto field asset_key → JSON assetKey).

4. Error Codes

Common Errors

code	Constant	HTTP Status	Description	Common Scenarios	Resolution
`0`	`ERROR_CODE_UNSPECIFIED`	500	Unspecified error	Unexpected server error	Contact support with `traceId`
`2`	`ERROR_CODE_INVALID_ARGUMENT`	400	Invalid request argument	Missing required parameter, format error	Check request parameters
`3`	`ERROR_CODE_NOT_FOUND`	404	Requested target not found	Non-existent `assetKey`, `tokenId`, `walletAddress`	Verify identifier value
`4`	`ERROR_CODE_INTERNAL_ERROR`	500	Internal server error	Server failure	Retry or contact support
`5`	`ERROR_CODE_PERMISSION_DENIED`	403	Permission denied	API key scope exceeded	Check API key permissions
`6`	`ERROR_CODE_FAILED_PRECONDITION`	412	Unprocessable state	Operation not possible in current state	Check target resource state
`7`	`ERROR_CODE_ALREADY_PROCESS`	409	Already processed	Duplicate request	Check for duplicate requests
`9`	`ERROR_CODE_EXPECTATION_FAILED`	417	Expectation failed	Server-side precondition not met	Check `error.message` content
`10`	`ERROR_CODE_TOO_MANY_REQUEST`	429	Rate limit exceeded	Per-API-key rate limit exceeded	Retry with exponential backoff
`11`	`ERROR_CODE_CANCELED`	408	Request canceled/timeout	Processing time exceeded	Retry

Authentication Errors

code	Constant	HTTP Status	Description	Common Scenarios	Resolution
`8`	`ERROR_CODE_UNAUTHENTICATED`	401	Authentication failed	Missing or invalid `x-nxopen-api-key` header	Verify API key
`3001`	`ERROR_CODE_INVALID_AUTH_TOKEN`	401	Invalid MSU auth token	Invalid `access_token` provided	Re-issue token
`4001`	`ERROR_CODE_TOKEN_EXPIRED`	401	Token expired	`access_token` validity period exceeded	Re-issue with `refresh_token`
`4002`	`ERROR_CODE_TOKEN_EXPIRED_BY_OTHER_APP`	401	Token expired by another app in the same app_group	Another app in the same `app_group` logged in, invalidating the existing session	Re-login and re-issue token

Domain Errors

code	Constant	HTTP Status	Description	Common Scenarios	Resolution
`1001`	`ERROR_CODE_NOT_APPROVE_WALLET`	403	Wallet asset approval not granted	User has not granted the app access to wallet assets	Request wallet approval from user
`1002`	`ERROR_CODE_NOT_ENOUGH_NESO`	402	Insufficient on-chain NESO balance	Insufficient balance for NESO-consuming operations	Guide user to top up NESO
`2002`	`ERROR_CODE_NOT_FOUND_SYNERGY_APP`	404	Synergy app not found	Invalid `client_id` used	Verify `client_id`
`2003`	`ERROR_CODE_NOT_APPROVED_SYNERGY_APP_BY_USER`	403	User has not approved the synergy app	User has rejected or canceled app connection	Request app approval from user again

Error Handling Example

const res = await fetch(url, {
  headers: { 'x-nxopen-api-key': API_KEY }
});
const body = await res.json();

if (!body.success) {
  const { code, message } = body.error;
  switch (code) {
    case 3:    // NOT_FOUND
      console.error('Target not found');
      break;
    case 8:    // UNAUTHENTICATED
      console.error('API key verification needed');
      break;
    case 4001: // TOKEN_EXPIRED
    case 4002: // TOKEN_EXPIRED_BY_OTHER_APP
      await refreshAccessToken();
      break;
    case 10:   // TOO_MANY_REQUEST
      await delay(Math.pow(2, attempt) * 1000); // Exponential Backoff
      break;
    default:
      console.error(`Error (code: ${code}): ${message}`);
      console.error('traceId:', body.traceId); // Always provide when contacting support
  }
}

5. Pagination

Three pagination methods are used depending on the API.

Cursor Pagination

Used by most list APIs. Page size is fixed per API. Request Parameters

Parameter	Type	Description
`cursor`	string	`nextCursor` value from the previous response. Omit for the first page

Response Fields

Field	Type	Description
`nextCursor`	string	Cursor to use for the next page request
`hasMore`	boolean	Whether there is a next page

Page Number Pagination

Used by Search endpoints. Request Parameters (paginationParam)

Parameter	Type	Description
`pageNo`	integer	Page number (starting from 1)
`pageSize`	integer	Results per page

Response Fields (paginationResult)

Field	Type	Description
`totalCount`	integer	Total result count
`pageSize`	integer	Results per page
`currPageNo`	integer	Current page number
`isLastPage`	boolean	Whether this is the last page

Scroll Pagination

Used for collection queries. Request Parameters (paginationParam)

Parameter	Type	Description
`lastKey`	string	`lastKey` from the previous response. Omit for the first request
`pageSize`	integer	1–200 (default: 10)

Response Fields (paginationResult)

Field	Type	Description
`totalCount`	integer	Total result count
`pageSize`	integer	Results per page
`lastKey`	string	Key to use for the next page request
`isLastPage`	boolean	Whether this is the last page

6. Common Types

Type definitions commonly used across multiple endpoints.

`Category` Object

Field	Type	Description
`categoryNo`	integer	Category number
`label`	string	Category label
`tier0`	CategoryTier	Tier0 classification (NFT / FT / Character)
`tier1`	CategoryTier	Tier1 major classification
`tier2`	CategoryTier	Tier2 mid classification
`tier3`	CategoryTier	Tier3 minor classification

CategoryTier Object

Field	Type	Description
`label`	string	Classification name
`code`	string	Classification code

`TokenType` Enum

Value	Description
`TOKEN_TYPE_UNSPECIFIED` (0)	Unspecified
`TOKEN_TYPE_NFT_ITEM` (1)	NFT item
`TOKEN_TYPE_FT_ITEM` (2)	FT item
`TOKEN_TYPE_NFT_CHARACTER` (3)	NFT character
`TOKEN_TYPE_NFT_NICKNAME` (4)	NFT nickname

7. API Reference

Refer to the links below for detailed API documentation by category.

Category	Document Link	Key APIs
Account	account	NESO balance, currencies, collection, item/character list
Character	character	Character details, stats, equipped gear, skills, V Matrix, etc.
Item	item	NFT item details, history queries
GameMeta	gamemeta	Item/skill/set/quest metadata, V Matrix node skills
Enhancement	enhancement	Enhancement price queries
Rewards	rewards	Reward/raffle status, character raffle history, layer static data
Resource	resource	MCP proxy requests

Account

API	Endpoint	Description
`GetNeso`	`GET /v1rc1/accounts/{walletAddress}/neso`	Get on-chain and off-chain NESO balance for a wallet
`ListCurrency`	`GET /v1rc1/accounts/{walletAddress}/currencies`	Get list of currency types and balances linked to a wallet
`ListCollection`	`GET /v1rc1/accounts/{walletAddress}/collection`	Get NFT collection list held by a wallet (scroll pagination)
`ListWalletItems`	`GET /v1rc1/accounts/{walletAddress}/items`	Get item list held by a wallet (cursor pagination)
`ListCharacters`	`GET /v1rc1/accounts/{walletAddress}/characters`	Get character list linked to a wallet (cursor pagination)

Character

API	Endpoint	Description
`GetCharacter`	`GET /v1rc1/characters/{assetKey}`	Get character details (stats, equipped gear, abilities, etc.)
`GetCharacter` (by token)	`GET /v1rc1/characters/by-token-id/{tokenId}`	Get character details by token ID
`ListCharacterHoldingItems`	`GET /v1rc1/characters/{assetKey}/items`	Get list of items in character’s inventory
`ListCharacterHistoryMissions`	`GET /v1rc1/characters/{assetKey}/history-missions`	Get character history mission list
`ListCharacterQuests`	`GET /v1rc1/characters/{assetKey}/quests`	Get character quest achievement information
`ListCharacterSkills`	`GET /v1rc1/characters/{assetKey}/skills`	Get character skill information
`ListCharacterHyperSkills`	`GET /v1rc1/characters/{assetKey}/hyper-skill`	Get character hyper skill information
`GetCharacterVMatrix`	`GET /v1rc1/characters/{assetKey}/vmatrix`	Get V Matrix slot and V Core information

by-token-id variant endpoints are available identically for each API.

Item

API	Endpoint	Description
`GetNftItem`	`GET /v1rc1/items/{assetKey}`	Get NFT item details (stats, enhancement, potential, etc.)
`GetNftItem` (by token)	`GET /v1rc1/items/by-token-id/{tokenId}`	Get NFT item details by token ID
`ListNftItemHistoryMissions`	`GET /v1rc1/items/{assetKey}/history-missions`	Get full item history mission list
`ListNftItemHistoryMissionsRepresentative`	`GET /v1rc1/items/{assetKey}/history-missions/representative`	Get representative item history mission list

GameMeta

API	Endpoint	Description
`GetItemMetadata`	`GET /v1rc1/gamemeta/items/{itemId}`	Get game metadata by item ID
`GetItemCategory`	`GET /v1rc1/gamemeta/items/{itemId}/category`	Get item category classification information
`GetItemSet`	`GET /v1rc1/gamemeta/items/{itemId}/set`	Get set effect information for the item’s set
`ListEquipExclusiveItems`	`GET /v1rc1/gamemeta/items/{itemId}/exclusive`	Get list of items that cannot be equipped simultaneously
`GetQuestMetadata`	`GET /v1rc1/gamemeta/quests/{questId}`	Get quest metadata
`GetSkillMetadata`	`GET /v1rc1/gamemeta/skills/{skillId}`	Get skill metadata
`GetVMatrixNodeSkill`	`GET /v1rc1/gamemeta/vmatrix/{nodeId}`	Get V Matrix node skill information

Enhancement

API	Endpoint	Description
`GetCurrentPrice`	`GET /v1rc1/enhancement/items/{itemId}/dynamicprice`	Get current Starforce/Potential enhancement price for an item

Rewards

API	Endpoint	Description
`GetRewardInformation`	`POST /v1rc1/msn/rewards/{worldId}`	Get NFT drop probability and inventory status for fields/bosses/content
`GetRewardHistory`	`POST /v1rc1/msn/rewards/{worldId}/history`	Get reward history within 30 days after a raffle
`GetCharacterRaffleInformation`	`GET /v1rc1/msn/characters/{characterAssetKey}/raffles`	Get character raffle participation status (before drawing)
`GetCharacterRaffleHistory`	`GET /v1rc1/msn/characters/{characterAssetKey}/raffles/history`	Get character raffle participation history (up to 30 days after drawing)
`GetLayerStaticData`	`POST /v1rc1/msn/layers/static`	Get layer static data such as level range and name
`GetServerInformation`	`GET /v1rc1/msn/server`	Get reward server status by world

Resource

API	Endpoint	Description
`McpCall`	`POST /v1rc1/resource/mcp`	Proxy JSON-RPC 2.0 request to MCP server

8. Contact

When reporting an API error, always include the traceId from the response. 　

​1. Overview

​2. Authentication

​3. Response Format

​Success Response

​Error Response

​4. Error Codes

​Common Errors

​Authentication Errors

​Domain Errors

​Error Handling Example

​5. Pagination

​Cursor Pagination

​Page Number Pagination

​Scroll Pagination

​6. Common Types

​Category Object

​TokenType Enum

​7. API Reference

​Account

​Character

​Item

​GameMeta

​Enhancement

​Rewards

​Resource

​8. Contact

1. Overview

2. Authentication

3. Response Format

Success Response

Error Response

4. Error Codes

Common Errors

Authentication Errors

Domain Errors

Error Handling Example

5. Pagination

Cursor Pagination

Page Number Pagination

Scroll Pagination

6. Common Types

`Category` Object

`TokenType` Enum

7. API Reference

Account

Character

Item

GameMeta

Enhancement

Rewards

Resource

8. Contact