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.