Character — Character - MapleStory Universe

For authentication, error codes, pagination, and common types, refer to the MSU OpenAPI Builder Guide.

`GetCharacter` — Get Character Details

GET /v1rc1/characters/{assetKey}
GET /v1rc1/characters/by-token-id/{tokenId}

Returns full details of a character. Path Parameters

Parameter	Type	Description
`assetKey`	string	Internal character identifier
`tokenId`	string	NFT token ID (by-token-id endpoint)

Response data

Field	Type	Description
`character.assetKey`	string	Character asset key
`character.category`	Category	Character classification
`character.tokenInfo`	TokenInfo	Minting information (null if not minted)
`character.statusV2`	CharacterStatus	Character status
`character.owner.walletAddress`	string	Owner’s wallet address
`character.image`	CharacterImage	Character image information
`character.common.name`	string	Character name
`character.common.level`	integer	Level
`character.common.world.code`	integer	World code
`character.common.world.name`	string	World name
`character.common.job.classCode`	integer	Class code
`character.common.job.className`	string	Class name
`character.common.job.jobCode`	integer	Job code
`character.common.job.jobName`	string	Job name
`character.common.nesolet`	string	Off-chain NESO
`character.common.exp`	string	Current experience
`character.common.totalExp`	string	Total experience
`character.common.expr`	string	Experience percentage
`character.common.gender`	integer	Gender (0: Male, 1: Female)
`character.common.popularity`	integer	Popularity
`character.common.honorExp`	integer	Honor points
`character.apStat`	ApStat	Stat information
`character.hyperStat`	HyperStat	Hyper stat information
`character.ability`	Ability	Ability information
`character.wearing`	Wearing	Equipped gear information

TokenInfo Object

Field	Type	Description
`tokenId`	string	NFT token ID
`tokenStandard`	string	Token standard
`mintingNo`	integer	Minting number
`tokenType`	TokenType	Token type

CharacterStatus Object

Field	Type	Description
`usageStatus`	CharacterUsageStatus	Character usage status
`isMinted`	boolean	Whether minted
`linkedDapp`	string[]	List of linked dApps

CharacterUsageStatus Values

Value	Description
`CHARACTER_USAGE_STATUS_UNSPECIFIED` (0)	Unknown
`CHARACTER_USAGE_STATUS_TRADABLE` (1)	Tradable
`CHARACTER_USAGE_STATUS_ON_SALE` (2)	On sale
`CHARACTER_USAGE_STATUS_IN_USE` (3)	In use in-game (dApp linked)
`CHARACTER_USAGE_STATUS_BURNED` (4)	Burned (character deleted)

CharacterImage Object

Field	Type	Description
`avatarParam`	string	Avatar parameters (for image rendering)
`imageUrl`	string	Character image URL

ApStat Object Each field is either ApStatRecord or ApStatRecordFloat. ApStatRecord Object

Field	Type	Description
`total`	integer	Aggregated stat value

ApStatRecordFloat Object

Field	Type	Description
`total`	float	Aggregated stat value (%)

Field	Type	Description
`str`, `dex`, `int`, `luk`	ApStatRecord	Base stats
`hp`, `mp`	ApStatRecord	Max HP/MP
`att`, `magicAtt`	ApStatRecord	Attack power / Magic attack
`criticalRate`	ApStatRecord	Critical rate
`damage`	ApStatRecordFloat	Damage (%)
`bossMonsterDamage`	ApStatRecordFloat	Boss damage (%)
`finalDamage`	ApStatRecordFloat	Final damage (%)
`ignoreDefence`	ApStatRecordFloat	Defense ignore (%)
`criticalDamage`	ApStatRecordFloat	Critical damage (%)
`buffDurationRate`	ApStatRecord	Buff duration increase rate
`abnormalStatusResistance`	ApStatRecord	Abnormal status resistance
`defence`	ApStatRecord	Defense
`speed`	ApStatRecord	Movement speed
`jump`	ApStatRecord	Jump
`knockbackResistance`	ApStatRecord	Knockback resistance
`normalEnemyDamage`	ApStatRecordFloat	Normal monster damage (%)
`cooldownReduction`	ApStatRecord	Skill cooldown reduction (seconds)
`cooldownReductionRate`	ApStatRecord	Skill cooldown reduction rate (%)
`cooldownNotApplied`	ApStatRecord	Chance of cooldown not applied (%)
`ignoreElementalResistance`	ApStatRecordFloat	Elemental resistance ignore (%)
`additionalStatusDamage`	ApStatRecordFloat	Additional damage from status effects (%)
`summonDurationIncrease`	ApStatRecord	Summon duration increase (%)
`starforce`	ApStatRecord	Starforce
`bonusExp`	ApStatRecordFloat	Bonus experience (%)
`attackSpeed`	ApStatRecord	Attack speed
`arcaneForce`	ApStatRecord	Arcane Force
`combatPower`	integer (int64)	Combat power

