### Install Remnawave SDK (Development Version)

Source: https://github.com/remnawave/python-sdk/blob/production/README.md

Install the development version of the Remnawave SDK directly from its GitHub repository.

```bash
pip install git+https://github.com/remnawave/python-sdk.git@development
```

--------------------------------

### Install Remnawave SDK (New Package)

Source: https://github.com/remnawave/python-sdk/blob/production/README.md

Install the latest version of the Remnawave SDK using pip. This is the recommended installation method.

```bash
pip install remnawave
```

--------------------------------

### Install Remnawave Python SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Install the SDK using pip. Ensure you are using a compatible Python version.

```bash
pip install remnawave          # Python 3.11 – 3.13
```

--------------------------------

### Initialize and Use Remnawave SDK

Source: https://github.com/remnawave/python-sdk/blob/production/README.md

A basic example demonstrating how to initialize the Remnawave SDK with your API credentials and fetch all users. Ensure REMNAWAVE_BASE_URL and REMNAWAVE_TOKEN environment variables are set.

```python
import os
import asyncio

from remnawave import RemnawaveSDK  # Updated import for new package
from remnawave.models import (
    UsersResponseDto, 
    UserResponseDto,
    GetAllConfigProfilesResponseDto,
    CreateInternalSquadRequestDto
)

async def main():
    # URL to your panel (ex. https://vpn.com or http://127.0.0.1:3000)
    base_url: str = os.getenv("REMNAWAVE_BASE_URL")
    # Bearer Token from panel (section: API Tokens) 
    token: str = os.getenv("REMNAWAVE_TOKEN")

    # Initialize the SDK
    remnawave = RemnawaveSDK(base_url=base_url, token=token)

    # Fetch all users
    response: UsersResponseDto = await remnawave.users.get_all_users()
    total_users: int = response.total
    users: list[UserResponseDto] = response.users
    print("Total users: ", total_users)
    print("List of users: ", users)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Install Remnawave SDK (Legacy Package)

Source: https://github.com/remnawave/python-sdk/blob/production/README.md

Install the legacy version (≤1.x) of the Remnawave SDK. This package is deprecated and 'remnawave' should be used instead.

```bash
pip install remnawave_api  # Deprecated - use 'remnawave' instead
```

--------------------------------

### Manage Subscriptions with SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates fetching paginated subscription lists, looking up subscriptions by username or short UUID, retrieving raw proxy links, and getting connection keys.

```python
import asyncio
from remnawave import RemnawaveSDK

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_subscriptions():
    # Paginated subscription list
    page = await sdk.subscriptions.get_all_subscriptions(start=0, size=25)

    # Lookup by username
    sub = await sdk.subscriptions.get_subscription_by_username("alice")
    print(sub.subscription_url)

    # Lookup by short UUID
    sub2 = await sdk.subscriptions.get_subscription_by_short_uuid("abc123")

    # Raw proxy links (base64 encoded, suitable for client import)
    raw = await sdk.subscriptions.get_raw_subscription(
        short_uuid="abc123",
        with_disabled_hosts=False,
    )
    print(raw)   # GetRawSubscriptionByShortUuidResponseDto

    # Connection keys (base64) by user UUID
    keys = await sdk.subscriptions.get_connection_keys_by_uuid(
        "aaaaaaaa-0000-0000-0000-000000000001"
    )
    print(keys)

asyncio.run(demo_subscriptions())
```

--------------------------------

### Get Bandwidth Stats with Remnawave SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates fetching per-user and per-node bandwidth usage over a date range, as well as real-time node usage. Requires SDK initialization with base URL and token.

```python
import asyncio
from remnawave import RemnawaveSDK

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_bw():
    user_uuid = "aaaaaaaa-0000-0000-0000-000000000001"
    node_uuid = "bbbbbbbb-0000-0000-0000-000000000001"

    # Per-user usage over a date range (top 5 nodes)
    usage = await sdk.bandwidthstats.get_stats_user_usage(
        uuid=user_uuid,
        top_nodes_limit=5,
        start="2024-01-01",
        end="2024-01-31",
    )
    print(usage)

    # All-nodes aggregated usage
    nodes_usage = await sdk.bandwidthstats.get_stats_nodes_usage(
        top_nodes_limit=10,
        start="2024-01-01",
        end="2024-01-31",
    )

    # Top users on a specific node
    node_users = await sdk.bandwidthstats.get_stats_node_users_usage(
        uuid=node_uuid,
        top_users_limit=20,
        start="2024-01-01",
        end="2024-01-31",
    )

    # Realtime per-node bandwidth
    realtime = await sdk.bandwidthstats.get_nodes_realtime_usage()
    print(realtime)

asyncio.run(demo_bw())
```

--------------------------------

### Get All Users

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a paginated list of all users, with options to specify the starting index and the number of users per page.

```APIDOC
## GET /users

