📘 OwllProxy API Reference

Live API Origin: ·
High-performance REST API with SOCKS5 & HTTP/HTTPS proxy gateways. Full client-side offline demo mode supported.

GET /api/health
Response: { "ok": true, "mode": "server", "name": "OwllProxy" }

🔑 Authentication & Provisioning

Bearer Token or Session cookie np_token. This site is owner-only — signup and instant demo accounts are closed, and only the admin account can sign in.

POST/api/auth/signup      { "email", "password" }   → 403 (signup closed — owner-only site)
POST/api/auth/instant     { }                       → 403 (closed — owner-only site)
POST/api/auth/login       { "email", "password" }   → Owner / admin login only
POST/api/auth/logout
GET /api/me               → Current user object & remaining balance

⚡ Proxy Line Extractor API

Rate: 10MB per line (0.01 GB). Supports country, state, city filtering, rotation, and protocol selection.

POST/api/extract
Payload:
{
  "country": "US",
  "state": "California",
  "city": "Los Angeles",
  "protocol": "socks5",
  "rotation": "10min",
  "format": "hpu",
  "qty": 5
}

Response (200 OK):
{
  "lines": [
    "104.16.240.54:7777:np_user_session_abc123:pass456"
  ],
  "cost": 0.05,
  "trafficGB": 0.05,
  "balanceMB": 50
}

🔀 API Forwarding (key-authenticated & metered)

Every member is issued one forwarding key automatically at sign-up (visible in Dashboard → API & Forwarding). The site also carries its own master forwarding key, so a request can be relayed on behalf of a named member. In both cases the transfer is measured byte-by-byte and charged against that member's ceiling — the key never grants extra traffic.

POST/api/forward        Relay one request. Body: { "key", "url", "method", "headers", "body", "member" }
GET /api/plan          Your ceiling, used MB, remaining MB + key list
GET /api/keys          My API keys (label, quota, metered bytes, request count)
POST/api/keys/rotate    Replace my key — the previous one stops working instantly
GET /api/usage          Metered request log (last 100 calls)

curl -X POST https://owlproxy.pro/api/forward \
  -H "Content-Type: application/json" \
  -d '{
    "key":    "npk_…your-key-from-the-board…",
    "member": "alice@example.com",
    "url":    "https://api.ipify.org?format=json",
    "method": "GET"
  }'

# → { "mode": "browser-relay", "upstream_status": 200, "bytes": 26,
#     "quota": { "limitMB": 100, "usedMB": 0.002, "leftMB": 99.998 },
#     "preview": "{\"ip\": \"...\"}" }

# Member key instead (no "member" field needed):
curl -X POST https://owlproxy.pro/api/forward \
  -H "Content-Type: application/json" \
  -d '{ "key": "npk_…your-member-key…", "url": "https://example.com/target" }'

import requests

SITE = "https://owlproxy.pro"
r = requests.post(f"{SITE}/api/forward", json={
    "key":  "npk_…your-key-from-the-board…",
    "member": "alice@example.com",
    "url":  "https://api.ipify.org?format=json",
})

if r.status_code == 402 and r.json().get("code") == "quota_exhausted":
    raise SystemExit("Member hit the 100 MB ceiling — stop, do not retry.")
print(r.json()["bytes"], "bytes metered ·", r.json()["quota"]["leftMB"], "MB left")

⛔ The 100 MB Hard Cap (new members)

A member who joins today gets exactly 100 MB of total transfer — that number is a wall, not a warning. It is charged by every metered action and enforced before any traffic leaves the gateway.

What the member does	Metered as	When it is refused
Extract proxy lines	10 MB per line	11th line without a top-up (403 HARD LIMIT)
Forward an API call	request + response bytes, 1 KB minimum	any call after the ceiling (402 quota_exhausted)
A mid-flight download that would overshoot	cut off at the last allowed byte	truncated: true
Buy extra traffic	—	blocked on free plans (403 BLOCKED) until the owner upgrades

Owner-only escape hatch (Admin Panel → Users → "Set cap" / "Lift 100MB"):

