A modern, async Python client library for interacting with Marzban VPN panel API.
- 🚀 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
Install using pip:
pip install marzbanapilib
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())
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())
The library is organized into modular sections:
user
- User management operationsadmin
- Admin management operationssystem
- System statistics and configurationcore
- Xray core managementnode
- Multi-node management
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(...)
# 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()
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}")
# Get active users with pagination
users = await api.user.get_users(
offset=0,
limit=50,
status="active",
sort="created_at"
)
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...
get_stats()
- Get system statisticsget_inbounds()
- Get inbound configurationsget_hosts()
- Get proxy hostsmodify_hosts(data)
- Modify proxy hosts
get_stats()
- Get core statisticsrestart()
- Restart Xray coreget_config()
- Get core configurationmodify_config(data)
- Modify core configuration
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
- Python 3.7+
- httpx
- pydantic
- aiofiles
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For issues and feature requests, please use the GitHub issue tracker.