### Description
Retrieves a paginated list of all users, with options to specify the starting index and the number of users per page.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **start** (integer) - Optional - The starting index for pagination.
- **size** (integer) - Optional - The number of users to retrieve per page.

### Response
#### Success Response (200)
- **PaginatedUserListDto** - Contains the total number of users and a list of user objects.
  - **total** (integer) - The total number of users available.
  - **users** (array) - A list of UserResponseDto objects.

#### Response Example
```json
{
  "total": 100,
  "users": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "username": "alice",
      "status": "active",
      "expire_at": "2023-12-31T23:59:59Z",
      "traffic_limit_bytes": 10737418240,
      "subscription_url": "https://vpn.example.com/sub/abc123xyz",
      "user_traffic": {
        "used_traffic_bytes": 5368709120,
        "upload_bytes": 1073741824,
        "download_bytes": 4294967296
      },
      "happ": {
        "crypto_link": "happ://..."
      }
    }
  ]
}
```
```

--------------------------------

### Get User by Username

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a user's details by their unique username.

```APIDOC
## GET /users/by-username/{username}

### Description
Retrieves a user's details by their unique username.

### Method
GET

### Endpoint
/users/by-username/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to retrieve.

### Response
#### Success Response (200)
- **UserResponseDto** - Contains user details.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "alice",
  "status": "active",
  "expire_at": "2023-12-31T23:59:59Z",
  "traffic_limit_bytes": 10737418240,
  "subscription_url": "https://vpn.example.com/sub/abc123xyz",
  "user_traffic": {
    "used_traffic_bytes": 5368709120,
    "upload_bytes": 1073741824,
    "download_bytes": 4294967296
  },
  "happ": {
    "crypto_link": "happ://..."
  }
}
```
```

--------------------------------

### Get User by Short UUID

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a user's details by their short UUID.

```APIDOC
## GET /users/by-short-uuid/{short_uuid}

### Description
Retrieves a user's details by their short UUID.

### Method
GET

### Endpoint
/users/by-short-uuid/{short_uuid}

### Parameters
#### Path Parameters
- **short_uuid** (string) - Required - The short UUID of the user to retrieve.

### Response
#### Success Response (200)
- **UserResponseDto** - Contains user details.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "alice",
  "status": "active",
  "expire_at": "2023-12-31T23:59:59Z",
  "traffic_limit_bytes": 10737418240,
  "subscription_url": "https://vpn.example.com/sub/abc123xyz",
  "user_traffic": {
    "used_traffic_bytes": 5368709120,
    "upload_bytes": 1073741824,
    "download_bytes": 4294967296
  },
  "happ": {
    "crypto_link": "happ://..."
  }
}
```
```

--------------------------------

### SDK Initialization

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates how to initialize the RemnawaveSDK with minimal and advanced configurations, including using a custom httpx.AsyncClient.

```APIDOC
## SDK Initialization

`RemnawaveSDK` — main entry point that wires together every controller.

Accepts a `base_url` (panel URL without trailing `/`) and a `token` (Bearer token). Optionally accepts a pre-built `httpx.AsyncClient` for custom transport, `ssl_ignore=True` to skip TLS verification, `caddy_token` for Caddy reverse-proxy API-key auth, `custom_headers`, and `cookies`.

```python
import asyncio
import os
import httpx
from remnawave import RemnawaveSDK

# --- Minimal setup ---
sdk = RemnawaveSDK(
    base_url=os.environ["REMNAWAVE_BASE_URL"],   # e.g. "https://vpn.example.com"
    token=os.environ["REMNAWAVE_TOKEN"],          # Bearer token from panel
)

# --- Advanced: bring your own client (custom timeouts, retries, etc.) ---
transport = httpx.AsyncHTTPTransport(retries=3)
client = httpx.AsyncClient(
    base_url="https://vpn.example.com/api",
    headers={"Authorization": f"Bearer {os.environ['REMNAWAVE_TOKEN']}"},
    timeout=httpx.Timeout(30.0),
    transport=transport,
)
sdk_custom = RemnawaveSDK(client=client)

async def main():
    # health check
    health = await sdk.system.get_health()
    print(health)   # GetRemnawaveHealthResponseDto

asyncio.run(main())
```
```

--------------------------------

### Initialize Remnawave SDK (Minimal)

Source: https://context7.com/remnawave/python-sdk/llms.txt

Initialize the SDK with minimal configuration using environment variables for base URL and token.

```python
import asyncio
import os
import httpx
from remnawave import RemnawaveSDK

# --- Minimal setup ---
sdk = RemnawaveSDK(
    base_url=os.environ["REMNAWAVE_BASE_URL"],   # e.g. "https://vpn.example.com"
    token=os.environ["REMNAWAVE_TOKEN"],          # Bearer token from panel
)

async def main():
    # health check
    health = await sdk.system.get_health()
    print(health)   # GetRemnawaveHealthResponseDto

