StarProxy API 문서: 잔액 조회, 주문, 프록시 사용자 이름 생성

어디서부터 시작하나요?

1아이디로 가입한 뒤 대시보드에 로그인해요.
2접속 설정 탭에서 API 키를 만들어요. 전체 키는 만들 때 한 번만 표시되니 바로 안전한 곳에 저장해 두세요.
3키가 필요한 요청마다 Authorization 헤더에 키를 실어 보내요.
4/account를 먼저 불러 키가 통하는지 확인하고, 그다음 /orders로 주문해요.

인증 방식

내 계정에 관한 요청(account, orders, proxy-user)은 API 키가 있어야 해요. 헤더에 Authorization: Bearer spk_... 형식으로 넣어요. 가격, 나라 목록, 견적은 공개 정보라 키 없이 불러요.

StarProxy에는 키 원문이 남지 않고 해시 값만 저장돼요. 키를 잃어버렸으면 대시보드에서 새로 만들면 되고, 그 즉시 이전 키는 막혀요. 키는 서버 코드에만 두세요. 브라우저에서 실행되는 코드나 공개 저장소에 올리면 안 돼요.

HTTP header

Authorization: Bearer spk_your_api_key

기본 주소와 데이터 형식

기본 주소: https://starproxy.shop/api/v1
요청, 응답 본문: application/json
금액: USD 숫자(예: 1047.70)
시각: ISO 8601 (UTC)

호출 한도가 있나요?

API 키 하나로 1분에 최대 60번 호출할 수 있어요. 키 없는 공개 주소는 IP 하나당 1분에 60번이에요. 한도를 넘기면 HTTP 429가 오니, 1분 뒤에 다시 보내 주세요.

오류는 어떤 형태로 오나요?

HTTP 상태 코드와 함께, 짧은 오류 코드와 설명이 든 JSON 본문이 와요.

예시

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this order. Top up in the dashboard."
  }
}

HTTP	code	뜻
400	bad_requestHTTP 400필수 값이 없거나, 이 상품에 쓸 수 없는 값을 보냈어요.	필수 값이 없거나, 이 상품에 쓸 수 없는 값을 보냈어요.
401	unauthorizedHTTP 401API 키가 없거나 맞지 않아요.	API 키가 없거나 맞지 않아요.
402	insufficient_balanceHTTP 402잔액이 주문 금액보다 모자라요. 잔액은 빠지지 않았어요.	잔액이 주문 금액보다 모자라요. 잔액은 빠지지 않았어요.
404	not_foundHTTP 404내 계정에 이 번호의 주문이 없어요.	내 계정에 이 번호의 주문이 없어요.
429	rate_limitedHTTP 4291분 호출 한도를 넘었어요.	1분 호출 한도를 넘었어요.
500	server_errorHTTP 500서버가 요청을 처리하지 못했어요. 잔액은 빠지지 않았어요.	서버가 요청을 처리하지 못했어요. 잔액은 빠지지 않았어요.

엔드포인트

계정 조회

GET/api/v1/accountAPI 키 필요

잔액, 프록시 호스트와 포트, 프록시 사용자 이름과 비밀번호, 허용 IP 목록을 돌려줘요.

요청

curl https://starproxy.shop/api/v1/account \
  -H "Authorization: Bearer spk_your_api_key"

응답

{
  "username": "star_user01",
  "balance_usd": 1300,
  "proxy": {
    "host": "gate.starproxy.shop",
    "http_port": 6100,
    "socks5_port": 6200,
    "username": "spexample1",
    "password": "your_password"
  },
  "allowed_ips": [
    "203.0.113.10"
  ]
}

상품, 가격 조회

GET/api/v1/products키 없이 호출

상품마다 주문할 수 있는 범위, 수량 구간별 단가, 기간 할인을 돌려줘요. 요금 페이지와 같은 가격표 기준이에요.

요청

curl https://starproxy.shop/api/v1/products

응답

