Logo

v-proxies

Get proxies

V-PROXIES / DOCS · BUILD 0.0.1

API reference.

Everything you need to integrate v-proxies — gateway auth, geo targeting, REST endpoints, webhooks, and SDKs.

Base URL: https://api.v-proxies.ioStatus

01 // QUICK START

You can start routing traffic through v-proxies in under a minute. All you need is your proxy credentials from the Credentials page.

bash
# Route any HTTP/HTTPS request through the gateway
curl -x v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

# Response
{ "origin": "82.15.67.33" }

~/01

Get credentials

Find your username and password on the credentials page.

~/02

Point your client

Set proxy host to v-proxies.com and port to 9000.

~/03

Start routing

Traffic proxies immediately. Usage updates in real time.

02 // AUTHENTICATION

All REST API requests are authenticated with a bearer token. Generate API keys from your dashboard. Proxy gateway traffic uses HTTP Basic Auth with your proxy credentials — these are separate from your API key.

bash
# REST API — pass your API key as a Bearer token
curl https://api.v-proxies.io/v1/me \
  -H "Authorization: Bearer vp_live_sk_xxxxxxxxxxxxxxxx"

API key anatomy

vp_live_sk_xxxxxxxxxxxxxxxx

vp_

Product prefix

live | test

Environment

_sk_…

Secret key payload

03 // PROXY GATEWAY

The proxy gateway speaks HTTP CONNECT and plain HTTP proxy protocols. Use it with any HTTP client that supports proxy settings.

HOST

v-proxies.com

PORT

9000

PROTOCOL

HTTP / HTTPS

Proxy list format

v-proxies.com:9000:username:password
bash
# HTTPS via CONNECT tunnel
curl -x https://v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://target.example.com/api

# Plain HTTP
curl -x http://v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  http://target.example.com/page

04 // SESSION MODES

Control whether the gateway assigns a new IP on every request (rotating) or pins the same IP for a set duration (sticky). Session mode is encoded in the proxy username — no extra headers needed.

::rotating

New IP per request

Default mode. Highest anonymity. No username suffix required.

u_a91c2f:p_xk9m2r4n8q1vw3

::sticky

Same IP for N minutes

Pin a session for 1–60 minutes. Generate a unique session token per session.

u_a91c2f-session-abc123-sticky-30:p_…
bash
# Sticky 30-minute session (generate a unique token per session)
SESSION="sess_$(openssl rand -hex 8)"

curl -x v-proxies.com:9000 \
  -U "u_a91c2f-session-${SESSION}-sticky-30:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

# Rotating (default — no suffix)
curl -x v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

05 // GEO TARGETING

Append targeting parameters to the proxy username separated by hyphens. Parameters are applied in order and can be combined freely.

Username format

country-{cc}country-us

ISO 3166-1 alpha-2 country code

city-{name}city-new_york

City slug (lowercase, underscores)

asn-{number}asn-16509

Autonomous System Number

carrier-{name}carrier-att

Mobile carrier slug (mobile pool only)

session-{id}session-abc123

Session token for sticky mode

sticky-{minutes}sticky-30

Pin duration 1–60 min (requires session-)

bash
# Country only
-U "u_a91c2f-country-us:p_xk9m2r4n8q1vw3"

# Country + city
-U "u_a91c2f-country-us-city-new_york:p_xk9m2r4n8q1vw3"

# ASN targeting (AWS us-east-1)
-U "u_a91c2f-asn-16509:p_xk9m2r4n8q1vw3"

# Country + city + sticky 15 min
-U "u_a91c2f-country-gb-city-london-session-xyz-sticky-15:p_xk9m2r4n8q1vw3"

06 // POOLS

Select a pool when creating a credential or pass it as a header on existing credentials.

Residential

$2.40 /GB

  • 120+ countries
  • City + ASN targeting
  • 1–60 min sticky
  • Highest success rate

Mobile

$8.00 /GB

  • 4G/LTE IPs
  • Carrier targeting
  • Real mobile ASNs
  • Lowest detection rate

Datacenter

$0.40 /GB

  • 20+ countries
  • Highest throughput
  • Unlimited concurrency
  • Best for bulk scraping