asyncio.run(main())
```

--------------------------------

### Access System Information and Utilities with SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates retrieving various system-level data including metadata, statistics, bandwidth usage, node metrics, and generating cryptographic keys. Also includes utility functions for encryption and debugging.

```python
import asyncio
from remnawave import RemnawaveSDK
from remnawave.models import (
    EncryptHappCryptoLinkRequestDto,
    DebugSrrMatcherRequestDto,
)

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_system():
    # Panel version / build info
    meta = await sdk.system.get_metadata()
    print(meta.version, meta.build.number)

    # System stats (CPU, RAM, user counts)
    stats = await sdk.system.get_stats()
    print(f"CPU cores: {stats.cpu.cores}, uptime: {stats.uptime:.0f}s")
    print(f"Total users: {stats.users.total_users}")
    print(f"Online now: {stats.online_stats.online_now}")

    # Bandwidth statistics
    bw = await sdk.system.get_bandwidth_stats()
    print(f"Last 30 days: {bw.last_30_days.current}")

    # Node statistics (7-day per-node traffic)
    node_stats = await sdk.system.get_nodes_statistics()
    for day in node_stats.last_seven_days:
        print(day.node_name, day.date, day.total_bytes)

    # Real-time node metrics
    metrics = await sdk.system.get_nodes_metrics()
    for n in metrics.nodes:
        print(n.node_name, f"online={n.users_online}")

    # Health (PM2 process stats)
    health = await sdk.system.get_health()
    for proc in (health.pm2_stats or []):
        print(proc.name, proc.cpu, proc.memory)

    # Generate X25519 key pair for REALITY
    keys = await sdk.system.get_x25519_key_pair()
    kp = keys.key_pairs[0]
    print(f"public={kp.public_key}  private={kp.private_key}")

    # Encrypt a subscription URL into a Happ crypto link
    enc = await sdk.system.encrypt_happ_crypto_link(
        body=EncryptHappCryptoLinkRequestDto(linkToEncrypt="https://vpn.example.com/sub/abc123")
    )
    print(enc.encrypted_link)

    # Monthly recap
    recap = await sdk.system.get_recap()
    print(f"Total nodes: {recap.total.nodes}, traffic: {recap.total.traffic}")

asyncio.run(demo_system())
```

--------------------------------

### Get All Node Tags

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves all unique tags associated with nodes.

```APIDOC
## Get All Node Tags

### Description
Retrieves all unique tags associated with nodes.

### Method
`sdk.nodes.get_all_nodes_tags`

### Response
#### Success Response (200)
- **tags** (list[string]) - A list of all node tags.
```

--------------------------------

### Initialize Remnawave SDK (Advanced)

Source: https://context7.com/remnawave/python-sdk/llms.txt

Initialize the SDK with a custom httpx.AsyncClient for advanced configurations like custom timeouts and retries.

```python
import asyncio
import os
import httpx
from remnawave import RemnawaveSDK

# --- Advanced: bring your own client (custom timeouts, retries, etc.) ---
transport = httpx.AsyncHTTPTransport(retries=3)
client = httpx.AsyncClient(
    base_url="https://vpn.example.com/api",
    headers={"Authorization": f"Bearer {os.environ['REMNAWAVE_TOKEN']}"},
    timeout=httpx.Timeout(30.0),
    transport=transport,
)
sdk_custom = RemnawaveSDK(client=client)

async def main():
    # health check
    health = await sdk.system.get_health()
    print(health)   # GetRemnawaveHealthResponseDto

asyncio.run(main())
```

--------------------------------

### Get User by UUID

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a user's details by their unique UUID.

```APIDOC
## GET /users/by-uuid/{uuid}

### Description
Retrieves a user's details by their unique UUID.

### Method
GET

### Endpoint
/users/by-uuid/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the user to retrieve.

### Response
#### Success Response (200)
- **UserResponseDto** - Contains user details.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "alice",
  "status": "active",
  "expire_at": "2023-12-31T23:59:59Z",
  "traffic_limit_bytes": 10737418240,
  "subscription_url": "https://vpn.example.com/sub/abc123xyz",
  "user_traffic": {
    "used_traffic_bytes": 5368709120,
    "upload_bytes": 1073741824,
    "download_bytes": 4294967296
  },
  "happ": {
    "crypto_link": "happ://..."
  }
}
```
```

--------------------------------

### Manage HWID Devices with Python SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

This snippet demonstrates how to manage hardware-ID based device registrations for users, including listing, adding, and deleting devices, as well as retrieving statistics. Ensure the SDK is initialized with valid credentials and base URL.