POST /api/admin/set-quota   { "userId": "u_xxx", "limitMB": 5000 }   → widen the ceiling
POST /api/admin/set-quota   { "userId": "u_xxx", "lift": true }      → remove it (paid / staff accounts)
GET  /api/plan             → { "quota": { "limitMB": 5000, "usedMB": 100, "leftMB": 4900 } }

⚠ Enforcement lives in the code that answers /api/*. Serve the dashboard from a static host and the ceiling is metered in the browser (demo mode) — convenient, but a member with devtools can edit their own localStorage. Run node server.js (same rule engine, one shared JSON DB, HttpOnly session cookie) and the limit becomes impossible to talk past.

🌐 What a line looks like, and where each part goes

Host / server:  the host on YOUR line, e.g. rp.evomi.com
Port:           1002 for SOCKS5, 1000 for HTTP — exactly as printed on the line
Username:       the whole user string on the line, e.g. pnparves116
Password:       the whole password, _country-…_session-…_lifetime-… included
IP change URL:  none needed — a new extraction is a new IP, and a used line expires by itself

Use 📱 App setup on any result row to copy those four values one at a time. In your app the type must be SOCKS5 (or HTTP, if you asked for HTTP) and authentication must be username + password — leaving it on None is the single most common reason a perfectly good line looks broken. Only the host belongs in the Server box; the whole host:port:user:pass string belongs only in tools that accept a full line.

Every part above comes from the line you extracted — there is no shared host:port to look up, and none is written into this page. The board prints a live/unreachable stamp for the endpoint, and no line is issued while nothing can be reached.

📍 Which address do I use? (and why a line can look dead)

Only https://owlproxy.pro is the shop. The owlproxy.pro copy is a static demo: it has no PHP behind it, so it cannot mint a line for anyone — landing there now sends you straight back to the live shop. Two things then make a working line look broken: (1) the line was taken from the demo, or is older than its lifetime, or (2) the app is set to the wrong type or to Authentication: None. Press ⚡ Test on the server (or ⚡ Test this line) on the board: it dials the proxy from the server and prints the exit IP it came out with. That verdict is the ground truth — if it says ✓ works and your app still fails, the fix is in the app, not in the line.

🚫 “The provided credentials are invalid” — what that really means

That sentence comes from the app, and it only ever means one of four things, all of them about which box the text went into — never about the line being fake:

1. The long password was typed into the Username box. The most common one by far. Username is the short half (the characters between // and the first :), typically 10–14 characters with no underscore. Everything from _country- to _lifetime-30 belongs in Password.
2. The Password box was left empty — the same line, the opposite half missing.
3. The password got cut short or got extra text stuck on it. Copy with the button on the card; do not select by hand on a phone, and do not include the host or the port.
4. The line is older than its lifetime. A line is valid 30 minutes from the moment it was minted; the provider then stops accepting those credentials. Extract a fresh one — it costs the same 10 MB.

Under every line, 📱 app setup now has a 🔎 Paste check: paste into its three boxes exactly what your app is holding, and it names the box that is wrong and hands you the right value. It reads nothing from your device and sends nothing anywhere — it only compares text against the line above it. If the card says ✓ all three boxes match and the app still refuses, press ⚡ Test on the server: when that shows a green exit IP too, the problem is the app’s protocol (it must be SOCKS5, with authentication set to username + password, never None).

The card opens by itself the moment a line is issued — six boxes in the order your app asks for them (Protocol · Server · Port · Authentication method · Username · Password), each value in its own read-only field with its own copy button, so nothing has to be selected by hand. If your app has a scanner (the small square icon on its profile screen), press 📷 QR Code instead: it carries socks5://user:pass@host:port for that line, and the profile fills itself in. A line dies 30 minutes after it is minted, so a scan or a copy should be followed by Start right away.

🌍 Picking a country, and what the line is labelled with

The country box takes any ISO‑3166 two-letter short name — all 250 of them, not a hand-picked list: BD, DE, MG, TG, ZW. Typing the name instead works too — Bangladesh, United States, even Türkiye with its accents or a city like Dubai — because the shop resolves names to codes before asking the provider. That matters: a full name used to be chopped into letter pairs and shipped as junk, which is exactly what made a chosen location look ignored. Something that is no country at all is now named back to you instead of being quietly dropped, and every line is labelled with the country that is actually inside its credential — what the row, the app-setup card and the export show is the answer that came back, never the option that happened to be highlighted on screen. Several codes at once are allowed (DE,TG); the provider picks among them and the line tells you which one it picked.

The zone system — changing the country yourself

On your own gateway (the little program in the gateway zip) the country lives in the Username, the way every commercial gateway does it: np_a1b2c3_zone_MG_sid_71132125_time_30. The two letters after zone_ are an ISO short name, and you may edit them yourself in the app — change zone_MG to zone_JP, press Start, and the next connection leaves from Japan. No re-extract, no new line, nothing charged twice: the gateway reads those two letters, asks the shop which credential exits from that country, chains through it, and reuses that answer for the rest of the line’s life. The Password is your gateway pin — seven digits, the same shape the big shops hand out. A zone nobody routed is refused with a message that says what to configure, rather than quietly sending you out of some other country.

👑 What the three owner buttons decide

API — you paste your provider account's key and save; that is the whole setup. There is no second switch to flip: the account is live the moment the key is accepted, and the GB that account holds is what your members can be issued. When it runs dry, extraction stops and nobody is charged for a line that does not exist. The same panel holds one more field: the server name printed on every line. Put your own hostname there (an A or CNAME record pointing at the gateway members dial) and no line leaves this shop with a reseller's host in it — a name that cannot be reached is never printed, because a dead host on a line is a refund.

Free proxy — whatever number of MB you confirm in that box is exactly what a new account receives when it claims the free trial, and the same number is the wall on that account: extraction, forwarding and the API all count against it. It is deducted from your own pool. Accounts that already claimed keep the ceiling they were given; your new number applies to the ones after it.

Promo code — a code, the GB it gives, and how many people may redeem it. Only the first that many accounts can claim it, each one once: the tenth account is refused even if the code is still printed everywhere. Under the box you see the claim list itself — address, GB, timestamp, in the order they claimed — so “only the first 50” is something you can show, not something you have to trust. Members redeem the code in Referral, under their referral link; a correct code lands straight in their balance and their ceiling rises by exactly that much so the GB is actually spendable.

🔑 Every line has its own password

When a line is extracted, the gateway mints a fresh random password for that one line — 12 characters, no look-alike letters — and ties it to that line's country and expiry. Copying a line to a friend and changing two letters in the Username still fails: the password belongs to the line, not to the account. Your standing key keeps working for the API and for apps that need one credential for everything, so nothing you already run breaks; but what you hand out is a line, and a line now carries its own secret.

🔀 Which box holds the long half — and why it differs

Two layouts exist and mixing them up is the most common reason an app answers “the provided credentials are invalid” on a perfectly good line:

• Minted by the upstream provider (what this shop does by default): the Password carries the routing token — …_country-US_session-9Q8ANS08_lifetime-30 — and the Username is the short account name. This order was dialled against the provider and confirmed working; the reverse order is refused by them, so swapping the boxes is not a fix.
• Through our own gateway: the Username carries the zone (see above) and the Password is the short numeric pin — the long half is the username there.

The app-setup card knows which of the two it is showing and labels each row accordingly (“the SHORT half” / “the LONG half” / “your gateway pin”), and 🔎 Paste check compares what you typed with the line itself: a swapped pair gets a one-tap ⇄ swap the two boxes button, a truncated password says how many characters the app kept, and a whole line pasted into Server is split for you.

🔌 Where the lines come from — the owner's provider account

The shop does not invent addresses. Every line it hands out is minted at the moment of the request from the upstream account saved in Admin ▸ Upstream provider (Evomi's public API: https://api.evomi.com/public/generate), so what a member copies is current, and the same account's balance — read live, shown in that card — is what the shop meters. Product, protocol, session type, line lifetime in minutes (your provider's own ceiling is 1440) and the maximum lines per extraction are all set in that card; turning it off sends issuance back to the gateway below, and no setting here can make a fake line appear.

The key is never printed anywhere. It lives in a private secrets file outside the web folder — a place no browser can reach — and the board only ever reads back ••••last4. If that key was ever pasted into a chat, a mail or a screenshot, rotate it at my.evomi.com/settings/api and save the new one in the same card; the shop picks it up on the next request.

If the provider refuses — no balance, a dead key, a network fault — the extraction ends with 502 / 503, the reason in plain words, and charged: false: a member never loses a megabyte for a line that was never minted. If it mints fewer lines than were asked for, only the lines that exist are charged. Lines the owner pastes in Admin ▸ Imported lines are treated the same way: labelled pending until a server check proves them, and never shown as verified without one.

🚀 Running the gateway — what makes a megabyte real

A proxy line is only as real as the machine answering host:port. The shop ships that machine's program: a dependency-free Node gateway that authenticates every connection against the shop and reports the bytes it carried, so a member's 100 MB is spent on traffic that actually flowed. Until it is running, the board refuses to issue lines (and refuses to charge for them) rather than hand out an address nobody can dial.

After the first line is issued the board tests it for you: every row has a ⚡ Test this line button (and the console header a ⚡ Test every line one). The check runs on the server, never in the browser, and walks three stages — the name must resolve, the port must accept a TCP connection, and an authenticated fetch must come back through the proxy. Each row then carries the verdict and the reason (✓ works · exit IP · 214ms or ✗ tcp — connection refused). A test costs no traffic: nothing is charged for asking.

# 1. a box with a public IP (a €4 VPS is enough) — point DNS at it
     DNS: A record  pool.yourdomain.com → 203.0.113.10   (only if you run your own gateway)

# 2. install and run the shipped gateway
     scp gateway/gw-server.js user@vps:~/ && ssh user@vps
     GW_ORIGIN=https://owlproxy.pro GW_PORT=7777 GW_TOKEN=\
       <copied from Admin ▸ Gateway ▸ Rotate gateway token> node gw-server.js

# 3. keep it up (systemd)
     [Unit]
     Description=OwllProxy gateway
     After=network-online.target
     [Service]
     WorkingDirectory=/home/user
     Environment=GW_ORIGIN=https://owlproxy.pro
     Environment=GW_PORT=7777
     Environment=GW_TOKEN=put-the-real-token-here
     ExecStart=/usr/bin/node /home/user/gw-server.js
     Restart=always
     User=user
     [Install]
     WantedBy=multi-user.target

# 4. optional: sell real residential exits instead of your own IP — the per-line
#    session id is carried into the provider username, so sticky/rotating still works
     Environment=GW_UPSTREAM=gw.provider.com:2333:your-zone-login:password

What the gateway does with each connection: POST /api/gw/auth (username + password + shared token → allow / deny, and the member's remaining MB), then POST /api/gw/usage with the byte count every two seconds. A member who runs out is dropped mid-session; a wrong password never gets a tunnel; anonymous traffic is answered with 407 and nothing is relayed. Both endpoints are in api.php, so the same gateway works against the PHP host and against node server.js.

💻 Code Integration Examples

import requests

proxies = {
    'http':  'socks5://:@:1002',
    'https': 'socks5://:@:1002'
}

response = requests.get('https://api.ipify.org?format=json', proxies=proxies)
print("Connected Exit IP:", response.json()['ip'])

const axios = require('axios');
const { SocksProxyAgent } = require('socks-proxy-agent');

const agent = new SocksProxyAgent('socks5://:@:1002');
const res = await axios.get('https://api.ipify.org?format=json', { httpsAgent: agent });
console.log('Exit IP:', res.data.ip);

curl -x socks5://<user>:<pass>@<host-from-your-line>:1002 https://api.ipify.org

🛡 Role-Based Access List

🔐 Demo Test Credentials

👑 Admin / Owner	the owner panel answers to one reserved address only — the owner's own Gmail. Any other email, however it is typed in, stays a member account. No password is ever printed on this page.
👤 Demo Member	demo@owlproxy.pro / demo123
⚡ Instant Trial	1-Click instant temporary account (100MB free trial)