owlproxy-sdk 0.1.0

Python client for OwlProxy's token-authenticated site API

OwlProxy Python

A typed Python client for OwlProxy's token-authenticated site API. It adapts every callable endpoint in OwlProxy's public OpenAPI documentation to the equivalent working site route by removing the openApi/ path segment and authenticating with a site token.

This is an unofficial library. OwlProxy's site API is not the same stability contract as its documented HMAC OpenAPI and may change without notice.

Installation

pip install owlproxy

For local development:

git clone <repository-url>
cd owlproxy
python -m pip install -e '.[dev]'

Authentication

Create a client with the token header value used by proxy.owlproxy.com:

import os

from owlproxy import OwlProxyClient

client = OwlProxyClient(os.environ["OWLPROXY_SITE_TOKEN"])

A user ID can be supplied if an account or endpoint requires it:

client = OwlProxyClient(
    os.environ["OWLPROXY_SITE_TOKEN"],
    user_id=os.environ.get("OWLPROXY_USER_ID"),
)

Never commit site tokens. A token grants access to account data and purchasing or renewal actions.

Response and error behavior

Methods return OwlProxy's decoded JSON response:

response = client.static.list()
records = response["data"]["records"]

By default, a JSON response whose code is not 200 raises OwlProxyAPIError. HTTP, transport, and decoding failures raise dedicated exception classes:

from owlproxy import OwlProxyAPIError, OwlProxyError

try:
    client.dynamic.traffic_balance()
except OwlProxyAPIError as error:
    print(error.code, error.message)
except OwlProxyError as error:
    print(error)

Set raise_for_api_errors=False to receive non-200 API responses directly.

Static IP API

client.static.proxy_types(proxy_mode=1)
client.static.countries(proxy_type=4)
client.static.quality_options(proxy_type=4)
client.static.providers("US", proxy_type=4, proxy_id_type="ord")
client.static.packages(2, "US", proxy_type=4, proxy_id_type="ord")

List proxies:

response = client.static.list(
    current=1,
    size=20,
    proxy_name="",
    proxy_buy_status_id="",
    group_id_list=[],
)

Find a proxy and disable automatic renewal:

response = client.static.list(size=100, proxy_name="62.132.16.64")
proxy = next(
    item
    for item in response["data"]["records"]
    if item["proxyHost"] == "62.132.16.64"
)
client.static.set_auto_renew(proxy["proxyId"], False)

Purchase and order information:

client.static.create_order(
    proxy_good_id=1,
    num=1,
    country="US",
    proxy_shop_id=1,
    auto_renew=False,
    back_url="https://example.com/owlproxy/callback",
)
client.static.ip_info(["Owl-PROXY123"])
client.static.orders(page=1, rows=20)

Maintenance:

client.static.update_name(proxy_id=93847, proxy_name="production")
client.static.calculate_renew_price(["192.0.2.10"], renewal_days=30)
client.static.renew(
    proxy_good_id=1,
    proxy_shop_id=1,
    proxy_ips="192.0.2.10",
    back_url="https://example.com/owlproxy/callback",
)

Dynamic proxy API

client.dynamic.traffic_balance()
client.dynamic.packages()
client.dynamic.regions()
client.dynamic.lines()
client.dynamic.automatic_renewal()
client.dynamic.orders(page=1, rows=20)

Purchase, extract, and renewal settings:

client.dynamic.create_order(good_id=1, good_num=1, auto_renew_order=0)
client.dynamic.extract(
    country_code="AE",
    state="Sharjah",
    city="Sharjahcity",
    proxy_host="change4.owlproxy.com:7778",
    proxy_type="socks5",
    time=5,
    good_num=1,
)
client.dynamic.set_auto_renew(False)

Complete endpoint mapping