```python
import asyncio
from remnawave import RemnawaveSDK
from remnawave.models import CreateHWIDUser, HWIDDeleteRequest

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_hwid():
    user_uuid = "aaaaaaaa-0000-0000-0000-000000000001"

    # List all HWID devices (paginated)
    devices = await sdk.hwid.get_hwid_users(start=0, size=50)
    print(devices)

    # Get devices for a specific user
    user_devices = await sdk.hwid.get_hwid_user(user_uuid)

    # Register a device for a user
    created = await sdk.hwid.add_hwid_to_users(
        body=CreateHWIDUser(
            user_uuid=user_uuid,
            hwid="DEVICE-FINGERPRINT-ABC123",
        )
    )
    print(created)

    # Delete a specific device
    await sdk.hwid.delete_hwid_to_user(
        body=HWIDDeleteRequest(hwid="DEVICE-FINGERPRINT-ABC123", user_uuid=user_uuid)
    )

    # HWID statistics (total devices, unique users, etc.)
    stats = await sdk.hwid.get_hwid_stats()
    print(stats)

    # Top users by device count
    top = await sdk.hwid.get_top_users_by_hwid_devices(size=10, start=0)
    print(top)

asyncio.run(demo_hwid())
```

--------------------------------

### Get User Accessible Nodes

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a list of nodes that a specific user can access.

```APIDOC
## GET /users/{uuid}/accessible-nodes

### Description
Retrieves a list of nodes that a specific user can access.

### Method
GET

### Endpoint
/users/{uuid}/accessible-nodes

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the user.

### Response
#### Success Response (200)
- **array** - A list of node objects accessible by the user.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Node 1",
    "country": "USA"
  },
  {
    "id": 2,
    "name": "Node 2",
    "country": "Canada"
  }
]
```
```

--------------------------------

### Get User Subscription Request History

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves the history of subscription requests for a specific user.

```APIDOC
## GET /users/{uuid}/subscription-requests

### Description
Retrieves the history of subscription requests for a specific user.

### Method
GET

### Endpoint
/users/{uuid}/subscription-requests

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the user.

### Response
#### Success Response (200)
- **SubscriptionRequestHistoryDto** - Contains the history of subscription requests.
  - **records** (array) - A list of subscription request records.
    - **request_at** (datetime) - The timestamp of the request.
    - **request_ip** (string) - The IP address from which the request was made.
    - **user_agent** (string) - The user agent string of the client.

#### Response Example
```json
{
  "records": [
    {
      "request_at": "2023-11-15T10:00:00Z",
      "request_ip": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
    }
  ]
}
```
```

--------------------------------

### Get Users by Telegram ID

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a list of users associated with a specific Telegram ID.

```APIDOC
## GET /users/by-telegram-id/{telegram_id}

### Description
Retrieves a list of users associated with a specific Telegram ID.

### Method
GET

### Endpoint
/users/by-telegram-id/{telegram_id}

### Parameters
#### Path Parameters
- **telegram_id** (string) - Required - The Telegram ID to search for.

### Response
#### Success Response (200)
- **array** - A list of UserResponseDto objects associated with the given Telegram ID.

#### Response Example
```json
[
  {
    "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "username": "alice",
    "status": "active",
    "expire_at": "2023-12-31T23:59:59Z",
    "traffic_limit_bytes": 10737418240,
    "subscription_url": "https://vpn.example.com/sub/abc123xyz",
    "user_traffic": {
      "used_traffic_bytes": 5368709120,
      "upload_bytes": 1073741824,
      "download_bytes": 4294967296
    },
    "happ": {
      "crypto_link": "happ://..."
    }
  }
]
```
```

--------------------------------

### Manage Subscription Delivery Hosts with SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Use the `sdk.hosts` controller to create, list, update, reorder, and delete subscription delivery hosts. Ensure necessary UUIDs and DTOs are imported.

```python
import asyncio
from uuid import UUID
from remnawave import RemnawaveSDK
from remnawave.models import (
    CreateHostRequestDto,
    CreateHostInboundData,
    UpdateHostRequestDto,
    ReorderHostRequestDto,
    ReorderHostItem,
)
from remnawave.enums import SecurityLayer, ALPN, Fingerprint

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_hosts():
    profile_uuid  = UUID("11111111-1111-1111-1111-111111111111")
    inbound_uuid  = UUID("22222222-2222-2222-2222-222222222222")
    node_uuid     = UUID("33333333-3333-3333-3333-333333333333")

    # Create a host
    host = await sdk.hosts.create_host(
        body=CreateHostRequestDto(
            remark="DE VLESS TLS",
            address="de-01.example.com",
            port=443,
            sni="de-01.example.com",
            alpn=ALPN.H2,
            fingerprint=Fingerprint.CHROME,
            security_layer=SecurityLayer.TLS,
            nodes=[node_uuid],
            inbound=CreateHostInboundData(
                configProfileUuid=profile_uuid,
                configProfileInboundUuid=inbound_uuid,
            ),
        )
    )
    print(host.uuid, host.remark)

    # List all hosts (iterable RootModel)
    all_hosts = await sdk.hosts.get_all_hosts()
    for h in all_hosts:
        print(h.remark, h.address, h.port, h.is_disabled)

    # Update host
    await sdk.hosts.update_host(
        body=UpdateHostRequestDto(
            uuid=host.uuid,
            port=8443,
            sni="alt.example.com",
        )
    )

    # Reorder hosts
    await sdk.hosts.reorder_hosts(
        body=ReorderHostRequestDto(
            hosts=[ReorderHostItem(viewPosition=1, uuid=host.uuid)]
        )
    )

    # Tags
    tags = await sdk.hosts.get_hosts_tags()
    print(tags.tags)

    # Delete
    result = await sdk.hosts.delete_host(str(host.uuid))
    print(result.is_deleted)