HyperStat Object Each field is of type HyperStatRecord. HyperStatRecord Object

Field	Type	Description
`code`	integer	Hyper stat code
`desc`	string	Hyper stat description
`level`	integer	Hyper stat level

Field	Description
`str`, `dex`, `int`, `luk`	Base stats
`maxHp`, `maxMp`	Max HP/MP
`criticalRate`, `criticalDamage`	Critical rate / damage
`ignoreDefence`	Defense ignore
`damage`, `bossMonsterDamage`, `normalMonsterDamage`	Damage-type stats
`abnormalStatusResistance`	Abnormal status resistance
`attackAndMagicAttack`	Attack power / Magic attack
`expEarned`	Experience gain

Ability Object

Field	Type	Description
`ability1`	AbilityRecord	First ability
`ability2`	AbilityRecord	Second ability
`ability3`	AbilityRecord	Third ability

AbilityRecord Object

Field	Type	Description
`grade`	integer	Grade
`code`	integer	Ability code
`desc`	string	Ability description
`values`	double[]	List of values
`level`	integer	Level

Wearing Object

Field	Type	Description
`equip`	EquipWearings	Equipment slots (cap, faceAcc, eyeAcc, earAcc, clothes, pants, shoes, gloves, cape, subWeapon, weapon, ring1–4, pendant1–2, medal, belt, shoulder, pocket, android, machineHeart, badge, emblem)
`decoEquip`	DecoWearings	Cosmetic slots (cap, faceAcc, eyeAcc, earAcc, clothes, pants, shoes, gloves, cape, subWeapon, weapon, ring1–4, face, skin, hair)
`pet`	PetWearings	Pet slots (pet1, pet2, pet3 — each slot is `Pet` type, not `Gear`)
`arcaneSymbols`	EquippedArcaneSymbols	Equipped arcane symbol information

Pet Object (each slot in PetWearings)

Field	Type	Description
`itemId`	integer	Pet item ID
`tokenId`	string	NFT token ID
`assetKey`	string	Internal item identifier
`mintable`	boolean	Whether mintable
`petAcc`	Gear	Equipped pet accessory (null if none)
`imageUrl`	string	Pet image URL

Gear Object (each slot in EquipWearings / DecoWearings)

Field	Type	Description
`assetKey`	string	Internal item identifier
`itemId`	integer	Item meta ID
`tokenId`	string	NFT token ID
`mintable`	boolean	Whether mintable
`imageUrl`	string	Image URL
`expiredDate`	string (ISO8601)	Expiry date/time (optional)

EquippedArcaneSymbols Object

Field	Type	Description
`totalArcaneForce`	integer	Total Arcane Force
`totalStat`	map<string, integer>	Primary stat bonuses (str/dex/int/luk)
`slots`	ArcaneSymbol[]	Equipped arcane symbol list (always 3 returned; empty slots are null)

ArcaneSymbol Object

Field	Type	Description
`itemId`	integer	Arcane symbol item ID
`imageUrl`	string	Image URL
`level`	integer	Symbol level
`maxLevel`	integer	Maximum level (fixed: 20)
`currentExp`	integer	Current accumulated symbol count
`totalExp`	integer	Total symbols needed to level up
`arcaneForce`	integer	Arcane Force
`stat`	map<string, integer>	Primary stat bonuses

Common Errors

code	Description
`3`	`assetKey` or `tokenId` does not exist

`ListCharacterHoldingItems` — List Character Items

GET /v1rc1/characters/{assetKey}/items
GET /v1rc1/characters/by-token-id/{tokenId}/items

Returns the list of items held by the character. Fixed page size of 20. Path Parameters

