User Endpoints

Send an in-game verification code to the player's account, valid for 5 mins. This endpoint is part of the authentication flow and is used to validate ownership of a game account.

Request body:

• role_id: Player role identifier (Game ID).
• zone_id: Server zone identifier (Server ID).

The response confirms whether the verification code was successfully dispatched:

• code: Status code (0 indicates success).
• data: Empty string (no payload returned).
• msg: Message string (e.g., 'ok').

Useful for account authentication flows, linking user identity, and validating account ownership.

Authenticate the player using a verification code to obtain a JWT and session token. This endpoint completes the account login flow, establishes a secure session, and enables authorized access to user-specific resources.

Request body:

• role_id: Player role identifier.
• zone_id: Server zone identifier.
• vc: Verification code sent to the player via in-game mail, valid 5 mins.

The response includes authentication details:

• code: Status code (0 indicates success).
• data.jwt: JSON Web Token used for subsequent authenticated requests.
• data.token: Session token string.
• data.roleid: Player role ID.
• data.zoneid: Player zone ID.
• data.time: Timestamp of login.
• data.module, name, email, mobile, open_id: Metadata fields (may be empty depending on account).

The response confirms successful login and provides the credentials required for accessing other user endpoints.

Invalidate the player's session using the JWT obtained from /api/user/auth/login. This endpoint terminates the current authenticated session, ensuring that the JWT can no longer be used for authorized requests.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

The response confirms whether the logout was successful:

• code: Status code (0 indicates success).
• data: Empty string (no payload returned).
• msg: Message string (e.g., 'ok').

Note: Although the login response also includes a token field, only the JWT is required for logout. The server uses the JWT to invalidate the session.

Retrieve the authenticated player's base profile information using a valid JWT. Supports query parameter for localization (lang). Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• lang: Language code for localized content (default: en).

The response includes player details:

• avatar: Avatar image URL.
• name: Display name.
• level: Current player level.
• rank_level: Current rank level.
• history_rank_level: Highest historical rank level.
• reg_country: Registered country code.
• roleId: Player role identifier.
• zoneId: Server zone identifier.

Useful for displaying identity card information, verifying account ownership, and populating player profile data in client applications.

Retrieve the authenticated player's overall statistics using a valid JWT. Supports query parameter for localization (lang). Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• lang: Language code for localized content (default: en).

The response includes general player statistics:

• wc: Win Count (total matches won).
• tc: Total Count (total matches played).
• as: Average Score (overall performance rating, as/100).
• gt: Game Time (total play time duration in hours).
• mvpc: MVP Count (number of times player earned MVP).
• wsc: Win Streak Count (longest consecutive wins).

Hero-specific highlights:

• mo: Most Often (hero most damage dealt).
• hk: Highest Kills (hero with the most kills).
• ma: Most Assists (hero contributing the most assists).
• ms: Most Score (hero with the highest accumulated score).
• mdt: Most Damage Taken (hero absorbing the most damage).
• mg: Most Gold (hero earning the most gold).
• mtd: Most Total Damage (hero dealing the most damage overall).

Each hero highlight includes metadata such as:

• v: Value or statistic for the highlight. if ms is used, it calculates v/100.
• ts: Timestamp of the highlight.
• hid: Hero ID.
• n: Hero name.
• ix: Hero image URL.
• i2x: Large hero image URL.
• bid: Battle ID reference.

This endpoint is useful for:

• Analyzing overall player performance.
• Identifying favorite heroes.
• Showcasing personal achievements in MLBB.

Retrieve the authenticated player's privacy settings using a valid JWT. Supports query parameter for localization (lang). Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• lang: Language code for localized content (default: en).

The response includes:

• popup_shown: Whether the privacy popup has been shown to the user.
• privacy: Current privacy state (true/false).

Update the authenticated player's privacy settings using a valid JWT. Supports query parameter for localization (lang). Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• visibility: Visibility mode. Use visible to allow friends to view your profile, and invisible to hide your profile from friends. This parameter is required.
• lang: Language code for localized content (default: en).

Retrieve the authenticated player's season information using a valid JWT. Supports query parameter for localization (lang). Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• lang: Language code for localized content (default: en).

The response includes:

• sids: List of season identifiers representing the seasons in which the player has participated or has tracked statistics.

This endpoint is useful for:

• Displaying season history.
• Linking performance data to specific seasons.
• Enabling clients to fetch season-specific stats or achievements.

Retrieve the authenticated player's recent matches information using a valid JWT. Supports query parameters for season filtering, pagination, and localization. Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• sid: Season ID for filtering matches (must be a valid season ID from /api/user/season).
• limit: Maximum number of matches to retrieve (minimum: 1).
• last_cursor: Cursor for pagination. Use the value from pageInfo.nextCursor in the current response. If pageInfo.hasNext is false or pageInfo.nextCursor is empty, there is no next page.
• lang: Language code for localized content (default: en).