asyncio.run(demo_hosts())
```

--------------------------------

### Full Nodes Controller Demo

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates the comprehensive usage of the Nodes Controller, including node creation, listing, updating, lifecycle management (enable, disable, restart), bulk actions, profile modifications, tag retrieval, and deletion. Ensure RemnawaveSDK is initialized with a valid base URL and token.

```python
import asyncio
from uuid import UUID
from remnawave import RemnawaveSDK
from remnawave.models import (
    CreateNodeRequestDto,
    UpdateNodeRequestDto,
    NodeConfigProfileRequestDto,
    RestartAllNodesRequestBodyDto,
    ProfileModificationRequestDto,
    ConfigProfileData,
    NodesBulkActionsRequestDto,
)


sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_nodes():
    profile_uuid = UUID("11111111-1111-1111-1111-111111111111")
    inbound_uuid  = UUID("22222222-2222-2222-2222-222222222222")

    # Create a node
    node = await sdk.nodes.create_node(
        body=CreateNodeRequestDto(
            name="DE-01",
            address="de-01.example.com",
            port=443,
            country_code="DE",
            is_traffic_tracking_active=True,
            traffic_limit_bytes=500 * 1024 ** 3,   # 500 GB
            notify_percent=80,
            traffic_reset_day=1,
            config_profile=NodeConfigProfileRequestDto(
                activeConfigProfileUuid=profile_uuid,
                activeInbounds=[inbound_uuid],
            ),
            tags=["DATACENTER:AWS", "REGION:EU"],
        )
    )
    print(node.uuid, node.is_connected)

    # List all nodes
    nodes = await sdk.nodes.get_all_nodes()
    for n in nodes:                              # GetAllNodesResponseDto is iterable
        print(n.name, n.country_code, n.users_online)

    # Update node
    await sdk.nodes.update_node(
        body=UpdateNodeRequestDto(
            uuid=node.uuid,
            traffic_limit_bytes=1024 ** 4,       # 1 TB
            notify_percent=90,
        )
    )

    # Lifecycle
    await sdk.nodes.enable_node(str(node.uuid))
    await sdk.nodes.disable_node(str(node.uuid))
    await sdk.nodes.restart_node(str(node.uuid))
    await sdk.nodes.restart_all_nodes(
        body=RestartAllNodesRequestBodyDto(forceRestart=True)
    )
    await sdk.nodes.reset_node_traffic(str(node.uuid))

    # Bulk: enable multiple nodes at once
    await sdk.nodes.nodes_bulk_actions(
        body=NodesBulkActionsRequestDto(
            uuids=[node.uuid],
            action="ENABLE",
        )
    )

    # Bulk profile modification
    await sdk.nodes.profile_modification(
        body=ProfileModificationRequestDto(
            uuids=[str(node.uuid)],
            configProfile=ConfigProfileData(
                activeConfigProfileUuid=str(profile_uuid),
                activeInbounds=[str(inbound_uuid)],
            ),
        )
    )

    # Tags
    tags = await sdk.nodes.get_all_nodes_tags()
    print(tags.tags)

    # Delete
    result = await sdk.nodes.delete_node(str(node.uuid))
    print(result.is_deleted)

asyncio.run(demo_nodes())

```

--------------------------------

### Manage API Tokens with Remnawave SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates listing, creating, and deleting API tokens using the SDK. Token creation requires a name and can optionally specify an expiry. Requires SDK initialization.

```python
import asyncio
from remnawave import RemnawaveSDK
from remnawave.models import CreateApiTokenRequestDto

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_tokens():
    # List all tokens
    tokens = await sdk.api_tokens_management.find_all()
    for t in tokens.response:
        print(t.uuid, t.name)

    # Create a new token
    new_token = await sdk.api_tokens_management.create(
        body=CreateApiTokenRequestDto(name="CI-Bot")
    )
    print(new_token)

    # Delete a token
    result = await sdk.api_tokens_management.delete(str(tokens.response[0].uuid))
    print(result)

