# 1001Proxy API Reference

> Full REST API documentation for 1001Proxy — programmatic access to buy, manage, and retrieve proxy credentials.

---

## Overview

1001Proxy provides residential, datacenter IPv4, IPv6, ISP, and mobile proxies across 150+ countries. The API lets you programmatically create orders, retrieve proxy credentials, manage your balance, and generate crypto deposit addresses.

- **Base URL**: `https://api.1001proxy.io/api/v1`
- **Protocol**: HTTPS only
- **Content-Type**: `application/json` (except download endpoint which returns `text/plain`)
- **Authentication**: Bearer token via API key

---

## Authentication

All requests require an API key passed in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key from the dashboard at https://1001proxy.io/dashboard/api-keys. You can rotate your key at any time.

### Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.1001proxy.io/api/v1/account
```

```javascript
const res = await fetch('https://api.1001proxy.io/api/v1/account', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await res.json();
```

### Error responses

- `401 Unauthorized` with code `UNAUTHORIZED` — Missing or malformed Authorization header
- `401 Unauthorized` with code `INVALID_API_KEY` — API key not found
- `403 Forbidden` with code `BANNED` — Account is banned
- `403 Forbidden` with code `UNVERIFIED` — Account email not verified

---

## Response Format

All endpoints return a consistent JSON envelope.

### Success

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 42,
    "totalPages": 3
  }
}
```

The `meta` field is only present on paginated list endpoints.

### Error

```json
{
  "success": false,
  "error": {
    "message": "Human-readable error description",
    "code": "MACHINE_READABLE_CODE",
    "details": { ... }
  }
}
```

---

## Error Codes

| HTTP Status | Code                | Meaning                                       |
|-------------|---------------------|-----------------------------------------------|
| 400         | VALIDATION_ERROR    | Missing or invalid parameters                 |
| 400         | INVALID_TYPE        | Invalid proxy type or filter value            |
| 400         | INVALID_CURRENCY    | Unsupported deposit currency                  |
| 401         | UNAUTHORIZED        | Missing or malformed API key                  |
| 401         | INVALID_API_KEY     | API key not found in database                 |
| 402         | INSUFFICIENT_FUNDS  | Account balance too low (details: required, available) |
| 403         | BANNED              | Account is banned                             |
| 403         | UNVERIFIED          | Account email not verified                    |
| 404         | NOT_FOUND           | Resource does not exist or not owned by you   |
| 409         | NOT_PROVISIONED     | Order not yet provisioned upstream            |
| 429         | RATE_LIMITED        | Too many requests, see Retry-After header     |
| 500         | SERVER_ERROR        | Internal server error                         |
| 502         | UPSTREAM_ERROR      | Proxy provider returned an error              |

---

## Rate Limiting

Rate limits are enforced per API key using a token bucket algorithm.

| Scope              | Limit          |
|--------------------|----------------|
| General requests   | 60 per minute  |
| Order creation     | 10 per minute  |
| Deposit addresses  | 30 per minute  |

When rate limited, the response is:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMITED"
  }
}
```

---

## Proxy Types

The API supports these proxy types:

| Type       | Description                                      | Pricing Unit |
|------------|--------------------------------------------------|--------------|
| `resident` | Residential rotating/sticky IPs, 150+ countries  | Per GB       |
| `ipv4`     | Dedicated datacenter IPv4 static IPs             | Per IP       |
| `ipv6`     | Datacenter IPv6 proxies                          | Per IP       |
| `isp`      | ISP proxies (residential IPs on datacenter speed)| Per IP       |
| `mobile`   | 4G/5G mobile proxies                             | Per IP       |
| `mix`      | Mixed datacenter pool                            | Per IP       |
| `mix_isp`  | Mixed ISP pool                                   | Per IP       |

---

## Pagination

List endpoints support pagination via query parameters:

| Parameter  | Type   | Default | Max | Description        |
|------------|--------|---------|-----|--------------------|
| `page`     | number | 1       | —   | Page number        |
| `per_page` | number | 20      | 100 | Items per page     |

Response includes a `meta` object with `page`, `perPage`, `total`, and `totalPages`.

---

## Idempotency

The `POST /api/v1/orders` endpoint supports idempotency via the `Idempotency-Key` header. If you send the same key twice, the second request returns the cached response from the first without creating a duplicate order.

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"type":"ipv4","countryId":1,"periodId":1,"quantity":5}' \
  https://api.1001proxy.io/api/v1/orders
```

