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 marzbanapilibimport 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 operations
- admin- Admin management operations
- system- System statistics and configuration
- core- Xray core management
- node- 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 user
- get_user(username)- Get user details
- modify_user(username, data)- Modify user
- delete_user(username)- Delete user
- get_users(**filters)- List users with filters
- reset_data_usage(username)- Reset user data usage
- revoke_subscription(username)- Revoke user subscription
- get_usage(username)- Get user usage statistics
- And more...
- get_stats()- Get system statistics
- get_inbounds()- Get inbound configurations
- get_hosts()- Get proxy hosts
- modify_hosts(data)- Modify proxy hosts
- get_stats()- Get core statistics
- restart()- Restart Xray core
- get_config()- Get core configuration
- modify_config(data)- Modify core configuration
- get_all()- List all nodes
- create(data)- Create new node
- get(node_id)- Get node details
- modify(node_id, data)- Modify node
- delete(node_id)- Delete node
- reconnect(node_id)- Reconnect node
- get_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.