asyncio.run(demo_tokens())
```

--------------------------------

### Perform Bulk User Actions with Remnawave SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates various bulk user operations including deletion, traffic reset, subscription revocation, and expiry date extension. Ensure RemnawaveSDK is initialized with a valid base URL and token.

```python
import asyncio
from uuid import UUID
from datetime import timedelta
from remnawave import RemnawaveSDK
from remnawave.models import (
    BulkDeleteUsersRequestDto,
    BulkDeleteUsersByStatusRequestDto,
    BulkResetTrafficUsersRequestDto,
    BulkRevokeUsersSubscriptionRequestDto,
    BulkExtendExpirationDateRequestDto,
    BulkAllExtendExpirationDateRequestDto,
    BulkUpdateUsersRequestDto,
)
from remnawave.enums import UserStatus


sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_bulk():
    uuids = [
        UUID("aaaaaaaa-0000-0000-0000-000000000001"),
        UUID("aaaaaaaa-0000-0000-0000-000000000002"),
    ]

    # Delete a specific set of users
    del_resp = await sdk.users_bulk_actions.bulk_delete_users(
        body=BulkDeleteUsersRequestDto(uuids=uuids)
    )

    # Delete all EXPIRED users
    del_status = await sdk.users_bulk_actions.bulk_delete_users_by_status(
        body=BulkDeleteUsersByStatusRequestDto(status=UserStatus.EXPIRED)
    )

    # Reset traffic for a list of users
    await sdk.users_bulk_actions.bulk_reset_user_traffic(
        body=BulkResetTrafficUsersRequestDto(uuids=uuids)
    )

    # Revoke subscriptions for a list of users
    await sdk.users_bulk_actions.bulk_revoke_users_subscription(
        body=BulkRevokeUsersSubscriptionRequestDto(uuids=uuids)
    )

    # Extend expiry by 30 days for specific users
    await sdk.users_bulk_actions.bulk_extend_expiration_date(
        body=BulkExtendExpirationDateRequestDto(
            uuids=uuids,
            days=30,
        )
    )

    # Extend expiry by 7 days for ALL users
    await sdk.users_bulk_actions.bulk_all_extend_expiration_date(
        body=BulkAllExtendExpirationDateRequestDto(days=7)
    )

    # Reset traffic for ALL users
    await sdk.users_bulk_actions.bulk_all_reset_user_traffic()

asyncio.run(demo_bulk())
```

--------------------------------

### Manage Panel Users with Remnawave SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Demonstrates full CRUD and lifecycle operations for panel users, including creation with specific expiry and traffic limits, paginated retrieval, lookup by various identifiers, updates, and deletion. Requires RemnawaveSDK initialization with base URL and token.

```python
import asyncio
from datetime import datetime, timezone, timedelta
from remnawave import RemnawaveSDK
from remnawave.models import (
    CreateUserRequestDto,
    UpdateUserRequestDto,
    RevokeUserRequestDto,
    ResolveUserRequestBodyDto,
)
from remnawave.enums import UserStatus, TrafficLimitStrategy


sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_users():
    # Create a user (30-day expiry, 10 GB limit, monthly reset)
    new_user = await sdk.users.create_user(
        body=CreateUserRequestDto(
            username="alice",
            expire_at=datetime.now(timezone.utc) + timedelta(days=30),
            traffic_limit_bytes=10 * 1024 ** 3,           # 10 GB
            traffic_limit_strategy=TrafficLimitStrategy.MONTH,
            telegram_id=123456789,
            description="VIP customer",
            tag="VIP",
        )
    )
    print(new_user.uuid, new_user.subscription_url)
    # Happ-encrypted subscription link (v4 by default)
    print(new_user.happ.crypto_link)

    # Paginated user list
    page = await sdk.users.get_all_users(start=0, size=25)
    print(f"Total users: {page.total}")
    for u in page.users:
        print(u.username, u.status, u.user_traffic.used_traffic_bytes)

    # Lookup by various identifiers
    by_name  = await sdk.users.get_user_by_username("alice")
    by_uuid  = await sdk.users.get_user_by_uuid(str(new_user.uuid))
    by_short = await sdk.users.get_user_by_short_uuid(new_user.short_uuid)
    by_tg    = await sdk.users.get_users_by_telegram_id("123456789")   # list

    # Resolve by any identifier
    resolved = await sdk.users.resolve_user(
        body=ResolveUserRequestBodyDto(username="alice")
    )
    print(resolved.uuid, resolved.id)

    # Update — extend expiry and change traffic limit
    updated = await sdk.users.update_user(
        body=UpdateUserRequestDto(
            uuid=new_user.uuid,
            expire_at=datetime.now(timezone.utc) + timedelta(days=60),
            traffic_limit_bytes=20 * 1024 ** 3,
        )
    )

    # Lifecycle actions
    await sdk.users.disable_user(str(new_user.uuid))
    await sdk.users.enable_user(str(new_user.uuid))
    await sdk.users.reset_user_traffic(str(new_user.uuid))
    await sdk.users.revoke_user_subscription(
        str(new_user.uuid),
        body=RevokeUserRequestDto(revoke_only_passwords=True),
    )

    # Accessible nodes for user
    nodes = await sdk.users.get_user_accessible_nodes(str(new_user.uuid))

    # Subscription request history (last 24 records)
    history = await sdk.users.get_user_subscription_request_history(str(new_user.uuid))
    for record in history.records:
        print(record.request_at, record.request_ip, record.user_agent)

    # Delete
    result = await sdk.users.delete_user(str(new_user.uuid))
    print(result.is_deleted)   # True

