OpenMLBB User Client / SDK Docs

POST Send Verification Code

/openmlbb/user/auth/send-vc

API Path: /api/user/auth/send-vc

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.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.send_vc(role_id=1234567890, zone_id=1234)
print(response)

Request Body Example

{
  "role_id": 1234567890,
  "zone_id": 1234
}

POST Login with Verification Code

/openmlbb/user/auth/login

Open Only This

API Path: /api/user/auth/login

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.

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.login(role_id=1234567890, zone_id=1234, vc="1234")
print(response)

Request Body Example

{
  "role_id": 1234567890,
  "zone_id": 1234,
  "vc": 1234
}

POST Logout

/openmlbb/user/auth/logout

Open Only This

API Path: /api/user/auth/logout

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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.logout(jwt="YOUR_JWT")
print(response)

GET User Info

/openmlbb/user/info

Open Only This

API Path: /api/user/info

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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.info(jwt="YOUR_JWT", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
lang	query	string	no	en

GET User Statistics

/openmlbb/user/stats

Open Only This

API Path: /api/user/stats

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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.stats(jwt="YOUR_JWT", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
lang	query	string	no	en

GET User Privacy Settings

/openmlbb/user/privacy/settings

Open Only This

API Path: /api/user/privacy/settings

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).

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.privacy_settings(jwt="YOUR_JWT", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
lang	query	string	no	en

POST Update User Privacy Settings

/openmlbb/user/privacy/settings

Open Only This

API Path: /api/user/privacy/settings

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).

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.update_privacy_settings(jwt="YOUR_JWT", body={...}, visibility="visible", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
visibility	query	string	yes	-
lang	query	string	no	en

GET User Season List

/openmlbb/user/season

Open Only This

API Path: /api/user/season

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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.season(jwt="YOUR_JWT", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
lang	query	string	no	en

GET User Matches

/openmlbb/user/matches

Open Only This

API Path: /api/user/matches

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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.matches(jwt="YOUR_JWT", sid=1, limit=10, last_cursor="value", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
sid	query	integer	yes	-
limit	query	integer	no	10
last_cursor	query	string	no	-
lang	query	string	no	en

GET User Match Details

/openmlbb/user/matches/{match_id}

Open Only This

API Path: /api/user/matches/{match_id}

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:
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:
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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.match_detail(1234567890, jwt="YOUR_JWT", sid=1, lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
match_id	path	integer	yes	-
sid	query	integer	yes	-
lang	query	string	no	en

GET User Frequent Heroes

/openmlbb/user/heroes/frequent

Open Only This

API Path: /api/user/heroes/frequent

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:
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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.heroes_frequent(jwt="YOUR_JWT", sid=1, limit=5, last_cursor="value", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
sid	query	integer	yes	-
limit	query	integer	no	5
last_cursor	query	string	no	-
lang	query	string	no	en

GET User Matches by Hero

/openmlbb/user/matches/hero/{hero_identifier}

Open Only This

API Path: /api/user/matches/hero/{hero_identifier}

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.

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.

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.matches_by_hero("miya", jwt="YOUR_JWT", sid=1, limit=10, last_cursor="value", lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
hero_identifier	path	string	yes	-
sid	query	integer	yes	-
limit	query	integer	no	10
last_cursor	query	string	no	-
lang	query	string	no	en

GET User Friends

/openmlbb/user/friends

Open Only This

API Path: /api/user/friends

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:

This endpoint is useful for:

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

This endpoint requires JWT. Pass the token via the SDK call argument jwt="YOUR_JWT".

Python Example

from OpenMLBB import OpenMLBB

client = OpenMLBB()
response = client.user.friends(jwt="YOUR_JWT", sid=1, lang="en")
print(response)

Path and Query Parameters

Name	In	Type	Required	Default
sid	query	integer	yes	-
lang	query	string	no	en