---

# Endpoints

---

## GET /api/v1/account

Retrieve your account profile and current balance.

### Request

No parameters required.

### Response

```json
{
  "success": true,
  "data": {
    "id": "cm1abc123def456",
    "email": "you@example.com",
    "name": "John Doe",
    "balance": "45.20",
    "apiKey": "********************abcd1234",
    "createdAt": "2025-01-15T08:30:00.000Z"
  }
}
```

### Response Fields

| Field     | Type   | Description                                |
|-----------|--------|--------------------------------------------|
| id        | string | User ID (CUID)                             |
| email     | string | Account email                              |
| name      | string | Display name (may be null)                 |
| balance   | string | Current balance in USD (2 decimal places)  |
| apiKey    | string | Masked API key (last 8 chars visible)      |
| createdAt | string | ISO 8601 account creation timestamp        |

---

## GET /api/v1/account/transactions

List your balance transactions (deposits, purchases, refunds, adjustments).

### Query Parameters

| Parameter | Type   | Required | Description                                                      |
|-----------|--------|----------|------------------------------------------------------------------|
| page      | number | No       | Page number (default: 1)                                         |
| per_page  | number | No       | Items per page (default: 20, max: 100)                           |
| type      | string | No       | Filter by type: `deposit`, `purchase`, `refund`, `adjustment`    |

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "cm1txn789",
      "type": "deposit",
      "amount": 50.00,
      "description": "Crypto deposit (BTC)",
      "paymentMethod": "oxapay",
      "status": "completed",
      "createdAt": "2025-03-10T12:00:00.000Z"
    },
    {
      "id": "cm1txn790",
      "type": "purchase",
      "amount": -8.75,
      "description": "Order cm1ord123 (ipv4)",
      "paymentMethod": "balance",
      "status": "completed",
      "createdAt": "2025-03-10T12:05:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 42,
    "totalPages": 3
  }
}
```

### Response Fields (per transaction)

| Field         | Type   | Description                                     |
|---------------|--------|-------------------------------------------------|
| id            | string | Transaction ID                                  |
| type          | string | `deposit`, `purchase`, `refund`, or `adjustment` |
| amount        | number | Amount (negative for debits, positive for credits) |
| description   | string | Human-readable description                      |
| paymentMethod | string | `oxapay`, `balance`, or `admin`                 |
| status        | string | `completed`, `pending`, or `failed`             |
| createdAt     | string | ISO 8601 timestamp                              |

---

## POST /api/v1/orders/calc

Calculate the price of an order without creating it. Use this to show pricing before confirming.

### Request Body

| Field             | Type   | Required | Description                                                |
|-------------------|--------|----------|------------------------------------------------------------|
| type              | string | Yes      | Proxy type: `ipv4`, `ipv6`, `mobile`, `isp`, `resident`, `mix`, `mix_isp` |
| countryId         | number | Yes*     | Country ID from reference data (*not required for `resident`) |
| periodId          | number | Yes*     | Period ID from reference data (*not required for `resident`) |
| quantity          | number | Yes*     | Number of IPs (*not required for `resident`)               |
| protocol          | string | Yes*     | `HTTPS` or `SOCKS5` (*required for `ipv6` only)           |
| mobileServiceType | string | Yes*     | `shared` or `dedicated` (*required for `mobile` only)      |
| operatorId        | number | Yes*     | Operator ID (*required for `mobile` only)                  |
| rotationId        | number | Yes*     | Rotation ID (*required for `mobile` only)                  |
| tarifId           | number | Yes*     | Tariff ID (*required for `resident` only)                  |
| coupon            | string | No       | Promo code for discount                                    |

### Example

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"ipv4","countryId":1,"periodId":1,"quantity":10}' \
  https://api.1001proxy.io/api/v1/orders/calc
```

### Response