asyncio.run(demo_users())

```

--------------------------------

### Authenticate with Remnawave SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Shows how to check the status of the current token and log in using username and password to obtain a new JWT. Requires SDK initialization.

```python
import asyncio
from remnawave import RemnawaveSDK
from remnawave.models import LoginRequestDto, RegisterRequestDto

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_auth():
    # Check token validity
    status = await sdk.auth.get_status()
    print(status)

    # Login with credentials (returns JWT)
    login_resp = await sdk.auth.login(
        body=LoginRequestDto(username="admin", password="secret")
    )
    print(login_resp)

asyncio.run(demo_auth())
```

--------------------------------

### Manage Subscription Settings with SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Shows how to read current global subscription delivery settings and update them, such as changing the expired user strategy. Only provided fields in `UpdateSubscriptionSettingsRequestDto` are modified.

```python
import asyncio
from remnawave import RemnawaveSDK
from remnawave.models import UpdateSubscriptionSettingsRequestDto

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_sub_settings():
    # Read current settings
    settings = await sdk.subscriptions_settings.get_settings()
    print(settings)

    # Update — enable/disable profile options
    updated = await sdk.subscriptions_settings.update_settings(
        body=UpdateSubscriptionSettingsRequestDto(
            expired_user_strategy="REMOVE_HOSTS",
        )
    )
    print(updated)

asyncio.run(demo_sub_settings())
```

--------------------------------

### Read and Replace Global Xray Configuration with SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Use the `sdk.xray_config` controller to retrieve the current global Xray configuration or replace it with a new configuration. The configuration is handled as a Python dictionary.

```python
import asyncio
from remnawave import RemnawaveSDK

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_xray():
    # Read current Xray config
    cfg = await sdk.xray_config.get_config()
    print(cfg)   # GetConfigResponseDto wrapping the full JSON

    # Replace config (minimal example — adapt to your real config)
    new_config = {
        "log": {"loglevel": "warning"},
        "inbounds": [],
        "outbounds": [{"protocol": "freedom"}],
    }
    updated = await sdk.xray_config.update_config(body=new_config)
    print(updated)

asyncio.run(demo_xray())
```

--------------------------------

### Create User

Source: https://context7.com/remnawave/python-sdk/llms.txt

Creates a new user with specified details including username, expiry, traffic limits, and optional fields like Telegram ID and description.

```APIDOC
## POST /users

### Description
Creates a new user with specified details including username, expiry, traffic limits, and optional fields like Telegram ID and description.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **body** (CreateUserRequestDto) - Required - User creation data.
  - **username** (string) - Required - The username for the new user.
  - **expire_at** (datetime) - Required - The expiration time for the user's account.
  - **traffic_limit_bytes** (integer) - Required - The traffic limit in bytes.
  - **traffic_limit_strategy** (TrafficLimitStrategy) - Optional - The strategy for traffic limit resets (e.g., MONTH).
  - **telegram_id** (integer) - Optional - The Telegram ID of the user.
  - **description** (string) - Optional - A description for the user.
  - **tag** (string) - Optional - A tag for the user.

### Request Example
```python
await sdk.users.create_user(
    body=CreateUserRequestDto(
        username="alice",
        expire_at=datetime.now(timezone.utc) + timedelta(days=30),
        traffic_limit_bytes=10 * 1024 ** 3,           # 10 GB
        traffic_limit_strategy=TrafficLimitStrategy.MONTH,
        telegram_id=123456789,
        description="VIP customer",
        tag="VIP",
    )
)
```

### Response
#### Success Response (200)
- **UserResponseDto** - Contains user details including uuid, username, status, expiry, traffic information, and subscription URL.
  - **uuid** (string) - The unique identifier of the user.
  - **username** (string) - The username of the user.
  - **status** (UserStatus) - The current status of the user.
  - **expire_at** (datetime) - The expiration time of the user's account.
  - **traffic_limit_bytes** (integer) - The total traffic limit in bytes.
  - **subscription_url** (string) - The URL for the user's subscription.
  - **user_traffic** (UserTrafficDto) - Nested object with current traffic usage.
  - **happ** (HappDto) - Nested object containing Happ crypto link information.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "alice",
  "status": "active",
  "expire_at": "2023-12-31T23:59:59Z",
  "traffic_limit_bytes": 10737418240,
  "subscription_url": "https://vpn.example.com/sub/abc123xyz",
  "user_traffic": {
    "used_traffic_bytes": 5368709120,
    "upload_bytes": 1073741824,
    "download_bytes": 4294967296
  },
  "happ": {
    "crypto_link": "happ://..."
  }
}
```
```