bash
# Override pool per-request with the X-VP-Pool header
curl -x v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  -H "X-VP-Pool: mobile" \
  https://httpbin.org/ip

07 // REST API

All endpoints are under https://api.v-proxies.io. Responses are JSON. Rate limit: 300 requests / minute per API key.

GET/v1/me

Account info — email, plan, created_at

GET/v1/balance

Current balance in USD and GB remaining

GET/v1/credentials

List all proxy credentials

POST/v1/credentials

Create a new credential set

DELETE/v1/credentials/:id

Revoke a credential

GET/v1/usage

Bandwidth usage (range=7d|30d|90d)

GET/v1/requests

Proxy request log (limit, status, page)

POST/v1/topup

Create Stripe checkout session → { url }

GET/v1/webhooks

List registered webhook endpoints

POST/v1/webhooks

Register a new webhook

DELETE/v1/webhooks/:id

Remove a webhook

Example — GET /v1/me

bash
curl https://api.v-proxies.io/v1/me \
  -H "Authorization: Bearer vp_live_sk_xxxxxxxxxxxxxxxx"

# 200 OK
{
  "id": "usr_a91c2f",
  "email": "ops@example.com",
  "plan": "residential",
  "balance_usd": 184.20,
  "gb_remaining": 76.7,
  "created_at": "2024-09-01T00:00:00Z"
}

Example — POST /v1/credentials

Body parameters

poolrequired
string

residential | mobile | datacenter

label
string

Human-readable label for this credential set.

allowlist
string[]

IP CIDR ranges allowed to use this credential.

bash
curl -X POST https://api.v-proxies.io/v1/credentials \
  -H "Authorization: Bearer vp_live_sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "pool": "residential", "label": "scraper-01" }'

# 201 Created
{
  "id": "crd_7f3a1b",
  "host": "v-proxies.com",
  "port": 9000,
  "username": "u_7f3a1b",
  "password": "p_hj8mq5rn2wk4vx",
  "pool": "residential",
  "label": "scraper-01"
}

08 // WEBHOOKS

Subscribe to account events and receive a POST request to your endpoint whenever an event fires. Payloads are signed with HMAC-SHA256.

Event types

balance.low

Balance drops below the configured threshold.

balance.depleted

Balance reaches $0 — traffic will stop.

topup.completed

A top-up payment is confirmed.

credential.created

A new credential set is provisioned.

credential.revoked

A credential is deleted.

request.blocked

A proxy request is blocked (403/407).

json
// POST to your endpoint
{
  "id": "evt_01j1xmkqz2",
  "event": "balance.low",
  "created_at": "2024-10-13T14:22:00Z",
  "data": {
    "balance_usd": 9.40,
    "threshold_usd": 10.00
  }
}

// Signature header
X-VP-Signature: sha256=3d4f9a1c…
bash
# Register a webhook
curl -X POST https://api.v-proxies.io/v1/webhooks \
  -H "Authorization: Bearer vp_live_sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example.com/webhook",
    "events": ["balance.low", "balance.depleted", "topup.completed"]
  }'

09 // ERROR CODES

All error responses include a JSON body with a code and a human-readable message.

400Bad request

Invalid or missing parameters in the request body.

401Unauthorized

API key missing, malformed, or revoked.

403Forbidden

Source IP not in allowlist, or insufficient balance.

407Proxy auth required

Proxy credentials rejected at the gateway.

429Too many requests

Management API rate limit hit — back off and retry.

500Server error

Unexpected error on our end. Check status.v-proxies.com.

502Bad gateway

Upstream target unreachable. Verify the target URL.

503Unavailable

Gateway under maintenance. Check status page.

json
// Error response shape
{
  "error": {
    "code": "insufficient_balance",
    "message": "Account balance is $0.00. Top up to resume traffic.",
    "status": 403
  }
}

10 // SDKS

Use any HTTP client that supports proxy authentication. Below are copy-paste examples for the most common environments.

bash
curl -x v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

::ready

Start routing traffic

Top-up from $10. Credentials provisioned in under 2 seconds.

Top upGet credentials