HiProxy API 안내: 잔액, 주문, 프록시 사용자 이름

처음 쓸 때는 어떻게 하나요?

1아이디로 가입하고 대시보드에 로그인해요.
2접속 설정 탭에서 API 키를 발급해요. 키 전체는 발급할 때 한 번만 보여 주니 바로 안전한 곳에 적어 두세요.
3키가 필요한 요청에는 Authorization 헤더에 키를 담아 보내요.
4먼저 /account를 호출해 키가 동작하는지 보고, 그다음 /orders로 주문해요.

인증은 어떻게 하나요?

내 계정과 관련된 요청(account, orders, proxy-user)에는 API 키가 있어야 해요. Authorization: Bearer hpk_... 형식으로 헤더에 넣어요. 가격, 나라 목록, 견적은 누구나 볼 수 있어서 키 없이 호출해요.

HiProxy는 키 원문이 아니라 해시 값만 저장해요. 키를 잃어버렸다면 대시보드에서 새로 발급하면 되고, 그 순간 예전 키는 막혀요. 키는 서버 쪽 코드에만 두고, 브라우저에서 도는 코드나 공개 저장소에는 넣지 마세요.

HTTP header

Authorization: Bearer hpk_your_api_key

기본 주소와 데이터 형식

기본 주소: https://hiproxy.shop/api/v1
요청과 응답 본문: application/json
금액: USD 숫자(예: 1036.60)
시각: 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://hiproxy.shop/api/v1/account \
  -H "Authorization: Bearer hpk_your_api_key"

응답

{
  "username": "hi_user01",
  "balance_usd": 1300,
  "proxy": {
    "host": "gate.hiproxy.shop",
    "http_port": 6100,
    "socks5_port": 6200,
    "username": "hpexample1",
    "password": "your_password"
  },
  "allowed_ips": [
    "203.0.113.10"
  ]
}

상품과 가격표 조회

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

상품별 주문 가능 범위, 구간별 단가, 기간 할인을 알려 줘요. 요금 페이지와 같은 가격표를 써요.

요청

curl https://hiproxy.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://hiproxy.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://hiproxy.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.78,
  "unit": "day",
  "total_usd": 263.4
}

주문 넣기

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://hiproxy.shop/api/v1/orders \
  -H "Authorization: Bearer hpk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'

응답

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

주문 목록 조회

GET/api/v1/ordersAPI 키 필요

가장 최근 주문부터 100개까지 알려 줘요.

항목	형식	설명
`status`선택	string	pending, active, refunded 중 하나예요. 비워 두면 상태와 상관없이 전부 보여 줘요.

요청

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

응답

{
  "orders": [
    {
      "id": "HP-7KQ2M-X4HTD",
      "product": "unlimited",
      "quantity": 30,
      "months": null,
      "concurrency": 1000,
      "bandwidth_mbps": 200,
      "country": null,
      "unit_price_usd": 8.78,
      "total_usd": 263.4,
      "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	주문 번호예요(예: HP-7KQ2M-X4HTD).

요청

curl https://hiproxy.shop/api/v1/orders/HP-7KQ2M-X4HTD \
  -H "Authorization: Bearer hpk_your_api_key"

응답

{
  "order": {
    "id": "HP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.78,
    "total_usd": 263.4,
    "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://hiproxy.shop/api/v1/proxy-user?product=residential&country=jp&city=tokyo&session=job42&ttl=30" \
  -H "Authorization: Bearer hpk_your_api_key"

응답

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

한 번에 따라 하는 예시

가격을 확인하고, 잔액으로 주문하고, 일본 IP로 접속하는 흐름을 코드 하나로 보여 드려요.

Python (requests)

import requests

API = "https://hiproxy.shop/api/v1"
HEAD = {"Authorization": "Bearer hpk_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://hiproxy.shop/api/v1";
const HEAD = { Authorization: "Bearer hpk_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로 넣은 주문도 대시보드에서 넣은 주문과 똑같이 처리되고 내역 탭에 나와요. 예시의 hpk_your_api_key는 내 API 키로 바꿔 주세요.

HiProxy API 사용 안내