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 operations
• admin - Admin management operations
• system - System statistics and configuration
• core - Xray core management
• node - 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 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...

System Management

• get_stats() - Get system statistics
• get_inbounds() - Get inbound configurations
• get_hosts() - Get proxy hosts
• modify_hosts(data) - Modify proxy hosts

Core Management

• get_stats() - Get core statistics
• restart() - Restart Xray core
• get_config() - Get core configuration
• modify_config(data) - Modify core configuration

Node Management

• 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

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.