```json
{
  "success": true,
  "data": {
    "type": "ipv4",
    "quantity": 10,
    "price": 12.50,
    "unitPrice": 1.25,
    "currency": "USD"
  }
}
```

### Response Fields

| Field     | Type        | Description                        |
|-----------|-------------|------------------------------------|
| type      | string      | Proxy type                         |
| quantity  | number      | Quantity quoted                    |
| price     | number      | Total price (with markup applied)  |
| unitPrice | number|null | Per-unit price (if applicable)     |
| currency  | string      | Currency code (always "USD")       |

---

## POST /api/v1/orders

Create a new proxy order. Funds are deducted from your account balance atomically. If the upstream provider fails after debit, you are automatically refunded.

### Request Body

Same fields as `POST /api/v1/orders/calc` (see above).

### Headers

| Header          | Required | Description                                           |
|-----------------|----------|-------------------------------------------------------|
| Idempotency-Key | No       | Unique key to prevent duplicate orders on retry       |

### Example

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"type":"ipv4","countryId":1,"periodId":1,"quantity":5}' \
  https://api.1001proxy.io/api/v1/orders
```

### Response

```json
{
  "success": true,
  "data": {
    "ok": true,
    "orderId": "cm1ord456abc",
    "charged": 6.25,
    "upstreamOrderId": "12345"
  }
}
```

### Response Fields

| Field           | Type   | Description                              |
|-----------------|--------|------------------------------------------|
| ok              | boolean| Always true on success                   |
| orderId         | string | Your order ID (use for subsequent calls) |
| charged         | number | Amount deducted from balance             |
| upstreamOrderId | string | Upstream provider order reference        |

### Error Responses

- `400 VALIDATION_ERROR` — Invalid or missing required fields
- `402 INSUFFICIENT_FUNDS` — Balance too low. `details.required` and `details.available` indicate amounts
- `502 UPSTREAM_ERROR` — Provider error. If balance was debited, it is automatically refunded (`refunded` field in response)

---

## GET /api/v1/orders

List your orders with optional filtering and pagination.

### Query Parameters

| Parameter | Type   | Required | Description                                               |
|-----------|--------|----------|-----------------------------------------------------------|
| page      | number | No       | Page number (default: 1)                                  |
| per_page  | number | No       | Items per page (default: 20, max: 100)                    |
| status    | string | No       | Filter: `active`, `expired`, `canceled`, `pending`        |
| type      | string | No       | Filter by proxy type: `ipv4`, `ipv6`, `mobile`, etc.      |

### Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.1001proxy.io/api/v1/orders?status=active&per_page=10"
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "cm1ord456abc",
      "type": "ipv4",
      "status": "active",
      "quantity": 5,
      "chargedAmount": 6.25,
      "currency": "USD",
      "countryId": 1,
      "protocol": "https",
      "expiresAt": "2025-04-10T12:00:00.000Z",
      "createdAt": "2025-03-10T12:00:00.000Z",
      "proxyCount": 5
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 10,
    "total": 3,
    "totalPages": 1
  }
}
```

### Response Fields (per order)

| Field         | Type        | Description                               |
|---------------|-------------|-------------------------------------------|
| id            | string      | Order ID                                  |
| type          | string      | Proxy type                                |
| status        | string      | `active`, `expired`, `canceled`, `pending`|
| quantity      | number      | Number of proxies/GB ordered              |
| chargedAmount | number      | Amount charged from balance               |
| currency      | string      | Currency (USD)                            |
| countryId     | number|null | Country ID                                |
| protocol      | string|null | Protocol (https, socks5)                  |
| expiresAt     | string|null | ISO 8601 expiration (null for residential)|
| createdAt     | string      | ISO 8601 creation timestamp               |
| proxyCount    | number      | Number of provisioned proxies             |

---

## GET /api/v1/orders/:id

Get detailed information about a specific order. You can only access orders you own.

### Path Parameters

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| id        | string | Yes      | Order ID    |

### Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.1001proxy.io/api/v1/orders/cm1ord456abc
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "cm1ord456abc",
    "type": "ipv4",
    "status": "active",
    "quantity": 5,
    "chargedAmount": 6.25,
    "currency": "USD",
    "countryId": 1,
    "periodId": 1,
    "protocol": "https",
    "mobileServiceType": null,
    "expiresAt": "2025-04-10T12:00:00.000Z",
    "createdAt": "2025-03-10T12:00:00.000Z",
    "updatedAt": "2025-03-10T12:00:00.000Z",
    "proxyCount": 5
  }
}
```

---

## GET /api/v1/orders/:id/proxies

Get the proxy credentials (IPs, ports, login/password) for an order. Fetches live data from the upstream provider.

### Path Parameters

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| id        | string | Yes      | Order ID    |

### Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.1001proxy.io/api/v1/orders/cm1ord456abc/proxies
```

### Response

```json
{
  "success": true,
  "data": [
    {
      "ip": "185.123.45.67",
      "portHttps": 8080,
      "portSocks5": 1080,
      "login": "user_abc123",
      "password": "pass_xyz789",
      "country": "US",
      "expiresAt": "2025-04-10"
    },
    {
      "ip": "185.123.45.68",
      "portHttps": 8080,
      "portSocks5": 1080,
      "login": "user_abc123",
      "password": "pass_xyz789",
      "country": "US",
      "expiresAt": "2025-04-10"
    }
  ]
}
```

### Response Fields (per proxy)

| Field      | Type        | Description                    |
|------------|-------------|--------------------------------|
| ip         | string|null | Proxy IP address               |
| portHttps  | number|null | HTTPS/HTTP port                |
| portSocks5 | number|null | SOCKS5 port                    |
| login      | string|null | Authentication username        |
| password   | string|null | Authentication password        |
| country    | string|null | Country code (ISO alpha-2 or alpha-3) |
| expiresAt  | string|null | Expiration date                |

### Using the proxies

```bash
# HTTPS proxy
curl -x http://user_abc123:pass_xyz789@185.123.45.67:8080 https://httpbin.org/ip

# SOCKS5 proxy
curl -x socks5://user_abc123:pass_xyz789@185.123.45.67:1080 https://httpbin.org/ip
```

---

## GET /api/v1/orders/:id/download

Download the proxy list for an order as a plain text file. Returns `text/plain` with `Content-Disposition: attachment`.

### Path Parameters

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| id        | string | Yes      | Order ID    |

### Query Parameters

| Parameter | Type   | Required | Default  | Description                                      |
|-----------|--------|----------|----------|--------------------------------------------------|
| format    | string | No       | ip:port  | `ip:port` or `user:pass@ip:port`                 |
| protocol  | string | No       | https    | `https` or `socks5` (determines which port)      |

### Example

```bash
# Download as ip:port
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.1001proxy.io/api/v1/orders/cm1ord456abc/download?protocol=https"

# Download with credentials
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.1001proxy.io/api/v1/orders/cm1ord456abc/download?format=user:pass@ip:port&protocol=socks5"
```

### Response

```
185.123.45.67:8080
185.123.45.68:8080
185.123.45.69:8080
```

Or with `format=user:pass@ip:port`:

```
user_abc123:pass_xyz789@185.123.45.67:8080
user_abc123:pass_xyz789@185.123.45.68:8080
user_abc123:pass_xyz789@185.123.45.69:8080
```

---

## POST /api/v1/orders/:id/extend

Extend (prolong) an active order's duration. Calculates the extension price, debits your balance, and applies the extension upstream. Automatically refunds if the upstream call fails.

### Path Parameters

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| id        | string | Yes      | Order ID    |

### Request Body

| Field    | Type            | Required | Description                                          |
|----------|-----------------|----------|------------------------------------------------------|
| periodId | number          | Yes      | Period ID for the extension (from reference data)    |
| proxyIds | array of string | No       | Specific proxy IDs to extend (defaults to all)       |

### Example

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"periodId": 2}' \
  https://api.1001proxy.io/api/v1/orders/cm1ord456abc/extend