{
  "currency": "USD",
  "prices_as_of": "2026-10-31",
  "products": [
    {
      "id": "unlimited",
      "unit": "day",
      "quantity": {
        "meaning": "days",
        "min": 1,
        "max": 365
      },
      "...": "..."
    },
    {
      "id": "residential",
      "unit": "gb",
      "...": "..."
    }
  ]
}

나라, 도시 목록

GET/api/v1/countries키 없이 호출

상품별로 고를 수 있는 나라와, 사용자 이름 -city- 옵션에 쓸 도시 값을 돌려줘요.

항목	형식	뜻
`product`선택	string	unlimited, residential, isp, datacenter 중 하나예요. 빈 값이면 residential이에요.

요청

curl "https://starproxy.shop/api/v1/countries?product=datacenter"

응답

{
  "product": "datacenter",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "region": "americas",
      "datacenter": true,
      "cities": [
        {
          "name": "New York",
          "value": "new_york"
        },
        {
          "name": "Los Angeles",
          "value": "los_angeles"
        }
      ]
    }
  ]
}

견적 계산

POST/api/v1/quote키 없이 호출

잔액은 그대로 두고 주문 금액만 계산해요. 주문할 때와 같은 본문을 보내면 돼요.

항목	형식	뜻
`product`필수	string	unlimited, residential, isp, datacenter 중 하나예요.
`quantity`필수	integer	수량이에요. 무제한은 일수(1~365), 주거용은 GB(5~5,000), 고정 ISP는 IP 수(1~1,000), 데이터센터는 IP 수(5~5,000)예요.
`concurrency`선택	integer	무제한에만 써요. 200, 500, 1000, 2000 중 하나예요.
`bandwidth`선택	integer	무제한에만 써요. Mbps 단위로 100, 200, 500, 1000 중 하나예요.
`months`선택	integer	고정 ISP와 데이터센터에만 써요. 1, 3, 6, 12 중 하나예요.
`country`선택	string	고정 ISP와 데이터센터에만 써요. 두 글자 나라 코드(예: jp)이고, 쓸 수 있는 값은 /countries에 나와요.

요청

curl -X POST https://starproxy.shop/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'

응답

{
  "product": "unlimited",
  "quantity": 30,
  "unit_price_usd": 8.41,
  "unit": "day",
  "total_usd": 252.3
}

주문 생성

POST/api/v1/ordersAPI 키 필요

주문 금액을 잔액에서 빼고 주문을 만들어요. 처음 상태는 pending(개통 진행)이고, 준비가 끝나면 active가 돼요. 개통되지 않으면 refunded로 바뀌고 결제 금액 전부가 잔액으로 돌아와요. 잔액이 모자라면 402가 와요.

항목	형식	뜻
`product`필수	string	unlimited, residential, isp, datacenter 중 하나예요.
`quantity`필수	integer	수량이에요. 무제한은 일수(1~365), 주거용은 GB(5~5,000), 고정 ISP는 IP 수(1~1,000), 데이터센터는 IP 수(5~5,000)예요.
`concurrency`선택	integer	무제한에만 써요. 200, 500, 1000, 2000 중 하나예요.
`bandwidth`선택	integer	무제한에만 써요. Mbps 단위로 100, 200, 500, 1000 중 하나예요.
`months`선택	integer	고정 ISP와 데이터센터에만 써요. 1, 3, 6, 12 중 하나예요.
`country`선택	string	고정 ISP와 데이터센터에만 써요. 두 글자 나라 코드(예: jp)이고, 쓸 수 있는 값은 /countries에 나와요.

요청

curl -X POST https://starproxy.shop/api/v1/orders \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'

응답

{
  "order": {
    "id": "SP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.41,
    "total_usd": 252.3,
    "status": "pending",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:12:44.120Z"
  },
  "balance_usd": 1047.7
}

주문 목록

GET/api/v1/ordersAPI 키 필요

최근 주문부터 최대 100건을 돌려줘요.

항목	형식	뜻
`status`선택	string	pending, active, refunded 중 하나예요. 빈 값이면 모든 상태의 주문이 나와요.

요청

curl "https://starproxy.shop/api/v1/orders?status=pending" \
  -H "Authorization: Bearer spk_your_api_key"

