mlbb-sdk

TypeScript SDK for the unofficial MLBB Stats API — hero statistics, academy data, player profiles, and more for Mobile Legends: Bang Bang.

Installation

npm install mlbb-sdk

Quick Start

import { createMlbbClient } from 'mlbb-sdk'

const client = createMlbbClient({ lang: 'en' })

const heroes = await client.mlbb.getHeroes()
const ranks = await client.mlbb.getHeroRanks({ rank: 'mythic', days: 7 })
const items = await client.academy.getEquipmentExpanded()

Configuration

const client = createMlbbClient({
  lang: 'ru',             // default language (default: 'en')
  defaultPageSize: 50,    // results per page (default: 20)
  timeout: 15000,         // request timeout in ms (default: 10000)
  retries: 2,             // auto-retries on failure (default: 1)
  headers: {},            // extra HTTP headers
})

Supported Languages

en, id, ru, es, pt, tr, ar, de, fr, it, ja, ko, th, vi, zh-CN, zh-TW

Modules

client.mlbb — Hero Data

// List all heroes
const heroes = await client.mlbb.getHeroes()

// Rank statistics (pick/ban/win rates)
const ranks = await client.mlbb.getHeroRanks({ rank: 'mythic', days: 7, sortField: 'win_rate' })

// Filter by role and lane
const mages = await client.mlbb.getHeroesByPosition({ role: 'mage', lane: 'mid' })

// Hero details
const hero = await client.mlbb.getHero('Fanny')
const stats = await client.mlbb.getHeroStats(17, { rank: 'legend' })
const combos = await client.mlbb.getHeroSkillCombos(17)
const trends = await client.mlbb.getHeroTrends(17, { pastDays: 30 })

// Relations and counters
const relations = await client.mlbb.getHeroRelations(17)
const counters = await client.mlbb.getHeroCounters(17, { rank: 'mythic', days: 7 })
const synergy = await client.mlbb.getHeroCompatibility(17, { rank: 'mythic', days: 7 })

client.academy — Game Reference Data

const version = await client.academy.getVersion()
const roles = await client.academy.getRoles()
const equipment = await client.academy.getEquipment()
const expanded = await client.academy.getEquipmentExpanded()
const spells = await client.academy.getSpells()
const emblems = await client.academy.getEmblems()
const ranks = await client.academy.getRanks()
const guides = await client.academy.getRecommended()

client.user — Player Authentication & Data

Requires in-game verification. Returns an immutable UserSession for each account.

// Login flow
await client.user.sendVerificationCode(123456789, 1234)
const session = await client.user.login(123456789, 1234, 5678)

// Or restore from a saved JWT
const session = client.user.createSession(process.env.MLBB_JWT)

// Player data
const info = await session.getInfo()
const stats = await session.getStats()
const seasons = await session.getSeason()
const matches = await session.getMatches({ sid: 30 })
const details = await session.getMatchDetails('4132717739868068534', 30)
const heroes = await session.getFrequentHeroes({ sid: 30 })
const byHero = await session.getMatchesByHero(17, { sid: 30 })
const friends = await session.getFriends(30)

// Privacy
const privacy = await session.getPrivacySettings()
await session.updatePrivacySettings('invisible')

// Logout
await session.logout()

Multi-account support — each session is independent:

const [s1, s2] = await Promise.all([
  client.user.login(id1, zone1, vc1),
  client.user.login(id2, zone2, vc2),
])
const [info1, info2] = await Promise.all([s1.getInfo(), s2.getInfo()])

client.addon — Utilities

// Calculate consecutive wins needed to reach a target win rate
const wr = await client.addon.calculateWinRate({ matchNow: 100, wrNow: 50, wrFuture: 75 })

// IP geolocation
const ip = await client.addon.getIpLocation()

Zod Schemas

Zod schemas are available as a separate export for runtime validation:

import { UserInfoResponseSchema } from 'mlbb-sdk/schemas'

const parsed = UserInfoResponseSchema.parse(rawData)

zod is an optional peer dependency — install it only if you need schemas.

License

MIT