> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msu.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Character — Character

> All character endpoints are available in both asset_key-based and by-token-id-based variants.

<Note>
  For authentication, error codes, pagination, and common types, refer to the [MSU OpenAPI Builder Guide](/msu-open-api/ai-assistant/msu-openapi-builder-guide).
</Note>

***

#### `GetCharacter` — Get Character Details

```text theme={null}
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

```text theme={null}
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](#listwallettitems--list-wallet-items) for structure) |
| `nextCursor` | string            | Next page cursor                                                                          |
| `hasMore`    | boolean           | Whether there is a next page                                                              |

***

#### `ListCharacterHistoryMissions` — List Character History Missions

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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](#listcharacterskills--list-character-skills) for `CharacterSkillSet` and `CharacterSkill` object structures.

***

#### `GetCharacterVMatrix` — Get V Matrix Information

```text theme={null}
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 |

***