> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.lumiweb.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# API — Proxy

> Proxy bot REST API: catalog, quote, subscriptions, credentials, buy static, renew

Base URL: `https://panel.scamprojecttest.xyz/proxy/api/v1`. Shared rules (auth, limits, errors, idempotency) are in the [overview](/en/api).

<Note>
  v1 covers buying **static** proxies (ISP/Datacenter), renewal, and all reads. Buying rotating (residential/mobile) proxies via the API is not exposed yet — it needs the bot's interactive geo-targeting flow.
</Note>

## Account

| Method | Path                       | Scope        | Description                           |
| ------ | -------------------------- | ------------ | ------------------------------------- |
| GET    | `/users/me`                | `proxy:read` | Key & user profile                    |
| GET    | `/users/{user_id}/balance` | `proxy:read` | Balance                               |
| GET    | `/transactions`            | `proxy:read` | Transactions (paginated, `?user_id=`) |
| GET    | `/referrals`               | `proxy:read` | Referral stats                        |

## Catalog & quote

### Catalog

`GET /proxy/catalog` · scope `proxy:read`

```json theme={"system"}
{ "categories": [
  { "category":"isp","label":"ISP","unit":"IP","kind":"static","live":true,"sample_price_usd":"2.50" },
  { "category":"residential","label":"Residential","unit":"GB","kind":"rotating","live":true,"sample_price_usd":"2.00" }
] }
```

Pricing is volume-tiered (the larger the volume, the lower the per-unit price); `sample_price_usd` is the first-tier price. Get live tiers via `/proxy/quote`.

### Quote

`POST /proxy/quote` · scope `proxy:read` · body `{ "category":"isp", "quantity":5 }`

```json theme={"system"}
{ "category":"isp","quantity":5,"unit":"IP","price_usd":"12.50","available":true }
```

## Subscriptions

| Method | Path                                    | Scope        | Description                   |
| ------ | --------------------------------------- | ------------ | ----------------------------- |
| GET    | `/proxy/subscriptions`                  | `proxy:read` | List (paginated, `?user_id=`) |
| GET    | `/proxy/subscriptions/{id}`             | `proxy:read` | Subscription card             |
| GET    | `/proxy/subscriptions/{id}/credentials` | `proxy:read` | Credentials                   |

The `credentials` response depends on the type:

```json theme={"system"}
// static
{ "subscription_id": 9, "kind": "static",
  "static_proxies": [ { "ip":"1.2.3.4","port_http":8080,"port_socks":1080,"login":"u","password":"p" } ] }

// rotating
{ "subscription_id": 9, "kind": "rotating",
  "upstream_login":"u","upstream_endpoint":"gw.example:7000","upstream_password":"p" }
```

<Note>
  Credentials return with `Cache-Control: no-store` — do not cache or log them.
</Note>

## Buy & renew (money)

<Warning>
  Require `API_MONEY_ENABLED`, scope `proxy:buy`, an `Idempotency-Key` header, and (if enabled) an `X-Signature`.
</Warning>

### Buy static proxies

`POST /proxy/static` · scope `proxy:buy` · **money**

| Field          | Type          | Description                  |
| -------------- | ------------- | ---------------------------- |
| `category`     | string        | `isp` or `datacenter`        |
| `country_name` | string (1–64) | Country (name or ISO code)   |
| `quantity`     | number 1–500  | IP count                     |
| `auto_renew`   | bool          | Auto-renew (default false)   |
| `user_id`      | number        | Required for an operator key |

```bash theme={"system"}
curl -X POST "https://panel.scamprojecttest.xyz/proxy/api/v1/proxy/static" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: prx-2026-06-09-001" \
  -H "Content-Type: application/json" \
  -d '{"category":"isp","country_name":"United States","quantity":5}'
```

```json theme={"system"}
{ "status":"ok","subscription_id":9,"order_id":120,"price_usd":"12.50","quantity":5,"country":"US" }
```

`status` field: `ok` (delivered), `provisioning` (in progress), `insufficient` (`402`, low balance), `provider_misconfig` (`503`), `bad_request` (`400`).

### Renew subscription

`POST /proxy/subscriptions/{id}/renew` · scope `proxy:buy` · **money**

```json theme={"system"}
{ "subscription_id":9,"status":"ok","price_usd":"12.50","new_expires_at":"2026-07-09T..." }
```

## Management (write)

### Auto-renew

`POST /proxy/subscriptions/{id}/auto-renew` · scope `proxy:write` · body `{ "auto_renew": true }`. Returns the updated subscription card.

## Deposits (money)

`POST /deposits` · scope `deposits:write` · **money** → `201`. Body and behaviour as in [domains](/en/api/domains). Status: `GET /deposits/{provider}/{external_id}`.

## Operator endpoints

Operator only (`admin:*`): `/admin/users/{id}/balance`, `/admin/users/{id}/ban`, `/admin/deposits/{tx}/mark-completed`, `/admin/deposits/{tx}/mark-failed` — see [domains](/en/api/domains#operator-endpoints).