```

### Response

```json
{
  "success": true,
  "data": {
    "ok": true,
    "charged": 4.50
  }
}
```

### Error Responses

- `400 VALIDATION_ERROR` — `periodId` is required or no proxies to extend
- `402 INSUFFICIENT_FUNDS` — Balance too low
- `404 NOT_FOUND` — Order not found or not owned by you
- `409 NOT_PROVISIONED` — Order not yet provisioned upstream
- `502 UPSTREAM_ERROR` — Provider error (balance auto-refunded)

---

## GET /api/v1/reference/:type

Get reference data (countries, periods, tariffs, operators, rotations) for a specific proxy type. Use this to get valid IDs for order creation. Response is cached for 5 minutes.

### Path Parameters

| Parameter | Type   | Required | Description                                                            |
|-----------|--------|----------|------------------------------------------------------------------------|
| type      | string | Yes      | Proxy type: `ipv4`, `ipv6`, `mobile`, `isp`, `resident`, `mix`, `mix_isp` |

### Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.1001proxy.io/api/v1/reference/ipv4
```

### Response

```json
{
  "success": true,
  "data": {
    "countries": [
      { "id": 1, "name": "United States" },
      { "id": 2, "name": "United Kingdom" },
      { "id": 3, "name": "Germany" }
    ],
    "periods": [
      { "id": 1, "name": "1 Week", "days": 7 },
      { "id": 2, "name": "1 Month", "days": 30 },
      { "id": 3, "name": "3 Months", "days": 90 }
    ],
    "tarifs": [
      { "id": 1, "name": "Standard", "price": 1.25, "traffic": null }
    ]
  }
}
```

### Response Fields

The response shape varies by proxy type:

| Field      | Present For                 | Description                           |
|------------|-----------------------------|---------------------------------------|
| countries  | All except `resident`       | Available countries with IDs          |
| periods    | All except `resident`       | Available rental periods with IDs     |
| tarifs     | `resident` only             | Traffic packages with prices (per GB) |
| operators  | `mobile` only               | Mobile operators with IDs             |
| rotations  | `mobile` only               | IP rotation intervals with IDs        |

Prices in `tarifs` have the platform markup already applied.

### Headers

```
Cache-Control: public, max-age=300
```

---

## GET /api/v1/deposits/addresses

List all your deposit wallet addresses across all supported cryptocurrencies. Addresses that haven't been generated yet show `address: null`.

### Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.1001proxy.io/api/v1/deposits/addresses
```

### Response

```json
{
  "success": true,
  "data": [
    { "currency": "USDT_TRC20", "network": "TRC-20", "address": "TXyz...abc" },
    { "currency": "USDT_ERC20", "network": "ERC-20", "address": null },
    { "currency": "BTC", "network": "BTC", "address": "bc1q...xyz" },
    { "currency": "ETH", "network": "ERC-20", "address": null },
    { "currency": "LTC", "network": "LTC", "address": null }
  ]
}
```

---

## POST /api/v1/deposits/addresses

Generate a deposit address for a specific cryptocurrency. If an address already exists for the given currency, it returns the existing one (idempotent).

### Request Body

| Field    | Type   | Required | Description                          |
|----------|--------|----------|--------------------------------------|
| currency | string | Yes      | Currency code (see supported list)   |

### Supported Currencies

| Currency Code   | Name          | Network       |
|-----------------|---------------|---------------|
| USDT_TRC20      | USDT          | TRC-20        |
| USDT_ERC20      | USDT          | ERC-20        |
| USDT_BEP20      | USDT          | BEP-20        |
| USDT_SOL        | USDT          | Solana        |
| USDT_POLYGON    | USDT          | Polygon       |
| USDT_TON        | USDT          | TON           |
| USDC_ERC20      | USDC          | ERC-20        |
| USDC_BEP20      | USDC          | BEP-20        |
| USDC_SOL        | USDC          | Solana        |
| USDC_BASE       | USDC          | Base          |
| DAI_ERC20       | DAI           | ERC-20        |
| DAI_POLYGON     | DAI           | Polygon       |
| BTC             | Bitcoin       | BTC           |
| ETH             | Ethereum      | ERC-20        |
| ETH_BASE        | Ethereum      | Base          |
| LTC             | Litecoin      | LTC           |
| DOGE            | Dogecoin      | DOGE          |
| BCH             | Bitcoin Cash  | BCH           |
| XMR             | Monero        | XMR           |
| XRP             | XRP           | XRPL          |
| TRX             | Tron          | TRX           |
| BNB             | BNB           | BEP-20        |
| SOL             | Solana        | Solana        |
| POL             | Polygon       | Polygon       |
| TON             | Toncoin       | TON           |
| SHIB_ERC20      | Shiba Inu     | ERC-20        |

### Example

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"BTC"}' \
  https://api.1001proxy.io/api/v1/deposits/addresses
```

