The complete SDK
for the Marzban API
Far more than an API client. MarzbanSDK bundles the entire infrastructure layer a serious Marzban integration needs — typed endpoints, auto token refresh, retries, WebSocket streaming, webhooks and runtime validation — so you ship features, not plumbing.
npm install marzban-sdkMIT licensed · Full official Marzban API coverage · Tree-shakeable ESM + CJS
From install to full API access in minutes
A single function authenticates, configures retries, and exposes every typed API module.
import { createMarzbanSDK, isAuthError } from 'marzban-sdk'
// One call authenticates and wires up every API module.
// Token refresh and retries are handled for you.
const sdk = await createMarzbanSDK({
baseUrl: 'https://panel.example.com',
username: 'admin',
password: 'secret',
})
// Fully typed API surface: users · nodes · system · subscriptions · …
const { users } = await sdk.user.getUsers({ status: 'active', limit: 10 })
const stats = await sdk.system.getSystemStats()
// Stream real-time logs from the core over WebSocket
const close = await sdk.logs.connectByCore({
onMessage: (data) => console.log(data),
})
// Typed, narrowable error handling
try {
await sdk.user.getUserByUsername('does-not-exist')
} catch (err) {
if (isAuthError(err)) await sdk.authorize()
}The whole API, fully typed
Nine ready-to-use modules cover everything Marzban exposes — each with complete TypeScript types and autocomplete.
Users
Create, update, reset and inspect users and their traffic.
Nodes
Manage and monitor connected Marzban nodes.
System
Live stats, host info and core configuration.
Core
Control and restart the Xray core, read its config.
Subscriptions
Resolve subscription links and per-client configs.
User templates
Reusable templates for provisioning users.
Admins
Manage admin accounts and permissions.
Logs
WebSocket log streams from the core and nodes.
Webhooks
Verify and handle inbound Marzban events.
A real SDK, not just a wrapper
MarzbanSDK ships the reliability features every production Marzban integration needs — so you focus on product, not plumbing.
End-to-end type safety
Every endpoint, parameter and response is fully typed. Autocomplete covers the entire Marzban API surface — typed against the official OpenAPI spec.
Isomorphic by design
One package, identical API in Node.js and the browser. Ships dual ESM + CJS builds, is side-effect free, and tree-shakes cleanly.
Flexible auth control
Authenticate automatically on init, pass an existing JWT, or take full manual control. Every mode is fully type-safe.
Auto token refresh
Expired sessions are renewed transparently behind the scenes. Your application code never has to handle a 401.
Built-in retry logic
Configurable exponential back-off for transient network failures and WebSocket reconnects — no boilerplate in your code.
Classified error system
Errors carry structured codes and are narrowed with type guards, so you handle auth, network and validation failures precisely.
Runtime Zod validation
Configuration and payloads are validated at runtime. Misconfigured clients fail fast with clear, actionable messages.
Real-time log streaming
Stream live logs from the Marzban core or any node over WebSocket, with automatic reconnection built in.
Webhooks, batteries included
HMAC-SHA256 signature verification, typed event subscriptions and wildcard handlers for inbound Marzban events.
Structured logging
Environment-aware logger out of the box — verbose in dev, quiet in production — or plug in your own logging stack.
Helpful utilities
First-class helpers for byte conversions, datetime math and subscription template variables — common chores, solved.
Production-hardened
Timeouts, cancellation and defensive defaults are baked in. Built and tested for real workloads, not just demos.
Build your Marzban integration the right way
Read the quick-start guide and have a typed, authenticated client running in a couple of minutes.