Parameter	Type	Description
`assetKey`	string	Character asset key (`assetKey` endpoint)
`tokenId`	string	NFT token ID (`by-token-id` endpoint)

Query Parameters (optional)

Parameter	Type	Description
`cursor`	string	Cursor (omit on first request)
`categoryNo`	integer	Filter by item category number

Response data

Field	Type	Description
`elements`	NftItemElement[]	List of items (see ListWalletItems for structure)
`nextCursor`	string	Next page cursor
`hasMore`	boolean	Whether there is a next page

`ListCharacterHistoryMissions` — List Character History Missions

GET /v1rc1/characters/{assetKey}/history-missions
GET /v1rc1/characters/by-token-id/{tokenId}/history-missions

Returns the history mission information for a character. Supports category filtering with a fixed page size of 20. Path Parameters

Parameter	Type	Description
`assetKey`	string	Character asset key (`assetKey` endpoint)
`tokenId`	string	NFT token ID (`by-token-id` endpoint)

Query Parameters (optional)

Parameter	Type	Description
`cursor`	string	Cursor
`mainCategory`	HistoryMissionMainCategory	History main category
`subCategory`	HistoryMissionSubCategory	History sub category

Response data

Field	Type	Description
`historyMissions`	CharacterHistoryMission[]	List of history missions
`nextCursor`	string	Next page cursor
`hasMore`	boolean	Whether there is a next page

CharacterHistoryMission Object

Field	Type	Description
`charAssetKey`	string	Character asset key
`historyMissionId`	integer	Mission ID
`historyMissionTitle`	string	Mission title
`mainCategory`	HistoryMissionMainCategory	Main category
`subCategory`	HistoryMissionSubCategory	Sub category
`achievedAt`	string (ISO8601)	Achievement time

HistoryMissionMainCategory Values

Value	Description
`UNSPECIFIED` (0)	Unknown
`CHARACTER` (1)	Character
`ITEM` (2)	Item
`ADVENTURE` (3)	Adventure
`BATTLE` (4)	Battle
`BLOCKCHAIN` (5)	Blockchain
`SOCIAL` (6)	Social

HistoryMissionSubCategory Values

Value	Description
`UNSPECIFIED` (0)	Unknown
`CHARACTER_LEVEL` (10)	Character level
`JOB_ADVANCEMENT` (11)	Job advancement
`ABILITY` (12)	Ability
`ITEM_REWARD` (20)	Item reward
`STAR_FORCE` (21)	Starforce
`POTENTIAL` (22)	Potential
`BONUS_STAT` (23)	Bonus stat
`REGIONAL_QUEST` (30)	Regional quest
`PARTY_QUEST` (31)	Party quest
`BATTLE_FIELD` (40)	Battle field
`BATTLE_BOSS` (41)	Boss battle
`MU_LUNG_DOJO` (42)	Mu Lung Dojo
`MINTING` (50)	Minting
`EXCHANGE_CURRENCY` (51)	Currency exchange

`ListCharacterQuests` — List Character Quests

GET /v1rc1/characters/{assetKey}/quests
GET /v1rc1/characters/by-token-id/{tokenId}/quests

Returns the quest achievement information for a character. Path Parameters

Parameter	Type	Description
`assetKey`	string	Character asset key (`assetKey` endpoint)
`tokenId`	string	NFT token ID (`by-token-id` endpoint)

Response data

Field	Type	Description
`quests`	QuestSet[]	List of quest sets

QuestSet Object

Field	Type	Description
`questAreaCode`	integer	Quest area code
`questAreaName`	string	Quest area name
`questRecords`	QuestRecord[]	List of quest achievements

QuestRecord Object

Field	Type	Description
`questId`	integer	Quest ID
`questTitle`	string	Quest title
`questStatus`	QuestStatus	Quest status
`completedAt`	string (ISO8601)	Completion time

QuestStatus Values

Value	Description
`UNSPECIFIED` (0)	Unknown
`IN_PROGRESS` (1)	In progress
`COMPLETED` (2)	Completed

`ListCharacterSkills` — List Character Skills

GET /v1rc1/characters/{assetKey}/skills
GET /v1rc1/characters/by-token-id/{tokenId}/skills

Returns the skill information for a character. Path Parameters

Parameter	Type	Description
`assetKey`	string	Character asset key (`assetKey` endpoint)
`tokenId`	string	NFT token ID (`by-token-id` endpoint)