### Response

```json
{
  "success": true,
  "data": {
    "currency": "BTC",
    "network": "BTC",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
}
```

### How deposits work

1. Generate a deposit address for your preferred cryptocurrency
2. Send crypto to the generated address
3. Once confirmed on-chain, your balance is credited automatically
4. Check your balance via `GET /api/v1/account`
5. View deposit history via `GET /api/v1/account/transactions?type=deposit`

---

## Typical Workflow

Here's a complete workflow from deposit to using proxies:

### 1. Fund your account

```bash
# Generate a BTC deposit address
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"BTC"}' \
  https://api.1001proxy.io/api/v1/deposits/addresses

# Send BTC to the returned address, then check balance
curl -H "Authorization: Bearer $KEY" \
  https://api.1001proxy.io/api/v1/account
```

### 2. Browse available options

```bash
# Get available countries and periods for datacenter IPv4
curl -H "Authorization: Bearer $KEY" \
  https://api.1001proxy.io/api/v1/reference/ipv4
```

### 3. Get a price quote

```bash
# Quote 10 US datacenter IPs for 1 month
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"ipv4","countryId":1,"periodId":2,"quantity":10}' \
  https://api.1001proxy.io/api/v1/orders/calc
```

### 4. Place the order

```bash
# Create the order (deducts balance)
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-order-001" \
  -d '{"type":"ipv4","countryId":1,"periodId":2,"quantity":10}' \
  https://api.1001proxy.io/api/v1/orders
```

### 5. Retrieve proxy credentials

```bash
# Get proxy list with credentials
curl -H "Authorization: Bearer $KEY" \
  https://api.1001proxy.io/api/v1/orders/ORDER_ID/proxies

# Or download as text file
curl -H "Authorization: Bearer $KEY" \
  "https://api.1001proxy.io/api/v1/orders/ORDER_ID/download?format=user:pass@ip:port"
```

### 6. Use the proxies

```bash
# Test a proxy
curl -x http://USER:PASS@IP:PORT https://httpbin.org/ip
```

### 7. Extend when needed

```bash
# Extend for another period
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"periodId":2}' \
  https://api.1001proxy.io/api/v1/orders/ORDER_ID/extend
```

---

## Order Creation Parameters by Proxy Type

### Datacenter IPv4 (`ipv4`)

```json
{
  "type": "ipv4",
  "countryId": 1,
  "periodId": 1,
  "quantity": 10
}
```

Required: `countryId`, `periodId`, `quantity` (min 1)

### Datacenter IPv6 (`ipv6`)

```json
{
  "type": "ipv6",
  "countryId": 1,
  "periodId": 1,
  "quantity": 10,
  "protocol": "HTTPS"
}
```

Required: `countryId`, `periodId`, `quantity`, `protocol` (`HTTPS` or `SOCKS5`)

### ISP (`isp`)

```json
{
  "type": "isp",
  "countryId": 1,
  "periodId": 1,
  "quantity": 5
}
```

Required: `countryId`, `periodId`, `quantity`

### Mobile (`mobile`)

```json
{
  "type": "mobile",
  "countryId": 1,
  "periodId": 1,
  "quantity": 1,
  "mobileServiceType": "dedicated",
  "operatorId": 1,
  "rotationId": 1
}
```

Required: `countryId`, `periodId`, `quantity`, `mobileServiceType`, `operatorId`, `rotationId`

### Residential (`resident`)

```json
{
  "type": "resident",
  "tarifId": 1
}
```

Required: `tarifId` (from reference data — represents a traffic package in GB)

### Mix (`mix`, `mix_isp`)

```json
{
  "type": "mix",
  "countryId": 1,
  "periodId": 1,
  "quantity": 10
}
```

Required: `countryId`, `periodId`, `quantity`