응답

{
  "orders": [
    {
      "id": "SP-7KQ2M-X4HTD",
      "product": "unlimited",
      "quantity": 30,
      "months": null,
      "concurrency": 1000,
      "bandwidth_mbps": 200,
      "country": null,
      "unit_price_usd": 8.41,
      "total_usd": 252.3,
      "status": "pending",
      "created_at": "2026-10-31T09:12:44.120Z",
      "updated_at": "2026-10-31T09:12:44.120Z"
    }
  ]
}

주문 한 건 조회

GET/api/v1/orders/{id}API 키 필요

주문 번호로 해당 주문을 돌려줘요. 개통이 끝났는지 확인할 때 써요.

항목	형식	뜻
`id`필수	string	주문 번호예요(예: SP-7KQ2M-X4HTD).

요청

curl https://starproxy.shop/api/v1/orders/SP-7KQ2M-X4HTD \
  -H "Authorization: Bearer spk_your_api_key"

응답

{
  "order": {
    "id": "SP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.41,
    "total_usd": 252.3,
    "status": "active",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:40:02.511Z"
  }
}

프록시 사용자 이름 생성

GET/api/v1/proxy-userAPI 키 필요

옵션을 넣은 프록시 사용자 이름과, 바로 붙여 쓸 HTTP, SOCKS5 주소를 돌려줘요. session이 없으면 요청마다 IP가 바뀌어요.

항목	형식	뜻
`product`선택	string	unlimited, residential, isp, datacenter 중 하나예요. 빈 값이면 unlimited예요.
`country`선택	string	두 글자 나라 코드예요(예: jp).
`city`선택	string	/countries에 있는 도시 값이에요(예: tokyo). country와 같이 보내야 해요.
`session`선택	string	영문자, 숫자 1~32자예요. 같은 session을 보낸 요청은 같은 IP를 써요.
`ttl`선택	integer	세션 IP 유지 시간이에요. 1~60분이고, 빈 값이면 30분이에요.

요청

curl "https://starproxy.shop/api/v1/proxy-user?product=residential&country=jp&city=tokyo&session=job42&ttl=30" \
  -H "Authorization: Bearer spk_your_api_key"

응답

{
  "username": "spexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30",
  "password": "your_password",
  "http": "http://spexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.starproxy.shop:6100",
  "socks5": "socks5h://spexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.starproxy.shop:6200"
}

전체 흐름 예시

견적 확인, 잔액 주문, 일본 IP 접속까지 스크립트 하나에 담았어요.

Python (requests)

import requests

API = "https://starproxy.shop/api/v1"
HEAD = {"Authorization": "Bearer spk_your_api_key"}

# 1) Check the price first
plan = {"product": "residential", "quantity": 100}
print(requests.post(f"{API}/quote", json=plan).json())

# 2) Order from your balance
r = requests.post(f"{API}/orders", json=plan, headers=HEAD)
order = r.json()["order"]
print(order["id"], order["status"])

# 3) Get a username for Japanese IPs
u = requests.get(f"{API}/proxy-user", headers=HEAD,
                 params={"product": "residential", "country": "jp"}).json()
proxies = {"http": u["http"], "https": u["http"]}
print(requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30).json())

Node.js 18+

const API = "https://starproxy.shop/api/v1";
const HEAD = { Authorization: "Bearer spk_your_api_key", "Content-Type": "application/json" };

// Check the balance
const acc = await fetch(`${API}/account`, { headers: HEAD }).then((r) => r.json());
console.log(acc.balance_usd);

// Order 7 days of unlimited
const res = await fetch(`${API}/orders`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ product: "unlimited", quantity: 7, concurrency: 500, bandwidth: 100 }),
});
if (res.status === 402) console.log("Top up first");
else console.log((await res.json()).order.id);

API로 넣은 주문은 대시보드 주문과 똑같이 처리되고 내역 탭에도 나와요. 예시 속 spk_your_api_key 자리에 내 API 키를 넣어 주세요.

StarProxy API