Fully typed client SDK for the Marzban API, supporting both browser and Node.js environments.
npm install marzban-sdk





---
> π§ We're working on Marzban SDK 2.0.0 β the biggest update yet!
>
> This release brings fundamental improvements:
>
> - π‘οΈ Strict validation with Zod schemas
> - π Plugin system for HTTP & WebSocket requests
> - β οΈ Unified error system with dedicated classes
> - π Configurable logger
> - π» CLI tool (planned)
>
> π Share your feedback! What features would you like to see? π Join the discussion on GitHub
---
MarzbanSDK is a fully typed TypeScript client for interacting with the Marzban API.
It provides a clean, consistent, and developer-friendly interface β with built-in authentication, retries, and WebSocket support.
Unlike some SDK generators, MarzbanSDK does not dynamically generate or rebuild code from OpenAPI.
Instead, all methods and types are implemented directly as strongly-typed TypeScript definitions, originally based on Marzbanβs OpenAPI schema β but maintained and refined manually for better developer experience.
The SDK works seamlessly in both Node.js and browser environments.
π View on GitHub
---
- β¨ Features
- π¦ Installation
- π Quick Start
- π Configuration Options
- π Authorization Control
- π How It Works
- π API Documentation
- π‘ WebSocket Support
- π€ Contributing
- π License
- β Support the Project
---
- β
First-class TypeScript Support β All methods, parameters, and responses are strongly typed.
- π Works in Node.js and Browser β Fully compatible with both environments.
- π Manual or Automatic Authorization β Choose explicit or automatic login with full error handling.
- π Auto Token Refresh β Automatic session renewal on expiration.
- π Retry Logic β Resilient against temporary network errors.
- π‘ Real-time WebSocket Logging β Stream logs from core or nodes.
- π OpenAPI-based Implementation β Methods and types are derived from Marzbanβs OpenAPI specification, but implemented as native TS code for stability and flexibility.
---
Install MarzbanSDK via npm:
``sh`
npm install marzban-sdk
Or using yarn:
`sh`
yarn add marzban-sdk
---
The Config object is used to initialize the MarzbanSDK instance. Below are all available options:
| Name | Type | Required | Default | Description |
| -------------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| baseUrl | string | Yes | β | The base URL of the Marzban API instance. Example: https://api.example.com |username
| | string | Yes | β | The username for authentication. |password
| | string | Yes | β | The password for authentication. |token
| | string | No | β | Optional JWT token for direct authorization. If provided, SDK uses this token for requests. |retries
| | number | No | 3 | Number of automatic retries for failed HTTP requests. |authenticateOnInit
| | boolean | No | true | If true (default), SDK authenticates automatically on init. If false, call authorize() manually. |
---
MarzbanSDK gives you full control over authentication:
- Automatic authentication (default): The SDK logs in as soon as you create an instance.
- Manual authentication: Set authenticateOnInit: false to delay login and handle errors yourself.
`typescript
import { MarzbanSDK, AuthenticationError } from 'marzban-sdk'
const sdk = new MarzbanSDK({
baseUrl: 'https://api.example.com',
username: 'admin',
password: 'secret',
authenticateOnInit: false, // Manual mode
})
try {
await sdk.authorize() // Explicit login
// Now you can make authenticated requests
} catch (e) {
if (e instanceof AuthenticationError) {
// Handle authentication failure
}
}
// Fetch user details
sdk.user.getUserById('user-id').then(user => {
console.log(user)
})
// Get an authorization token
sdk.getAuthToken().then(token => {
console.log(token)
})
`
You can also force re-authentication at any time:
`typescript`
await sdk.authorize(true) // Force a new login, even if already authenticated
See Config interface documentation for all available options.
---
`typescript
import { MarzbanSDK, Config } from 'marzban-sdk'
const sdk = new MarzbanSDK({
baseUrl: 'https://api.example.com',
username: 'your-username',
password: 'your-password',
})
// Fetch user details
sdk.user.getUserById('user-id').then(user => {
console.log(user)
})
// Get an authorization token
sdk.getAuthToken().then(token => {
console.log(token)
})
`
---
MarzbanSDK is built around a clean TypeScript architecture:
Every method, parameter, and response is defined using TypeScript types derived from Marzbanβs OpenAPI schema.
The SDK itself is not generated at runtime β all types and methods are implemented within the library for consistency and performance.
Access all Marzban endpoints through a single, well-structured class: MarzbanSDK`.
The SDK uses platform-agnostic HTTP clients, making it work seamlessly in:
- Node.js environments
- Modern browsers
- React/Next.js applications
- Other JavaScript runtimes
---
Full API reference and usage examples are available here:
---
MarzbanSDK supports WebSocket for real-time log streaming.
You can receive logs from both the core server and individual nodes.
For more details, check the WebSocket Guide.
---
We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation:
1. π Fork the repository
2. π§ Create a feature branch
3. π Make your changes
4. π Submit a pull request
Check our Contribution Guidelines for details.
---
This project is licensed under the MIT License. See LICENSE for details.
---
If MarzbanSDK helps your project, please:
- β Star the repository on GitHub
- π Report issues you encounter
- π‘ Suggest improvements and new features
- π’ Share with other developers
Your support helps us improve the library for everyone! β€οΈ
---
MarzbanSDK - TypeScript client for Marzban API β’ GitHub Repository