NexaLayer SDK

Managed network sessions for Playwright, Browser Use, AI agents, and automation scripts.

Keep using proxies. Stop managing them.
中文：代理继续使用，代理管理交给 NexaLayer。

This repository contains the Python and Node/TypeScript SDK source. Signed release artifacts are published to PyPI and npm through GitHub Trusted Publishing and npm provenance.

Status

The separately published MCP server, @nexalayer/mcp, is 0.1.5.

Installation

Python:

pip install nexalayer

Node / TypeScript:

npm install @nexalayer/sdk

Authentication

export NEXALAYER_BASE_URL=https://api.nexalayer.net/v1
export NEXALAYER_API_KEY=agk_your_key

The SDK uses X-API-Key for Agent requests.

Pricing

• Dynamic proxy sessions start at $0.23/GB.
• Shared static proxy sessions start at $1.05/month.

Use GET /v1/public/products for unauthenticated discovery or client.get_products() for the current authenticated catalog and authoritative quote before creating a paid session. Prices and availability can change.

60-second Python example

This example auto-selects a dynamic product, creates a session, reports telemetry, reads health, and terminates the session in cleanup.

import os
import time
import uuid

import requests
from nexalayer import NexaLayerClient

api_key = os.environ["NEXALAYER_API_KEY"]
client = NexaLayerClient(api_key=api_key)
session_id = None

def data(resp):
    return resp.get("data", resp)

try:
    products = data(client.get_products(type="dynamic"))
    product = next(p for p in products.get("items", []) if p.get("product_no"))

    session = client.create_session(
        session_type="dynamic",
        product_no=product["product_no"],
        quantity=1,
        protocol="socks5",
        rotation_mode="on_demand",
        idempotency_key=f"py-{uuid.uuid4()}",
    )
    session_id = session.session_id

    for _ in range(60):
        current = data(client.get_session(session_id, include_credentials=True))
        if current.get("status") == "active":
            proxy_url = current["proxy"]["full_url"]
            break
        time.sleep(2)
    else:
        raise TimeoutError("Session did not become active")

    res = requests.get(
        "https://httpbin.org/ip",
        proxies={"http": proxy_url, "https": proxy_url},
        timeout=30,
    )
    client.report_event(
        session_id,
        event_type="success" if res.ok else "http_error",
        status_code=res.status_code,
        target_host="httpbin.org",
    )
    print(client.get_session_health(session_id))
finally:
    if session_id:
        client.terminate_session(session_id)

Dynamic Session

Use a dynamic session when your automation can rotate after errors such as timeout, 403, 429, or explicit blocks.

session = client.create_session(
    session_type="dynamic",
    product_no="selected_from_products_api",
    quantity=1,
    protocol="socks5",
    rotation_mode="on_demand",
)

Static Session

Use a static session when you need fixed network identity for a longer-lived task.

session = client.create_session(
    session_type="static",
    product_no="selected_from_products_api",
    quantity=1,
    duration=30,
    protocol="socks5",
)

Telemetry

client.report_event(
    session_id,
    event_type="timeout",
    status_code=0,
    target_host="example.com",
)

Health

health = client.get_session_health(session_id)

timeout, captcha, block, and repeated HTTP errors are not neutral noise; report them so NexaLayer can score the session and recommend rotate or pause.

Credentials and usage

get_session() and rotate_session() hide proxy.full_url and other proxy credentials by default. Request credentials only at the point where the client needs to connect:

session_data = client.get_session(session_id, include_credentials=True)

Read measured traffic and request usage for a session with:

usage = client.get_session_usage(session_id)
# Equivalent session helper:
usage = session.usage()

Cleanup

Always terminate sessions you no longer need:

try:
    ...
finally:
    if session_id:
        client.terminate_session(session_id)

Playwright

Use the public Playwright examples:

• Chinese: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
• English: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session

中文文档

• 中文快速开始: https://docs.nexalayer.net/zh/quick-start
• Playwright 中文 Demo: https://docs.nexalayer.net/zh/examples
• API 文档: https://docs.nexalayer.net/api-reference/openapi

Error handling

• Check backend_ready=true before creating paid sessions after registration.
• Use Idempotency-Key for create, rotate, renew, and recharge operations.
• PRODUCT_NOT_FOUND is returned with HTTP 404 when product_no is unknown or unavailable.
• PRICE_MISMATCH is returned with HTTP 409 when the upstream charge does not match the displayed quote; the order is rejected before charging.
• proxy.full_url is hidden by default. When explicitly requested with include_credentials=True, treat it as a secret and never log it without redaction.
• Respect target website terms and applicable law.

Contributing

See CONTRIBUTING.md.

Security

Do not open public issues with API keys, cookies, account passwords, proxy credentials, or target-site secrets. See SECURITY.md.