Response data

Field	Type	Description
`skills`	CharacterSkillSet[]	List of skill sets

CharacterSkillSet Object

Field	Type	Description
`tier`	integer	Skill tier
`skills`	CharacterSkill[]	List of skills

CharacterSkill Object

Field	Type	Description
`skillId`	integer	Skill ID
`skillName`	string	Skill name
`skillDescription`	string	Skill description
`skillMasterLevel`	integer	Skill master level
`skillLevel`	integer	Current skill level
`skillEffectDescription`	string	Effect description at current level
`skillImageUrl`	string	Skill image URL

`ListCharacterHyperSkills` — List Hyper Skills

GET /v1rc1/characters/{assetKey}/hyper-skill
GET /v1rc1/characters/by-token-id/{tokenId}/hyper-skill

Returns the hyper skill information for a character. Path Parameters

Parameter	Type	Description
`assetKey`	string	Character asset key (`assetKey` endpoint)
`tokenId`	string	NFT token ID (`by-token-id` endpoint)

Response data

Field	Type	Description
`skills`	CharacterSkillSet[]	List of hyper skill sets

See ListCharacterSkills for CharacterSkillSet and CharacterSkill object structures.

`GetCharacterVMatrix` — Get V Matrix Information

GET /v1rc1/characters/{assetKey}/vmatrix
GET /v1rc1/characters/by-token-id/{tokenId}/vmatrix

Returns the V Matrix slot and V Core information for a character. Path Parameters

Parameter	Type	Description
`assetKey`	string	Character asset key (`assetKey` endpoint)
`tokenId`	string	NFT token ID (`by-token-id` endpoint)

Response data

Field	Type	Description
`matrixPoint`	integer	Matrix points
`vCoreShardCount`	integer	V Core shard count
`vMatrixSlots`	VMatrixSlot[]	Slot information (always 24 returned)
`vMatrixNodes`	VMatrixNode[]	Owned V Core information (equipped and unequipped)

VMatrixSlot Object

Field	Type	Description
`pos`	integer	Slot index (0–23)
`enhance`	integer	Slot enhancement level
`openType`	SlotOpenType	Slot open type

SlotOpenType Values

Value	Description
`SLOT_UNKNOWN` (0)	Unknown
`SLOT_OPENED` (1)	Open slot
`SLOT_OPENED_BY_NESO` (2)	Slot opened with NESO
`SLOT_OPENABLE_BY_NESO` (3)	Slot openable with NESO
`SLOT_LOCKED` (4)	Locked slot

VMatrixNode Object

Field	Type	Description
`nodeId`	integer	Node ID
`level`	integer	Node level
`exp`	integer	Current experience
`nodeImageUrl`	string	Node image URL
`nodeType`	NodeType	Node type
`isEquipped`	boolean	Whether equipped
`equippedPos`	integer	Equipped slot position (-1 if not equipped)
`protectLock`	boolean	Whether enhancement protection is locked
`nodeSkills`	NodeSkill[]	List of linked skills (Boost Core: 3, Skill/Special Core: 1)
`expiredAt`	string (ISO8601)	Expiry date (valid for Special Cores only)

NodeType Values

Value	Description
`V_MATRIX_SKILL_NODE` (0)	Skill Core
`V_MATRIX_BOOST_NODE` (1)	Boost Core
`V_MATRIX_SPECIAL_NODE` (2)	Special Core

NodeSkill Object

Field	Type	Description
`skillId`	integer	Skill ID
`imageUrl`	string	Skill image URL

​GetCharacter — Get Character Details

​ListCharacterHoldingItems — List Character Items

​ListCharacterHistoryMissions — List Character History Missions

​ListCharacterQuests — List Character Quests

​ListCharacterSkills — List Character Skills

​ListCharacterHyperSkills — List Hyper Skills

​GetCharacterVMatrix — Get V Matrix Information

`GetCharacter` — Get Character Details

`ListCharacterHoldingItems` — List Character Items

`ListCharacterHistoryMissions` — List Character History Missions

`ListCharacterQuests` — List Character Quests

`ListCharacterSkills` — List Character Skills

`ListCharacterHyperSkills` — List Hyper Skills

`GetCharacterVMatrix` — Get V Matrix Information