The response includes match details:

• sid: Season ID.
• bid: Battle ID (unique match reference).
• hid: Hero ID used in the match.
• k: Kills.
• d: Deaths.
• a: Assists.
• lid: Lane ID (1 EXP, 2 Mid, 3 Roam, 4 Jungle, 5 Gold).
• s: Score (performance rating for the match, s/100).
• mvp: MVP flag (1 if MVP, 0 otherwise).
• res: Result (1 = Win, 0 = Loss).
• ts: Timestamp of the match.
• hid_e: Hero entity metadata (hero ID, name, images).
• bid_s: String battle ID representation.

Pagination example:

First request: /api/user/matches?sid=40&limit=10&lang=en → response includes pageInfo.nextCursor = 4139649383291049463.

Second request: /api/user/matches?sid=40&limit=10&last_cursor=4139649383291049463&lang=en → retrieves the next page, using pageInfo.nextCursor from the current response.

Stop pagination when pageInfo.hasNext = false or pageInfo.nextCursor is empty.

The response also includes pagination metadata:

• pageInfo.nextCursor: Cursor value for the next page.
• pageInfo.hasNext: Boolean flag indicating if more results are available.
• pageInfo.count: Number of results returned in the current page.

This endpoint is useful for:

• Reconstructing match history.
• Analyzing player performance.
• Enabling clients to paginate reliably through a player's matches.

Retrieve the authenticated player's detailed match information using a valid JWT. Supports query parameters for season filtering and localization. Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Path parameters:

• match_id: Unique identifier of the match (from bid_s in /api/user/matches).

Query parameters:

• sid: Season ID for filtering (must be a valid season ID from /api/user/season).
• lang: Language code for localized content (default: en).

The response includes per-player match details:

• f: Team flag (1 = Team A, 2 = Team B).
• hid: Hero ID used in the match.
• rid: Role ID (unique player identifier).
• zid: Zone ID (server region).
• k: Kills.
• d: Deaths.
• a: Assists.
• tfr: Team Fight Rate (contribution ratio in team fights, tfr*100%).
• o: Output (total damage dealt or hero damage).
• op: Output Percentage (damage contribution relative to team).
• s: Score (performance rating, s/100).
• mvp: MVP flag (1 if MVP, 0 otherwise).
• its: Item IDs equipped during the match.
• its_e: Item entity metadata:
  • id: Item ID.
  • n: Item name.
  • ix: Item image URL.
  • i2x: Large item image URL.
• eq: Equipment slot indicator.
• ts: Timestamp of the match.
• bd: Battle duration (seconds).
• fk: First Kill flag (total kills in a team).
• fw: First Win flag (1 for Win, 0 for Loss).
• hid_e: Hero entity metadata:
  • id: Hero ID.
  • n: Hero name.
  • ix: Hero image URL.
  • i2x: Large hero image URL.
• hlvl: Hero level reached in the match.
• rname: Role name (localized string, e.g., 'ジャングラー').

This endpoint provides a full breakdown of each participant in the match, including:

• Hero choice.
• Performance stats (kills, deaths, assists, damage).
• Items built with metadata.
• Role assignment and team contribution.

It is useful for:

• Reconstructing match history.
• Analyzing team compositions.
• Evaluating player performance in detail.

Retrieve the authenticated player's frequent heroes information using a valid JWT. Supports query parameters for season filtering, pagination, and localization. Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• sid: Season ID for filtering frequent heroes (must be a valid season ID from /api/user/season).
• limit: Maximum number of heroes to retrieve (minimum: 1).
• last_cursor: Cursor for pagination. Use the value from pageInfo.nextCursor in the current response. If pageInfo.hasNext is false or pageInfo.nextCursor is empty, there is no next page.
• lang: Language code for localized content (default: en).

The response includes frequent hero usage details:

• hid: Hero ID.
• tc: Total Count (number of matches played with this hero).
• wc: Win Count (number of matches won with this hero).
• bs: Battle Score (average performance rating, bs/100).
• mr: Match Rating (accumulated rating points).
• mrp: Match Rating Percentage (rating contribution relative to overall performance).
• hid_e: Hero entity metadata:
  • id: Hero ID.
  • n: Hero name.
  • ix: Hero image URL.
  • i2x: Large hero image URL.
• p: Power score (weighted performance index for ranking frequent heroes, also called MMR).

Pagination example:

First request: /api/user/heroes/frequent?sid=37&limit=5&lang=en → response includes pageInfo.nextCursor = 11.

