Metadata-Version: 2.4
Name: nexrade-req
Version: 1.0.0
Summary: Fast HTTP client for trading bots — rate-limit bypass via Nexrade relay nodes
Home-page: https://github.com/nexrade/nexrade-req
Author: Vuong Phu
Author-email: vuongphudev@gmail.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyureq>=0.1.4
Provides-Extra: dev
Requires-Dist: pytest>=6.2.3; extra == "dev"
Requires-Dist: pytest-cov>=2.11.1; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# nexrade-req

[![PyPI](https://img.shields.io/pypi/v/nexrade-req.svg)](https://pypi.org/project/nexrade-req/)
[![Python 3.9+](https://img.shields.io/pypi/pyversions/nexrade-req.svg)](https://pypi.org/project/nexrade-req/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Fast Python HTTP client for trading bots — bypasses exchange rate limits by routing requests through **Nexrade relay nodes**.

Part of the [Nexrade](https://nexrade.com) ecosystem.

---

## How it works

```
Your bot
   │
   ▼
nexrade-req  ──(no api_key)──▶  direct request to exchange
   │
   └──(with api_key)──▶  Nexrade relay node  ──▶  exchange
                         (rotates IPs, bypasses rate limits)
```

- **Without `api_key`**: behaves like a normal fast HTTP client
- **With `api_key`**: routes through Nexrade's relay network — each request gets a fresh IP, bypassing exchange rate limits

---

## Installation

```bash
pip install nexrade-req
```

---

## Quick start

```python
import nexrade_req as req

# Simple GET (no relay)
r = req.get("https://api.binance.com/api/v3/ticker/price", params={"symbol": "BTCUSDT"})
print(r.status_code, r.json())

# POST
r = req.post("https://httpbin.org/post", json={"key": "value"})
print(r.json())
```

---

## Using the relay network (bypass rate limits)

```python
from nexrade_req import Client

client = Client(api_key="your_nexrade_api_key")

# All requests are routed through Nexrade relay nodes
r = client.get("https://api.binance.com/api/v3/ticker/price", params={"symbol": "ETHUSDT"})
print(r.json())
```

Get your API key at **[nexrade.com](https://nexrade.com)**.

---

## Session (connection reuse)

```python
from nexrade_req import Client

with Client(api_key="your_key") as c:
    r1 = c.get("https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT")
    r2 = c.get("https://api.binance.com/api/v3/ticker/price?symbol=ETHUSDT")
```

---

## Custom relay nodes

```python
from nexrade_req import Client

client = Client(
    api_key="your_key",
    base_urls=["https://your-own-relay.example.com"],
    endpoint="api/scraper",
    timeout=10,
    max_retries=3,
)
```

---

## Fallback client

`FallbackClient` retries through the relay, then falls back to a direct request if all relay attempts fail.

```python
from nexrade_req import FallbackClient

r = FallbackClient.get(
    "https://api.binance.com/api/v3/ticker/price",
    params={"symbol": "BTCUSDT"},
    max_retries=3,
)
print(r.json())
```

---

## API reference

### Top-level functions

```python
import nexrade_req as req

req.get(url, **kwargs)
req.post(url, data=None, json=None, **kwargs)
req.put(url, data=None, **kwargs)
req.patch(url, data=None, **kwargs)
req.delete(url, **kwargs)
req.head(url, **kwargs)
req.options(url, **kwargs)
req.request(method, url, **kwargs)
```

### `Client` constructor

| Parameter | Default | Description |
|---|---|---|
| `api_key` | `None` | Nexrade API key — enables relay routing |
| `base_urls` | Nexrade nodes | List of relay node URLs |
| `endpoint` | `"api/scraper"` | Relay endpoint path |
| `max_retries` | `1` | Retry attempts on failure |
| `timeout` | `6` | Request timeout in seconds |
| `is_random_base_url` | `True` | Rotate relay nodes randomly |

### Common request kwargs

| Argument | Description |
|---|---|
| `params` | Query string dict |
| `data` | Form body or raw bytes |
| `json` | JSON body |
| `headers` | Extra HTTP headers |
| `timeout` | Override timeout per request |
| `proxies` | Proxy dict `{"https": "http://..."}` |
| `verify` | TLS certificate verification |

### `Response`

| Attribute | Description |
|---|---|
| `.status_code` | HTTP status code |
| `.text` | Response body as string |
| `.content` | Response body as bytes |
| `.json()` | Parse body as JSON |
| `.headers` | Response headers |
| `.url` | Final URL |
| `.raise_for_status()` | Raise on 4xx/5xx |

---

## Exceptions

```python
from nexrade_req.exceptions import NexradeException

try:
    r = client.get("https://api.binance.com/...")
except NexradeException as e:
    print("All relay attempts failed:", e)
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## Part of Nexrade

| Product | Description |
|---|---|
| **nexrade-req** | This library — HTTP client with relay routing |
