MarzbanAPILib
A modern, async Python client library for interacting with Marzban VPN panel API.
Features
- 🚀 Async/await support - Built with modern Python async patterns
- 📦 Modular design - Organized into logical sections for better maintainability
- 🔐 Type hints - Full type annotation for better IDE support
- ⚡ Simple & intuitive - Easy to use API interface
- 🛡️ Error handling - Comprehensive error handling with meaningful messages
- 📚 Well documented - Detailed documentation for all methods
Installation
Install using pip:
pip install marzbanapilib
Quick Start
Authentication with Username/Password
import asyncio
from marzbanapilib import MarzbanAPI
async def main():
# Create API client using username and password
async with MarzbanAPI(
base_url="http://127.0.0.1:8000",
username="admin",
password="password"
) as api:
# Get system statistics
stats = await api.system.get_stats()
print(f"Total users: {stats['total_user']}")
# Create a new user
user = await api.user.create_user({
"username": "test_user",
"proxies": {"vmess": {}, "vless": {}},
"expire": 0, # No expiration
"data_limit": 0 # Unlimited
})
print(f"Created user: {user['username']}")
# Run the async function
asyncio.run(main())
Authentication with Access Token
import asyncio
from marzbanapilib import MarzbanAPI
async def main():
# Use pre-existing access token (no username/password needed)
async with MarzbanAPI(
base_url="http://127.0.0.1:8000",
access_token="your_jwt_token_here"
) as api:
# Get system statistics
stats = await api.system.get_stats()
print(f"Total users: {stats['total_user']}")
asyncio.run(main())
Architecture
The library is organized into modular sections:
user- User management operationsadmin- Admin management operationssystem- System statistics and configurationcore- Xray core managementnode- Multi-node management
Using Sections
async with MarzbanAPI(...) as api:
# User operations
await api.user.create_user(...)
await api.user.get_users()
await api.user.reset_data_usage("username")
# System operations
await api.system.get_stats()
await api.system.get_inbounds()
# Core operations
await api.core.restart()
await api.core.get_config()
# Node operations
await api.node.get_all()
await api.node.create(...)
Advanced Usage
Manual Authentication
# With username/password
api = MarzbanAPI("http://127.0.0.1:8000", "admin", "password")
await api.authenticate()
# Or with access token
api = MarzbanAPI("http://127.0.0.1:8000", access_token="your_jwt_token")
await api.authenticate()
# Use the API
users = await api.user.get_users()
# Don't forget to close
await api.close()
Error Handling
from marzbanapilib import MarzbanAPI
async with MarzbanAPI(...) as api:
try:
user = await api.user.get_user("nonexistent")
except ValueError as e:
print(f"User not found: {e}")
except httpx.HTTPStatusError as e:
print(f"HTTP error: {e}")
Filtering Users
# Get active users with pagination
users = await api.user.get_users(
offset=0,
limit=50,
status="active",
sort="created_at"
)
API Reference
User Management
create_user(data)- Create new userget_user(username)- Get user detailsmodify_user(username, data)- Modify userdelete_user(username)- Delete userget_users(**filters)- List users with filtersreset_data_usage(username)- Reset user data usagerevoke_subscription(username)- Revoke user subscriptionget_usage(username)- Get user usage statistics- And more...
System Management
get_stats()- Get system statisticsget_inbounds()- Get inbound configurationsget_hosts()- Get proxy hostsmodify_hosts(data)- Modify proxy hosts
Core Management
get_stats()- Get core statisticsrestart()- Restart Xray coreget_config()- Get core configurationmodify_config(data)- Modify core configuration
Node Management
get_all()- List all nodescreate(data)- Create new nodeget(node_id)- Get node detailsmodify(node_id, data)- Modify nodedelete(node_id)- Delete nodereconnect(node_id)- Reconnect nodeget_usage()- Get nodes usage statistics
Requirements
- Python 3.7+
- httpx
- pydantic
- aiofiles
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Support
For issues and feature requests, please use the GitHub issue tracker.
Metadata
Release files for marzbanapilib 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| marzbanapilib-0.2.0.tar.gz | 15.7 kB | Without provenance | Details for marzbanapilib-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| marzbanapilib-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for marzbanapilib-0.2.0-py3-none-any.whl |
Total release size: 32.6 kB
Release files / marzbanapilib-0.2.0.tar.gz
| Download URL | marzbanapilib-0.2.0.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3aaacb5759385927c25b858b13adc6e48e72e3b8d7e90dfb680ed9ce00ad1035
|
|
BLAKE2b-256 checksum How to use checksums |
6145b5e2041ef58c127344120fbbcff68dea1c632eed59a4da0fea732ce69278
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.3
|
Release files / marzbanapilib-0.2.0-py3-none-any.whl
| Download URL | marzbanapilib-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e4bd927356defcff7bacb90f8b78319ccc02bc54d15c8bbcdf4c7fa60cb87f22
|
|
BLAKE2b-256 checksum How to use checksums |
467f9a549cc4e144af8eefeb09d6beaf69c6f582f429e0c275210863a90cad8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.3
|
Security for marzbanapilib 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.