Second request: /api/user/heroes/frequent?sid=37&limit=5&last_cursor=11&lang=en → retrieves the next page, using pageInfo.nextCursor from the current response.

Stop pagination when pageInfo.hasNext = false or pageInfo.nextCursor is empty.

The response also includes pagination metadata:

• pageInfo.nextCursor: Cursor value for the next page.
• pageInfo.hasNext: Boolean flag indicating if more results are available.
• pageInfo.count: Number of results returned in the current page.

This endpoint is useful for:

• Analyzing which heroes a player uses most often.
• Tracking win rates and performance scores.
• Comparing hero usage across different seasons.

Retrieve the authenticated player's recent matches filtered by a specific hero using a valid JWT. Supports query parameters for season filtering, pagination, and localization. Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Path parameters:

• hero_identifier: Hero identifier as numeric hero ID or hero name. Accepts values like 30, Yi Sun-shin, or yisunshin.

Query parameters:

• sid: Season ID for filtering matches (must be a valid season ID from /api/user/season).
• limit: Maximum number of matches to retrieve (minimum: 1).
• last_cursor: Cursor for pagination. Use the value from pageInfo.nextCursor in the current response. If pageInfo.hasNext is false or pageInfo.nextCursor is empty, there is no next page.
• lang: Language code for localized content (default: en).

Response structure:

• code: Status code (0 indicates success).
• message: Response message from upstream service.
• traceID: Upstream trace identifier for request debugging/tracking.
• data: Main payload object.
  • pageInfo: Pagination metadata object.
    • nextCursor: Cursor value for the next page, used for pagination.
    • hasNext: Boolean flag indicating whether more results are available.
    • count: Number of results returned in the current page.
  • hi: Aggregated hero summary for the selected hero and season.
    • hid: Hero ID.
    • tc: Total Count (matches played with this hero).
    • wc: Win Count (matches won with this hero).
    • bs: Battle Score (average score; interpret as bs/100 when non-zero).
    • mr: Match Rating points for this hero.
    • mrp: Match Rating percentage/contribution.
    • hid_e: Hero metadata object.
      • id: Hero ID metadata.
      • n: Hero name.
      • ix: Hero image URL.
      • i2x: Large hero image URL.
    • p: Hero power/MMR-style value.
  • result: Array of match entries for this hero.
    • sid: Season ID.
    • bid: Battle ID (numeric).
    • hid: Hero ID used in that match.
    • k: Kills.
    • d: Deaths.
    • a: Assists.
    • lid: Lane ID (1 EXP, 2 Mid, 3 Roam, 4 Jungle, 5 Gold).
    • s: Match score/performance value (commonly interpreted as s/100).
    • mvp: MVP flag (1 if MVP, 0 otherwise).
    • res: Result (1 = Win, 0 = Loss).
    • ts: Match timestamp (unix time).
    • hid_e: Hero metadata object.
      • id: Hero ID metadata.
      • n: Hero name.
      • ix: Hero image URL.
      • i2x: Large hero image URL.
    • bid_s: String battle ID.

Pagination example:

First request: /api/user/matches/hero/17?sid=40&limit=10&lang=en

Next request: /api/user/matches/hero/17?sid=40&limit=10&last_cursor=<pageInfo.nextCursor>&lang=en

Stop pagination when pageInfo.hasNext = false or pageInfo.nextCursor is empty.

Retrieve the authenticated player's friends information using a valid JWT. Supports query parameters for season filtering and localization. Requires an Authorization header with the JWT from login.

Headers:

• Authorization: Bearer <jwt> (JWT obtained during login).

Query parameters:

• sid: Season ID for filtering friends (must be a valid season ID from /api/user/season).
• lang: Language code for localized content (default: en).

The response includes friend statistics and metadata:

• bfs: Best Friends (highlighted or prioritized friends list, may be null).
• wfs: Weekly Friends (friends interacted with recently, may be empty).
• fs: Friends list entries, each containing:
  • f: Friend object with identifiers:
    • rid: Role ID (unique player identifier).
    • zid: Zone ID (server region).
    • n: Name (may be empty if private).
    • ax: Avatar URL (may be empty).
    • pri: Privacy flag (true if details are hidden).
  • frid: Friend Role ID (unique identifier for the friend).
  • fzid: Friend Zone ID (server region for the friend).
  • cl: Current Level of the friend.
  • l: Level (same as cl, sometimes duplicated).
  • tbc: Total Battle Count (matches played together).
  • twc: Total Win Count (matches won together).

This endpoint is useful for:

• Displaying a player's friend list.
• Tracking shared match history.
• Analyzing cooperative performance with friends across different seasons.