--------------------------------

### Create Node

Source: https://context7.com/remnawave/python-sdk/llms.txt

Creates a new proxy node with specified configuration details.

```APIDOC
## Create Node

### Description
Creates a new proxy node with specified configuration details.

### Method
`sdk.nodes.create_node`

### Parameters
#### Request Body
- **body** (CreateNodeRequestDto) - Required - The request body containing node details.
  - **name** (string) - Required - The name of the node.
  - **address** (string) - Required - The network address of the node.
  - **port** (integer) - Required - The network port of the node.
  - **country_code** (string) - Required - The country code where the node is located.
  - **is_traffic_tracking_active** (boolean) - Required - Whether traffic tracking is active.
  - **traffic_limit_bytes** (integer) - Optional - The traffic limit in bytes.
  - **notify_percent** (integer) - Optional - The percentage at which to notify for traffic usage.
  - **traffic_reset_day** (integer) - Optional - The day of the month for traffic reset.
  - **config_profile** (NodeConfigProfileRequestDto) - Optional - Configuration profile for the node.
    - **activeConfigProfileUuid** (string) - Required - UUID of the active configuration profile.
    - **activeInbounds** (list[string]) - Required - List of active inbound UUIDs.
  - **tags** (list[string]) - Optional - List of tags for the node.

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier of the created node.
- **is_connected** (boolean) - The connection status of the node.
```

--------------------------------

### Manage Xray Config Profiles with SDK

Source: https://context7.com/remnawave/python-sdk/llms.txt

Use the `sdk.config_profiles` controller for CRUD operations on Xray config profiles and their inbounds. This includes fetching raw and computed configurations.

```python
import asyncio
from uuid import UUID
from remnawave import RemnawaveSDK
from remnawave.models import (
    CreateConfigProfileRequestDto,
    UpdateConfigProfileRequestDto,
    ReorderConfigProfilesRequestDto,
)

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_profiles():
    # List all profiles
    profiles = await sdk.config_profiles.get_config_profiles()
    for p in profiles.response:
        print(p.uuid, p.name)

    # Get a single profile
    profile_uuid = profiles.response[0].uuid
    p = await sdk.config_profiles.get_config_profile_by_uuid(str(profile_uuid))

    # Get its inbounds
    inbounds = await sdk.config_profiles.get_inbounds_by_profile_uuid(str(profile_uuid))

    # All inbounds across all profiles
    all_inbounds = await sdk.config_profiles.get_all_inbounds()

    # Computed (merged) config
    computed = await sdk.config_profiles.get_computed_config_profile_by_uuid(str(profile_uuid))

    # Delete
    result = await sdk.config_profiles.delete_config_profile_by_uuid(str(profile_uuid))
    print(result)

asyncio.run(demo_profiles())
```

--------------------------------

### Generate Public Key for Node Registration

Source: https://context7.com/remnawave/python-sdk/llms.txt

Use this snippet to generate a public key for enrolling new nodes that require key-based authentication. Ensure the SDK is initialized with the correct base URL and token.

```python
import asyncio
from remnawave import RemnawaveSDK

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_keygen():
    pub_key = await sdk.keygen.generate_key()
    print(pub_key)   # GetPubKeyResponseDto

asyncio.run(demo_keygen())
```

--------------------------------

### Auth Controller

Source: https://context7.com/remnawave/python-sdk/llms.txt

Handles login, registration, status checks, and OAuth2/Passkey authentication.

```APIDOC
## Auth Controller — `sdk.auth`

Login, registration, status check, OAuth2 (generic + Telegram), and Passkey authentication.

Most production deployments use token-based SDK auth, but the auth controller is useful for building admin UIs or automation that needs to obtain tokens programmatically.

```python
import asyncio
from remnawave import RemnawaveSDK
from remnawave.models import LoginRequestDto, RegisterRequestDto

sdk = RemnawaveSDK(base_url="https://vpn.example.com", token="...")

async def demo_auth():
    # Check token validity
    status = await sdk.auth.get_status()
    print(status)

    # Login with credentials (returns JWT)
    login_resp = await sdk.auth.login(
        body=LoginRequestDto(username="admin", password="secret")
    )
    print(login_resp)

asyncio.run(demo_auth())
```
```

--------------------------------

### List All Nodes

Source: https://context7.com/remnawave/python-sdk/llms.txt

Retrieves a list of all configured proxy nodes.

```APIDOC
## List All Nodes

### Description
Retrieves a list of all configured proxy nodes.

### Method
`sdk.nodes.get_all_nodes`

### Response
#### Success Response (200)
- **nodes** (list[NodeResponseDto]) - A list of NodeResponseDto objects, each representing a node.
```