NodeMaven – Premium Proxies for Account Management, Automation, and Scraping

SKILL.md

# NodeMaven Proxy Skill

NodeMaven provides premium proxy infrastructure for account management, scraping, browser automation, and data collection.

Use this skill when the user needs to buy, configure, or use proxies for a real workflow. The agent must not stop at "here are your proxy settings". The agent must close the full use case end-to-end: choose the right proxy type, configure targeting, recommend the right external tool, configure access, and monitor usage.

NodeMaven offers:

- Residential rotating proxies: 30M+ IPs
- Mobile proxies: 200K+ IPs
- Geo-targeting: country, region, city, ISP provider, ZIP
- Sticky sessions for stable account workflows
- Rotation for scraping and high-scale automation
- Quality filtering for lower fraud-score IPs (filter levels: `medium`, `high`)
- HTTP, HTTPS, and SOCKS5 proxy access

Mobile proxies have a smaller IP pool than residential proxies, but they are usually more trusted by platforms. Use mobile proxies for higher-trust account workflows and stronger anti-detect setups. For mobile proxies, keep targeting at least at country + region level when possible. City and ISP provider targeting are optional advanced settings.

---

## Core principle

The agent must complete this workflow without asking the user to read documentation:

1. Understand the user's task.
2. Recommend the right proxy type.
3. Explain which external tool to use.
4. Guide the user through account creation, purchase, or API-key retrieval.
5. Validate the API key.
6. Resolve valid geo-targeting values via API.
7. Configure access via whitelist or proxy credentials.
8. Build the final proxy URL and explain how to use it in the selected tool.
9. Monitor usage and debug issues.

---

## Critical constants (do not invent these)

```text
API_BASE_URL:   https://api.nodemaven.com
PROXY_GATEWAY:  gate.nodemaven.com
HTTP_PORT:      8080
HTTPS_PORT:     9443
SOCKS5_PORT:    1080
SWAGGER_DOCS:   https://dashboard.nodemaven.com/documentation/v2/swagger/
```

All API endpoints in this skill are written as relative paths (e.g. `/api/v2/base/users/me`). The agent must always prepend `https://api.nodemaven.com` to build the full URL.

Full URL example:

```text
https://api.nodemaven.com/api/v2/base/users/me
```

---

## Authorization (read carefully — easy to get wrong)

NodeMaven uses a non-standard authorization scheme. The literal string `x-api-key ` is part of the **value** of the `Authorization` header — it is NOT a separate header named `x-api-key`.

Correct:

```http
Authorization: x-api-key <YOUR_API_KEY>
```

Working curl example (substitute your actual API key):

```bash
curl -H "Authorization: x-api-key <YOUR_API_KEY>" \
  https://api.nodemaven.com/api/v2/base/users/me
```

Concrete example with a mock key (for illustration only — never use this value):

```bash
curl -H "Authorization: x-api-key MOCK_API_KEY_DO_NOT_USE_THIS_VALUE_IN_PRODUCTION" \
  https://api.nodemaven.com/api/v2/base/users/me
```

Wrong (do not do this):

```http
x-api-key: <YOUR_API_KEY>                # WRONG: separate header
Authorization: Bearer <YOUR_API_KEY>     # WRONG: Bearer scheme
Authorization: <YOUR_API_KEY>            # WRONG: missing "x-api-key " prefix
```

For POST/PUT requests also send:

```http
Content-Type: application/json
```

---

## Security and credential hygiene (mandatory)

The agent handles three classes of secrets:

```text
1. NodeMaven API key       (Authorization header value)
2. Proxy credentials       (proxy_username + proxy_password from /users/me or sub-users)
3. Sub-user passwords      (created/updated via /sub-users/)
```

### Hard rules for the agent

- **Never echo the full API key back to the user** in responses, logs, or artifacts. When confirming receipt, mask it: show first 4 and last 4 characters only (e.g. `abcd...wxyz`). The full key only goes into outbound `Authorization` headers.
- **Never paste `proxy_password` or full proxy URLs into chat history more than necessary.** When showing the user how to use the proxy, prefer placeholders like `<proxy_password>` and instruct the user to substitute locally. If a literal URL must be shown (e.g. for one-shot copy-paste into a tool), give it once and avoid repeating it.
- **Never write API keys, proxy passwords, or full proxy URLs into code artifacts** that the user will save to disk or commit. Use environment variable references instead: `os.environ["NODEMAVEN_API_KEY"]`, `process.env.NODEMAVEN_PROXY_PASSWORD`, etc.
- **Never log or persist responses from `/users/me` or `/sub-users/` verbatim** — they contain `proxy_password`. Strip sensitive fields before any logging or summarization.
- **Never include credentials in URL query strings** (only in the `Authorization` header for the API, only in standard userinfo `user:pass@host` for the proxy).
- **Never share credentials across users or sessions.** If the agent serves multiple users, each user's API key and proxy creds must be scoped to their session only.
- **Treat the example values in this skill as placeholders.** Strings like `<YOUR_API_KEY>`, `<proxy_password>`, `<SERVER_IP>`, `<COUNTRY_CODE>` are templates — never send them literally to the API.