Library method	Site route	Documented OpenAPI route
static.proxy_types	GET /owlproxy/api/vcProxyShop/getProxyTypeList	GET /owlproxy/api/openApi/vcProxyShop/getProxyTypeList
static.countries	GET /owlproxy/api/vcProxyGood/getProxyCountry	GET /owlproxy/api/openApi/vcProxyGood/getProxyCountry
static.quality_options	GET /owlproxy/api/vcProxyGood/proxyIdType	GET /owlproxy/api/openApi/vcProxyGood/proxyIdType
static.providers	POST /owlproxy/api/vcProxyShop/getProxyShopList	POST /owlproxy/api/openApi/vcProxyShop/getProxyShopList
static.packages	GET /owlproxy/api/vcProxyGood/proxyGoodList	GET /owlproxy/api/openApi/vcProxyGood/proxyGoodList
static.create_order	POST /owlproxy/api/vcProxyGood/createProxyOrder	POST /owlproxy/api/openApi/vcProxyGood/createProxyOrder
static.ip_info	POST /owlproxy/api/vcProxy/queryByorderIdList	POST /owlproxy/api/openApi/vcProxy/queryByorderIdList
static.list	POST /owlproxy/api/vcProxy/queryList	POST /owlproxy/api/openApi/vcProxy/queryList
static.update_name	GET /owlproxy/api/vcProxy/updateProxyName	GET /owlproxy/api/openApi/vcProxy/updateProxyName
static.renew	POST /owlproxy/api/vcProxyGood/createRenewProxyOrder	POST /owlproxy/api/openApi/vcProxyGood/createRenewProxyOrder
static.calculate_renew_price	POST /owlproxy/api/vcProxy/batchCalculateRenewPrice	POST /owlproxy/api/openApi/vcProxy/batchCalculateRenewPrice
static.set_auto_renew	POST /owlproxy/api/vcProxy/autoRenewClose	POST /owlproxy/api/openApi/vcProxy/autoRenewClose
static.orders	POST /owlproxy/api/vcProxyOrder/selectProxyOrderList	POST /owlproxy/api/openApi/vcProxyOrder/selectProxyOrderList
dynamic.traffic_balance	GET /owlproxy/api/vcDynamicGood/queryCurrentTrafficBalance	GET /owlproxy/api/openApi/vcDynamicGood/queryCurrentTrafficBalance
dynamic.packages	GET /owlproxy/api/vcDynamicGood/getDynamicGoodService	GET /owlproxy/api/openApi/vcDynamicGood/getDynamicGoodService
dynamic.create_order	POST /owlproxy/api/vcDynamicGood/buyDynamicProxy	POST /owlproxy/api/openApi/vcDynamicGood/buyDynamicProxy
dynamic.regions	GET /owlproxy/api/vcDynamicGood/getDynamicProxyRegion	GET /owlproxy/api/openApi/vcDynamicGood/getDynamicProxyRegion
dynamic.lines	GET /owlproxy/api/vcDynamicGood/getDynamicProxyHost	GET /owlproxy/api/openApi/vcDynamicGood/getDynamicProxyHost
dynamic.extract	POST /owlproxy/api/vcDynamicGood/createProxy	POST /owlproxy/api/openApi/vcDynamicGood/createProxy
dynamic.automatic_renewal	GET /owlproxy/api/vcDynamicGood/getDynamicProxyAutomaticRenewal	GET /owlproxy/api/openApi/vcDynamicGood/getDynamicProxyAutomaticRenewal
dynamic.set_auto_renew	POST /owlproxy/api/vcDynamicGood/setAutoRenewSwitch	POST /owlproxy/api/openApi/vcDynamicGood/setAutoRenewSwitch
dynamic.orders	POST /owlproxy/api/vcDynamicGood/getDynamicProxyOrders	POST /owlproxy/api/openApi/vcDynamicGood/getDynamicProxyOrders

The payment callback is inbound rather than an OwlProxy request, so it is documented but is not a client method.

Raw requests

New or undocumented site endpoints can be called without waiting for a release:

client.get("vcDynamicGood/getDynamicGoodService")
client.post("vcProxy/queryList", {"current": 1, "size": 20})
client.request("POST", "some/path", json={"key": "value"})

Publishing

python -m pytest
python -m build
python -m twine check dist/*
python -m twine upload dist/*

Verify that the owlproxy package name is available on PyPI before publishing. Change project.name if it is already owned by another publisher.