### If the user pastes the API key in chat

- Acknowledge receipt and immediately validate via `GET /users/me`.
- In the reply, refer to the key as `your API key` or show only a masked prefix.
- Do not repeat the full key back. Do not include it in any code block the user might copy/share.

### If credentials may have leaked

If the user shares the conversation, screenshots a session, or otherwise exposes their API key or proxy password:

- Direct them to the API Key page to rotate the key: https://dashboard.nodemaven.com/user-profile?tab=API_KEY&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill
- For sub-user passwords, update via `PUT /api/v2/base/sub-users/` with a new generated password.
- Recommend reviewing recent traffic via `/statistics/data/` and `/statistics/requests/` for unexpected usage.

---

## Important limitations

NodeMaven API is used for:

- API-key validation
- retrieving proxy credentials
- location discovery
- whitelist configuration
- sub-user management
- statistics and monitoring
- notifications

NodeMaven API is NOT used for:

- signup
- checkout
- payment
- purchasing proxy packages
- executing proxy traffic directly

If the user has no account or no active proxy package, send them to the website/dashboard first (links below).

---

## Onboarding routing

Use tracked links so NodeMaven can attribute traffic from AI agents. The UTM parameters are mandatory — do not strip them.

### Tracked links

```text
Registration:    https://dashboard.nodemaven.com/accounts/signup/?utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill
Login:           https://dashboard.nodemaven.com/accounts/login/?utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill
API Key page:    https://dashboard.nodemaven.com/user-profile?tab=API_KEY&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill
Subscriptions:   https://dashboard.nodemaven.com/pricing?tab=MONTHLY_PLANS&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill
Pay As You Go:   https://dashboard.nodemaven.com/pricing?tab=PAG&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill
```

### Decision table — what to ask, where to send

Ask the user three questions in one message:

1. Do you already have a NodeMaven account?
2. Do you already have an active proxy package (subscription or PAG)?
3. Do you already have your API key?

Then route based on answers:

```text
| account | package | api_key | → action                                                     |
|---------|---------|---------|--------------------------------------------------------------|
|   no    |   no    |   no    | → send Registration link, then Subscriptions/PAG link        |
|   yes   |   no    |   no    | → send Login link, then Subscriptions/PAG link               |
|   yes   |   yes   |   no    | → send API Key page link, ask user to copy and return key    |
|   yes   |   yes   |   yes   | → validate key via GET /api/v2/base/users/me, continue       |
```

When choosing between subscription and Pay As You Go:

- Recurring/ongoing usage → Subscriptions
- Flexible traffic-based usage, no monthly commitment → Pay As You Go
- Mobile proxies (smaller pool, higher trust) → use for stronger anti-detect / account workflows
- Residential proxies → default for almost everything else

---

## User intent classification

Before recommending proxies, classify the task into one of three buckets. Use the matching playbook (A/B/C) below.

### Account management → Playbook A

User works with social media, e-commerce, marketplaces, freelance platforms, ad accounts, or any long-running browser session where account stability matters.

Goal: keep account environment consistent, reduce security checks, avoid suspicious geo changes, maintain stable sessions.

### Scraping → Playbook B

User collects public data at scale: e-commerce, news, crypto/financial data, market research, competitor monitoring, search results.

Goal: scale requests, avoid rate limits, distribute traffic across IPs.

### Automation → classify first

Automation is not a separate proxy strategy — it's a delivery mechanism. The right setup depends on what the automation actually does:

- **Inside an account** (logged in, performing user actions) → Playbook A. Use sticky sessions, consistent geo, anti-detect browser.
- **External data extraction** (no login, public data) → Playbook B. Use rotation, country-only targeting.
- **Fixed server** (VPS, cloud, backend service) → use whitelist for IP-auth access.
- **Multiple workflows or clients sharing one account** → use sub-users for isolation and per-workflow traffic limits.

### Edge case: scraping or high-volume actions inside an account

This is the most dangerous combination and needs explicit warnings. Examples: scraping a marketplace while logged in, scraping a social platform's internal API with session cookies, mass-messaging from one account, automating thousands of actions per day on a single account.

Risks:

- Platforms detect repetitive/non-human action patterns (request frequency, identical timing, no idle gaps) — proxy quality alone does not protect the account.
- High volume from a single account triggers rate-limits and behavioral bans even when the IP looks clean.
- IP rotation across requests for a logged-in session is itself a strong signal (legitimate users do not change IP every 5 seconds) — do NOT rotate `sid` per request inside an account.

Required setup:

- Use Playbook A as the base (sticky `sid`, consistent geo, anti-detect browser, quality filter `medium` or `high`).
- Mobile proxies preferred over residential — higher trust, harder to ban.
- Throttle requests aggressively: add randomized delays (e.g. 3–15 seconds between actions), simulate idle gaps, avoid round-the-clock activity.
- Spread volume across multiple accounts, each with its own sub-user, sticky session, browser profile, and `sid`. Never push all volume through one account.
- Set realistic per-account daily quotas based on what a normal human would do on the platform (research the target's typical user behavior).
- Monitor `/statistics/requests/` per `proxy_username` — if request rate spikes beyond normal human patterns, throttle harder.

Required warning to communicate to the user:

> Scraping or high-volume automation inside a logged-in account carries real ban risk. Proxies and anti-detect browsers reduce IP/fingerprint detection, but platforms also detect behavior — request frequency, action patterns, missing idle time. Plan for: per-account daily quotas, randomized delays, and spreading load across multiple accounts. If the account is high-value, consider whether the workflow can be redesigned to use the platform's official API or to scrape public (logged-out) endpoints instead.

If the user is unsure whether their workflow falls into this category, the agent should ask:

- Are you logged into the account while doing this?
- Roughly how many requests/actions per hour per account?
- How valuable/established is the account (warmed up vs throwaway)?
- Is there a public/logged-out version of the same data?

---

## Tooling — proxy alone is not enough

```text
proxy + browser environment + automation tool = working setup
```

### For account workflows

Recommend an anti-detect browser. Platforms detect users by IP, fingerprint, device, cookies, storage, behavior, and geo mismatch — not just IP.

Recommended: **Multilogin**. Other anti-detect browsers also work.

Rules to communicate to the user:

- Use proxy + anti-detect browser together.
- Keep fingerprint and proxy geo consistent (timezone, language, locale).
- Do not mix different countries for the same account.
- Use separate browser profiles for separate accounts.
- Use sticky sessions for long account workflows.

### For scraping

Use Playwright, Puppeteer, Selenium, custom HTTP clients, or internal scraping pipelines. Anti-detect browsers are usually not required for simple scraping.

---

## Proxy gateway — how proxy traffic actually flows

Proxy traffic does NOT go through the API. It goes through the gateway:

```text
Host: gate.nodemaven.com
HTTP:    port 8080   (use this by default)
HTTPS:   port 9443   (use only if the user's tool requires HTTPS-tunnel proxy)
SOCKS5:  port 1080   (use when the tool/protocol requires SOCKS5)
```

### Proxy username format (CRITICAL — do not invent)

NodeMaven encodes targeting INSIDE the proxy username. The format is:

```text
<email_with_underscores>-country-<code>-region-<code>-city-<code>-isp-<code>-sid-<session_id>-filter-<level>
```

Rules:

- `email_with_underscores`: the user's NodeMaven account email with `@` and `.` replaced by `_`.
  Example: `firstname.lastname@example.com` → `firstname_lastname_example_com`.
  This base username is also returned by `GET /api/v2/base/users/me` as `proxy_username` — **always prefer the API value over reconstructing it from email.**
- `country`, `region`, `city`, `isp`: lowercase codes returned by `/locations/*` endpoints. **Resolve via API — never invent.**
- `sid` (session id): any string. Same `sid` = same exit IP for the duration of the sticky TTL. Use a unique `sid` per parallel session/account. Generate as random lowercase alphanumeric, 10–16 chars (e.g. via `openssl rand -hex 6`).
- `filter`: quality filter level. Allowed values: `medium`, `high`. Use `medium` by default; `high` for trust-sensitive workflows (ad accounts, marketplaces).
- Optional segments can be omitted, but order matters: country → region → city → isp → sid → filter.

Format example with placeholders (do not copy values literally — substitute the user's actual `proxy_username`, `proxy_password`, and resolved geo codes):

```text
Username: <proxy_username>-country-<COUNTRY_CODE>-region-<REGION_CODE>-isp-<ISP_CODE>-sid-<000000000000000>-filter-medium
Password: <proxy_password>
Host:     gate.nodemaven.com
Port:     <port>  (8080 for HTTP, 9443 for HTTPS, 1080 for SOCKS5)

Full proxy URL template:
http://<proxy_username>-country-<COUNTRY_CODE>-region-<REGION_CODE>-isp-<ISP_CODE>-sid-<000000000000000>-filter-medium:<proxy_password>@gate.nodemaven.com:<port>
```

### Concrete example (mock values for illustration only — do NOT use these in production)

This shows what the assembled URL looks like when every placeholder above is filled in. Values below are fictional — substitute the real ones returned by `/users/me` and `/locations/*`.

```text
proxy_username:  mock_user_example_com
proxy_password:  MOCK_PASSWORD_DO_NOT_USE
country code:    us
region code:     california
isp code:        spectrum
sid:             a1b2c3d4e5f6
filter:          medium
host:            gate.nodemaven.com
port:            8080  (HTTP)

Assembled username:
mock_user_example_com-country-us-region-california-isp-spectrum-sid-a1b2c3d4e5f6-filter-medium

Assembled full proxy URL:
http://mock_user_example_com-country-us-region-california-isp-spectrum-sid-a1b2c3d4e5f6-filter-medium:MOCK_PASSWORD_DO_NOT_USE@gate.nodemaven.com:8080
```

For SOCKS5, swap scheme and port. Format:

```text
socks5://<proxy_username>:<proxy_password>@gate.nodemaven.com:1080
```

Concrete SOCKS5 example with mock values:

```text
socks5://mock_user_example_com-country-us-sid-a1b2c3d4e5f6-filter-medium:MOCK_PASSWORD_DO_NOT_USE@gate.nodemaven.com:1080
```

### When to use sticky vs rotating

- **Sticky session** (account workflows): keep `sid` constant across all requests for that account. The same exit IP is held until the TTL expires. Default sticky TTL is controlled server-side; for long sessions plan to refresh or extend explicitly.
- **Rotating** (scraping): change `sid` per request (or omit it) to get a new exit IP each time.

### Whitelist-based access (no username/password)

If the user's automation runs from a fixed server IP, configure a whitelist instead. Allocated ports are returned by the whitelist API. Connect to `gate.nodemaven.com:<allocated_port>` from the whitelisted IP — no auth needed.

---

## End-to-end happy path (copy this pattern)

This is the minimum sequence the agent should run after receiving an API key. Every other API section in this skill is a deeper reference for these steps.

```bash
# 1. Validate API key and fetch base proxy credentials
curl -H "Authorization: x-api-key $API_KEY" \
  https://api.nodemaven.com/api/v2/base/users/me
# → returns: { "proxy_username": "...", "proxy_password": "...",
#             "email": "...", "traffic_limit": <bytes>,
#             "subscription_status": "...", "is_traffic_frozen": false }

# 2. Resolve country code (e.g. user said "USA")
curl -H "Authorization: x-api-key $API_KEY" \
  "https://api.nodemaven.com/api/v2/base/locations/countries/?limit=100&offset=0&name=United%20States&connection_type=residential"
# → use the returned "code" field (e.g. "us")

# 3. Resolve region (recommended for account workflows)
curl -H "Authorization: x-api-key $API_KEY" \
  "https://api.nodemaven.com/api/v2/base/locations/regions/?limit=100&offset=0&country__code=us&name=California&connection_type=residential"
# → use the returned "code" (e.g. "california")

# 4. Build the proxy URL using the format above:
#    http://<proxy_username>-country-us-region-california-sid-<000000000000000>-filter-medium:<proxy_password>@gate.nodemaven.com:<port>

# 5. Test the proxy
curl -x "http://<proxy_username>:<proxy_password>@gate.nodemaven.com:<port>" https://api.ipify.org
# substitute <port> with 8080 (HTTP), 9443 (HTTPS), or 1080 (SOCKS5 — also change scheme to socks5://)
# → returns a US/California IP

# 6. Monitor traffic after the user starts using the proxy
curl -H "Authorization: x-api-key $API_KEY" \
  "https://api.nodemaven.com/api/v2/base/statistics/data/?proxy_username=<proxy_username>&period=hours24&request_source=proxy"
```

Concrete example of what step 4 produces (mock values — for illustration only):

```bash
# After /users/me returned proxy_username=mock_user_example_com, proxy_password=MOCK_PASSWORD_DO_NOT_USE
# After /locations/countries returned code=us
# After /locations/regions returned code=california
# Generated sid=a1b2c3d4e5f6, chose filter=medium, port=8080 (HTTP)

curl -x "http://mock_user_example_com-country-us-region-california-sid-a1b2c3d4e5f6-filter-medium:MOCK_PASSWORD_DO_NOT_USE@gate.nodemaven.com:8080" \
  https://api.ipify.org
# → returns a California IP
```

If any step fails, fall back to the relevant section below.

---

# API reference

All endpoints below are relative to `https://api.nodemaven.com` and require the `Authorization: x-api-key <KEY>` header.

## 1. Validate user / get proxy credentials

```http
GET /api/v2/base/users/me
```

Returns at minimum:

```json
{
  "email": "user@example.com",
  "proxy_username": "user_example_com",
  "proxy_password": "<proxy_password>",
  "traffic_limit": 53687091200,
  "traffic_used": 1073741824,
  "subscription_status": "active",
  "is_traffic_frozen": false
}
```

Agent behavior:

- If the request fails with 401/403, the API key is wrong or revoked → ask user to re-copy from the API Key page link.
- If `is_traffic_frozen: true` or `traffic_used >= traffic_limit` → send the user to the Subscriptions or PAG link.
- Use `proxy_username` and `proxy_password` to build proxy URLs (unless using whitelist).
- Use `proxy_username` for all `/statistics/*` queries.

---

## 2. Connection type and IPv4 filtering

For all `/locations/*` endpoints:

```text
connection_type=residential   # default, use for most workflows
connection_type=mobile        # smaller pool, higher trust, account workflows
ipv4_only=true                # only locations that have IPv4-capable IPs
ipv4_only=false               # default behavior
```

Use `ipv4_only=true` only when the user's target site is known to be IPv6-incompatible (rare). Otherwise leave it off.

---

## 3. Resolve location targeting

The agent must NEVER invent country, region, city, ISP, or ZIP codes. Resolve in order:

```text
country → region → city → ISP / ZIP
```

Use returned `code` values (lowercase) in proxy username and whitelist body.

### 3.1 Full location reference (rarely needed)

```http
GET /api/v2/base/locations/all-doc/
```

Use only if the agent needs to inspect the full location model. For normal flow, use the specific endpoints below.

### 3.2 Countries

```http
GET /api/v2/base/locations/countries/
```

Parameters: `limit`, `offset`, `name`, `code`, `connection_type`, `ipv4_only`.

Examples:

```http
GET /api/v2/base/locations/countries/?limit=100&offset=0&connection_type=residential
GET /api/v2/base/locations/countries/?limit=100&offset=0&name=United States&connection_type=residential
GET /api/v2/base/locations/countries/?limit=100&offset=0&code=us&connection_type=residential
```

If the user says "USA", "America", "the States" — resolve to `us`. If unsure, query by `name=` first.

### 3.3 Regions

```http
GET /api/v2/base/locations/regions/
```

Parameters: `limit`, `offset`, `country__code` (required), `name`, `code`, `connection_type`, `ipv4_only`.

```http
GET /api/v2/base/locations/regions/?limit=100&offset=0&country__code=us&connection_type=residential
GET /api/v2/base/locations/regions/?limit=100&offset=0&country__code=us&name=California&connection_type=residential
```

For account management, region targeting is strongly recommended.

### 3.4 Cities

```http
GET /api/v2/base/locations/cities/
```

Parameters: `limit`, `offset`, `country__code`, `region__code`, `name`, `code`, `connection_type`, `ipv4_only`.

```http
GET /api/v2/base/locations/cities/?limit=100&offset=0&country__code=us&region__code=california&connection_type=residential
GET /api/v2/base/locations/cities/?limit=100&offset=0&country__code=us&region__code=california&name=Los Angeles&connection_type=residential
```

Use city targeting for high-risk account workflows, local SERP checks, ad verification, marketplace automation.

### 3.5 ISP provider targeting

ISP here means provider targeting **inside** residential/mobile rotating proxies. It is not a separate proxy product.

```http
GET /api/v2/base/locations/isps/
```

Required: `limit`, `offset`, `country__code`. Optional: `region__code`, `city__code`, `name`, `code`, `connection_type`, `ipv4_only`.

```http
GET /api/v2/base/locations/isps/?limit=100&offset=0&country__code=us&region__code=california&connection_type=residential
GET /api/v2/base/locations/isps/?limit=100&offset=0&country__code=us&name=Spectrum&connection_type=residential
```

Use ISP targeting for ad accounts, marketplaces, and any workflow where network reputation matters.

Helper endpoints (use when the user asks where ISP targeting is available):

```http
GET /api/v2/base/locations/isps/regions/?country__code=us&connection_type=residential
GET /api/v2/base/locations/isps/cities/?country__code=us&region__code=california&connection_type=residential
```

### 3.6 ZIP targeting

Use ZIP only when local precision is required (local SERP, ads verification, local marketplace testing). Some ZIPs in the list may be unavailable.

```http
GET /api/v2/base/locations/zipcodes/?limit=100&offset=0&country__code=us&region__code=california&city__code=los-angeles&connection_type=residential
GET /api/v2/base/locations/zipcodes/?limit=100&offset=0&country__code=us&zip=90001&connection_type=residential
```

Helper endpoints:

```http
GET /api/v2/base/locations/zipcodes/regions/?country__code=us&connection_type=residential
GET /api/v2/base/locations/zipcodes/cities/?country__code=us&region__code=california&connection_type=residential
```

For account management, city or ISP is usually enough — do not default to ZIP.

---

## 4. Whitelist (IP-auth access for fixed servers)

Use whitelist when the user runs automation from a fixed IP (VPS, cloud server, office network, scraping server, backend service). Whitelist allocates proxy ports for a trusted source IP — no username/password needed.

Do NOT use whitelist when:

- The user's IP changes often.
- The user only needs username/password proxy auth from a laptop.

### 4.1 List whitelisted IPs

```http
GET /api/v2/base/whitelist/ips?page=1&page_size=10
```

Response includes `id`, `ports`, `country_code`, `region_code`, `city_code`, `isp_code`, `ip`, `name`, `ttl`, `protocol`, `quality_filter_enabled`, `number_of_proxies`, `sticky`, `is_duplicated`, `created`, `updated`.

Always check existing entries before creating a new one.

### 4.2 Create or update whitelist IP

```http
POST /api/v2/base/whitelist/ip/upsert
```

Required: `ip`, `ports_count`. Optional: `id` (for update), `name`, `sticky`, `ttl`, `protocol`, `quality_filter_enabled`, `country`, `region`, `city`, `isp`.

Account workflow body (template):

```json
{
  "ip": "<SERVER_IP>",
  "name": "Account Automation",
  "sticky": true,
  "ttl": 3600,
  "protocol": "HTTP",
  "quality_filter_enabled": true,
  "ports_count": 5,
  "country": "<COUNTRY_CODE>",
  "region": "<REGION_CODE>",
  "city": "<CITY_CODE>",
  "isp": "<ISP_CODE>"
}
```

All `<*_CODE>` values must come from the matching `/locations/*` endpoint. Do not hardcode them.

Concrete example (mock values for illustration only — substitute the user's real server IP and API-resolved location codes):

```json
{
  "ip": "203.0.113.42",
  "name": "Account Automation",
  "sticky": true,
  "ttl": 3600,
  "protocol": "HTTP",
  "quality_filter_enabled": true,
  "ports_count": 5,
  "country": "us",
  "region": "california",
  "city": "los-angeles",
  "isp": "spectrum"
}
```

Scraping body (template):

```json
{
  "ip": "<SERVER_IP>",
  "name": "Scraping Server",
  "sticky": false,
  "ttl": 3600,
  "protocol": "HTTP",
  "quality_filter_enabled": false,
  "ports_count": 20,
  "country": "<COUNTRY_CODE>"
}
```

Concrete example (mock values):

```json
{
  "ip": "198.51.100.17",
  "name": "Scraping Server",
  "sticky": false,
  "ttl": 3600,
  "protocol": "HTTP",
  "quality_filter_enabled": false,
  "ports_count": 20,
  "country": "us"
}
```

Field semantics:

```text
ip                       source IP allowed to use the proxy (no auth needed from this IP)
name                     human label
sticky                   true = same exit IP per port, false = rotate per request
ttl                      sticky session lifetime in seconds (3600 = 1h, 86400 = 24h)
protocol                 HTTP or SOCKS5
quality_filter_enabled   true = lower fraud-score IPs (recommended for accounts)
ports_count              number of allocated ports — match expected parallelism
country/region/city/isp  lowercase codes from /locations/* endpoints
```

Defaults to recommend:

- Account: `sticky: true`, `quality_filter_enabled: true`, `ttl: 3600` (or longer for very long sessions), country + region minimum.
- Scraping: `sticky: false`, `quality_filter_enabled: false`, country only.
- `ports_count`: 5 for accounts, 10–20 for scraping. Tune to expected concurrency.

### 4.3 Get / delete whitelist by ID

```http
GET    /api/v2/base/whitelist/ip/{id}
DELETE /api/v2/base/whitelist/ip/{id}
```

Always confirm with the user before deleting.

---

## 5. Sub-users (isolation)

Use sub-users to isolate workflows: multiple accounts, multiple clients, separate scraping jobs, team access, traffic limits per workflow, separating test from production.

Each sub-user has its own `proxy_username` / `proxy_password`.

### 5.1 List

```http
GET /api/v2/base/sub-users/?page=1&per_page=20
GET /api/v2/base/sub-users/?id=<SUB_USER_ID>
```

Always check existing sub-users before creating.

### 5.2 Create

```http
POST /api/v2/base/sub-users/
```

Template:

```json
{
  "proxy_username": "<sub_user_name>",
  "proxy_password": "<proxy_password>",
  "is_traffic_limited": true,
  "traffic_limit": <bytes>
}
```

Concrete example (mock values):

```json
{
  "proxy_username": "client_account_1",
  "proxy_password": "MOCK_PASSWORD_DO_NOT_USE_v1",
  "is_traffic_limited": true,
  "traffic_limit": 10737418240
}
```

Generate `proxy_password` with a strong random generator (e.g. `openssl rand -base64 24 | tr -d '=+/' | cut -c1-20`). Do not copy the example password above into real requests.

Validation rules:

```text
proxy_username: 9–100 chars, [a-zA-Z0-9_] only
proxy_password: 9–100 chars, [a-zA-Z0-9_] only
traffic_limit:  bytes
```

If the user provides names with `-`, spaces, or non-ASCII, sanitize them: replace with `_`, then verify length ≥ 9. Ask the user to confirm the sanitized name.

Traffic limit conversions:

```text
1 GB  = 1073741824
10 GB = 10737418240
50 GB = 53687091200
```

### 5.3 Update

```http
PUT /api/v2/base/sub-users/
```

Template:

```json
{
  "id": "<sub_user_id>",
  "proxy_username": "<sub_user_name>",
  "proxy_password": "<proxy_password>",
  "is_traffic_limited": true,
  "traffic_limit": <bytes>
}
```

Concrete example (mock values):

```json
{
  "id": "MOCK_SUB_USER_ID_DO_NOT_USE",
  "proxy_username": "client_account_1",
  "proxy_password": "MOCK_PASSWORD_DO_NOT_USE_v2",
  "is_traffic_limited": true,
  "traffic_limit": 21474836480
}
```

Or increment instead of setting:

```json
{ "id": "<sub_user_id>", "traffic_limit_increment_bytes": 10737418240 }
```

`traffic_limit_increment_bytes` is mutually exclusive with `traffic_limit`. Negative values subtract.

### 5.4 Delete / reset usage

```http
DELETE /api/v2/base/sub-users/?id=<SUB_USER_ID>
POST   /api/v2/base/sub-users/reset/usage
```

Reset body:

```json
{ "ids": ["<SUB_USER_ID_1>", "<SUB_USER_ID_2>"] }
```

The default (root) user's usage cannot be reset.

---

## 6. Statistics

All statistics endpoints require `proxy_username`. Optional: `timezone`, `start`, `end` (date format `dd-mm-yyyy`), `period` (`today` | `hours24`), `request_source` (`proxy` | `browser`).

`request_source=proxy` covers all traffic via gateway (curl, Playwright, anti-detect, etc.). Use `browser` only if NodeMaven exposes browser-side telemetry separately and the user explicitly asks for it; otherwise default to `proxy`.

### 6.1 Traffic usage

```http
GET /api/v2/base/statistics/data/?proxy_username=<USERNAME>&period=hours24&request_source=proxy
```

Returns `{ "labels": [...], "data": [...] }` where `data` is bytes per bucket.

### 6.2 Requests

```http
GET /api/v2/base/statistics/requests/?proxy_username=<USERNAME>&period=hours24&request_source=proxy
```

`data` is request count per bucket. Use to confirm traffic is actually flowing or debug zero-request cases.

### 6.3 Domains

```http
GET /api/v2/base/statistics/domains/?proxy_username=<USERNAME>&limit=20&period=hours24&request_source=proxy
```

Use to see which domains consume traffic — useful for catching unexpected destinations or traffic leaks.

---

## 7. Notifications

```http
GET    /api/v2/base/notifications/
DELETE /api/v2/base/notifications/{notification_id}
```

Check unread notifications when:

- The user reports an issue.
- Before starting a large workflow.
- Debugging unexpected account state.

Only mark as read after the user confirms or after the issue is handled.

---

# Playbooks

## Playbook A — Account management

Use when the user manages social, marketplace, freelance, marketing, or e-commerce accounts.

Ask the user (in one message):

- What platform are you working with?
- How many accounts do you manage?
- Where were the accounts created and last used?
- Are accounts new or warmed up?
- Short actions or long sessions?
- Are you using an anti-detect browser?
- Running locally or from a server?

Recommendation:

- Residential or mobile proxies (mobile for higher-trust workflows)
- Country + region minimum; city or ISP if needed
- `sticky: true`, `quality_filter_enabled: true`
- `filter=medium` by default, `filter=high` for ad/marketplace accounts
- Anti-detect browser (Multilogin or equivalent)
- Separate browser profile per account
- Sub-user per account group if multi-client

API sequence:

1. `GET /api/v2/base/users/me` — validate, get base credentials
2. `GET /api/v2/base/locations/countries/?...&connection_type=residential` — resolve country
3. `GET /api/v2/base/locations/regions/?country__code=<X>&...` — resolve region
4. (optional) `GET /api/v2/base/locations/cities/?...` — resolve city
5. (optional) `GET /api/v2/base/locations/isps/?...` — resolve ISP
6. (optional) `POST /api/v2/base/sub-users/` — isolate account groups
7. (server-based) `POST /api/v2/base/whitelist/ip/upsert` with sticky body above
8. Build proxy URL (laptop) OR use allocated whitelist port (server)
9. Plug proxy into anti-detect browser profile
10. `GET /api/v2/base/statistics/data/` and `/requests/` for monitoring

Hard rules to communicate:

- Keep account geo, proxy geo, timezone, language, and browser fingerprint consistent.
- Do not rotate across countries.
- Do not reuse one browser profile for many accounts.
- Use a unique `sid` per account; keep it constant for that account.

## Playbook B — Scraping

Use when the user collects public data at scale.

Ask the user:

- What site?
- Source country?
- Browser rendering needed?
- How many pages/requests?
- Public or logged-in?
- Local or server?
- Concurrent sessions?

Recommendation:

- Residential rotating
- `sticky: false`, `quality_filter_enabled: false` (unless target is sensitive)
- Country only unless local results are required
- Larger `ports_count` for parallelism
- Playwright / Puppeteer / Selenium / custom HTTP client

API sequence:

1. `GET /api/v2/base/users/me`
2. `GET /api/v2/base/locations/countries/?...`
3. (optional) regions/cities for local targeting
4. (server) `POST /api/v2/base/whitelist/ip/upsert` with rotating body
5. Run scraping through `gate.nodemaven.com:<port>` (vary `sid` per request, or omit)
6. Monitor with `/statistics/data/`, `/requests/`, `/domains/`

Hard rules:

- Rotate IPs for scale (vary `sid`).
- Don't pin one IP for high-scale unless required.
- Country-only targeting by default.
- Watch top domains to catch leaks.

## Playbook C — Browser automation

Classify first:

- Account automation → Playbook A
- Data extraction (no login) → Playbook B
- Scraping or high-volume actions inside a logged-in account → Playbook A + the warnings in "Edge case: scraping or high-volume actions inside an account" above. Do NOT rotate `sid` per request. Throttle and spread load across multiple accounts.
- Fixed server → whitelist
- Multi-workflow → sub-users

Then follow the matched playbook.

---

# Agent decision rules

Always:

- Validate the API key before anything else.
- Ask the user's goal before recommending proxy type.
- Resolve geo codes via API; never invent them.
- Use country + region minimum for account workflows.
- Use sticky sessions with constant `sid` for account workflows.
- Use rotating sessions (varying `sid`) for scraping — but ONLY for logged-out / public scraping. Never rotate `sid` per request inside a logged-in account.
- For high-volume automation inside an account, warn the user explicitly about behavioral ban risk and recommend throttling + load-spreading across multiple accounts.
- Use `quality_filter_enabled: true` / `filter=medium` by default for accounts; `filter=high` for trust-sensitive.
- Use sub-users for isolation across clients/accounts.
- Use whitelist for fixed-server automation.
- Explain external tooling required (anti-detect browser for accounts, automation framework for scraping).
- Build the full proxy URL for the user — do not leave placeholders like `<HOST>` in the final answer.

Never:

- Invent country / region / city / ISP / ZIP codes.
- Invent the proxy username syntax — follow the format in this skill.
- Send `Authorization: Bearer ...` or a separate `x-api-key` header.
- Assume purchase or signup happens via API.
- Use random geo for accounts.
- Rotate accounts across countries.
- Recommend one fixed IP for high-scale scraping by default.
- Claim proxies alone are enough for account workflows.
- Strip UTM parameters from tracked links.
- Echo the full API key, proxy password, or full proxy URL back to the user unnecessarily — mask or use placeholders. See "Security and credential hygiene" above.
- Hardcode API keys or proxy passwords into code artifacts — use environment variables.
- Log or persist verbatim responses from `/users/me` or `/sub-users/` — they contain `proxy_password`.
- Copy literal example values from this skill (like `<YOUR_API_KEY>`, `<proxy_password>`, `<COUNTRY_CODE>`) into real API calls — they are placeholders.

---

# Minimal response templates

## User has no account

> To get started, create a NodeMaven account: https://dashboard.nodemaven.com/accounts/signup/?utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill — then pick a plan: subscription (https://dashboard.nodemaven.com/pricing?tab=MONTHLY_PLANS&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill) or Pay As You Go (https://dashboard.nodemaven.com/pricing?tab=PAG&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill). After purchase, grab your API key here: https://dashboard.nodemaven.com/user-profile?tab=API_KEY&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill — paste it back to me and I'll set everything up.

## User has account, not logged in

> Log in: https://dashboard.nodemaven.com/accounts/login/?utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill — then copy your API key from https://dashboard.nodemaven.com/user-profile?tab=API_KEY&utm_source=ai_agent&utm_medium=agent_skill&utm_campaign=nodemaven_proxy_skill and send it here so I can validate it and configure your setup.

## User wants account management

> For account workflows you need residential or mobile proxies with stable geo. Minimum setup: country + region, sticky sessions, quality filter `medium` (or `high` for ad/marketplace accounts). Pair this with an anti-detect browser like Multilogin — platforms detect both IP and browser fingerprint. Send me your API key and target country so I can build the exact proxy URL.

## User wants scraping

> For scraping use rotating residential proxies. Default: country-only targeting, sticky off, varying `sid` per request, larger port allocation. Pair with Playwright / Puppeteer / Selenium / a custom HTTP client. Send me your API key, target country, and concurrency so I can configure it.

## User provides API key

> Validating now. I'll call `GET /api/v2/base/users/me`, then resolve location codes, set up whitelist or sub-user if needed, and give you the exact proxy URL ready to paste into your tool.

---

# Summary

```text
user task → proxy recommendation → account/API setup → location resolution → access configuration → external tool setup → monitoring
```

API for: validation, location discovery, whitelist, sub-users, monitoring.
Gateway for: scraping, browser automation, anti-detect sessions, account workflows.

For full success, combine:

```text
correct proxy type + correct geo + correct session strategy (sticky/rotating + sid) + correct external tool
```

If anything is uncertain, the agent's defaults are: residential, country+region targeting, sticky for accounts / rotating for scraping, `filter=medium`, HTTP protocol (port 8080).