XProxy REST API: IP 로테이션, 상태, 프록시 목록

XProxy REST API를 사용하면 직접 작성한 코드에서 간단한 HTTP 호출로 모바일 프록시 목록을 가져오고, IP를 로테이션하고, 상태를 읽고, 모뎀을 재부팅할 수 있습니다. box 주소로 호출하고, 필요한 곳에 대시보드 로그인만 추가하면 됩니다.

필요한 것: Basic 플랜 이상(요금제, Free 플랜에는 IP 로테이션이 없습니다)과 box 주소. 네트워크 밖에서 호출한다면 대시보드 사용자 이름과 비밀번호도 필요합니다.

한눈에 보기

기본 URL

box 주소입니다. 예: http://192.168.1.100. 별도의 API 서버는 없습니다.

API 키 없음

호출에는 대시보드 사용자 이름과 비밀번호(HTTP Basic)를 사용합니다. 로테이션과 상태 호출은 Force API Auth를 켜기 전까지 로그인이 필요 없습니다.

시작은 호출 3개로

info_list는 모뎀 목록을, rotate_ip는 새 IP를 가져오고, status는 준비가 끝났는지 알려 줍니다.

XProxy API의 기본 URL은 무엇인가요?

기본 URL은 XProxy box의 주소이며, 대시보드 포트가 80이 아니면 포트도 붙입니다.

호출 위치	기본 URL
내 로컬 네트워크	`http://192.168.1.100` (box 주소)
다른 대시보드 포트	`http://192.168.1.100:8080` (대시보드 보안 참고)
인터넷	`http://myproxy.duckdns.org`, 공인 주소 또는 VPS 주소. NAT Forwarding, VPS Forwarding, Tailscale로 box에 접속합니다.

https://는 도메인이 HTTPS를 제공할 때만 사용하세요. 링크와 API 호출용 도메인은 Proxy Settings → Address에서 따로 지정할 수 있습니다.

REST API에는 어떻게 로그인하나요?

별도의 API 키는 없습니다. 로그인이 필요한 호출에는 대시보드 사용자 이름과 비밀번호를 HTTP Basic 인증으로 사용합니다. 대시보드 보안에서 설정한 로그인과 같습니다.

호출	로그인
로테이션, 상태, 재부팅: `/api/v1/rotate_ip/…`, `/api/v1/status/…`, `/api/v1/reboot/…`, 이전 방식의 `/reset`, `/status` 링크	Force API Auth를 켜기 전까지는 필요 없습니다. 켠 뒤에는 HTTP Basic입니다.
목록과 그 밖의 모든 호출: `/api/v1/info_list`, `/api/v1/proxy_list/…`, `/proxy_list`, `/reset_all`, `/reset_by_port`, `/status_by_port`	로컬 네트워크 밖에서는 HTTP Basic입니다.
로컬 네트워크의 기기, 화이트리스트에 있는 IP, Tailscale 기기(허용한 경우)	로그인 필요 없음. Force LAN Auth와 Force API Auth를 켜면 달라집니다.
자체 토큰이 있는 고객 프록시(Business 플랜)	링크에 포함된 토큰. Selling Platform 사용 방법을 참고하세요.

로테이션 링크는 비밀번호처럼 다루세요. Force API Auth가 꺼져 있으면 box에 접속할 수 있고 링크를 아는 사람은 누구나 그 모뎀을 로테이션할 수 있습니다. box가 인터넷에 공개되어 있다면 Force API Auth를 켜세요.

API 토큰이 있나요?

패널 자체는 POST /v2/auth/login으로 로그인합니다. 응답으로 받는 토큰은 사용자 이름과 비밀번호를 Base64로 적은 것일 뿐이므로 비밀번호만큼 안전하게 보관하세요. 스크립트에서는 매 호출마다 같은 로그인을 HTTP Basic으로 보내면 됩니다.

bash

# optional: check a login (answer: status true and a token)
curl -X POST 'http://192.168.1.100/v2/auth/login' \
  --header 'Content-Type: application/json' \
  --data '{"username": "admin", "password": "YOUR_PASSWORD"}'

패널에서 API는 어디에 있나요?

사이드바에서 API Reference를 여세요. apidocs.xproxy.io의 전체 문서 링크와, 대부분의 사용자가 먼저 쓰는 호출 3개가 있습니다.

XProxy 패널의 API Reference 페이지: Open Documentation 버튼과 info_list, rotate_ip, status 빠른 시작 호출이 표시된 모습 (데모 데이터) — API Reference: ① Open Documentation · ② Quick Start 호출: `info_list`, `rotate_ip/position`, `status/position`.

어떤 엔드포인트를 호출할 수 있나요?

따로 표시하지 않은 호출은 모두 GET입니다. <position>은 모뎀 번호(1 = 첫 번째 모뎀)입니다. <proxy>는 해당 프록시의 host:port입니다.

엔드포인트	기능	로그인 필요?
`/api/v1/info_list?page=&limit=`	모뎀 목록: 포트, 공인 IP, 마지막 로테이션, 기기 정보. 응답: `data`와 `total`.	예
`/api/v1/proxy_list/<type>`	일반 텍스트, 한 줄에 프록시 하나. 유형: `proxy`, `socks5`, `proxy_ipv6`, `socks5_ipv6`, `vless`, `vless_ipv6`, `ss`.	예
`/api/v1/rotate_ip/position/<position>`	해당 모뎀의 새 IP를 가져옵니다.	아니요*
`/api/v1/rotate_ip/proxy/<proxy>`	위와 같으며 프록시로 지정합니다.	아니요*
`/api/v1/status/position/<position>` `/api/v1/status/proxy/<proxy>`	모뎀의 공인 IP와 상태.	아니요*
`/api/v1/reboot/position/<position>` `/api/v1/reboot/proxy/<proxy>`	모뎀을 재부팅합니다.	아니요*
`/reset?proxy=<proxy>`, `/status?proxy=<proxy>`	이전 방식의 로테이션과 상태 링크. 패널의 LINK 버튼으로 복사할 수 있습니다.	아니요*
`/reset_all`	모든 모뎀을 로테이션합니다.	예
`POST /reset_by_port`, 본문 `{"port": 4001}`	해당 프록시 포트의 모뎀을 로테이션합니다.	예
`/status_by_port?port=4001`	프록시 포트 기준 상태.	예

예 = 로컬 네트워크 밖에서는 대시보드 로그인 필요. 아니요* = Force API Auth를 켜기 전까지 로그인 불필요. 모든 파라미터가 포함된 전체 목록은 API 문서에 있습니다.

API로 프록시 목록을 가져오려면 어떻게 하나요?

bash

# all modems, first page of 20
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list?page=1&limit=20'

# every modem at once (leave page and limit out)
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list'

내 로컬 네트워크나 화이트리스트에 있는 IP에서 호출할 때는 -u를 생략할 수 있습니다.

응답(일부 생략):

json

{
  "data": [
    {
      "position": 1,
      "host": "192.168.1.100",
      "proxy_port": 4001,
      "socks5_port": 5001,
      "public_ip": "203.0.113.25",
      "public_ip_ipv6": null,
      "device_manufacture": "XProxy-Hilink",
      "device_rebooting": false,
      "device_resetting": false
    }
  ],
  "total": 1
}

각 항목의 다른 필드: proxy_port_v6, socks5_port_ipv6, vless_port, vless_port_v6, ss_port, ss_port_v6, last_updated_ip, device_imei, device_number, device_ip, device_extra_info.

API로 IP를 로테이션하려면 어떻게 하나요?

rotate_ip를 호출한 다음, 모뎀이 새 IP로 MODEM_READY가 될 때까지 status를 확인하세요. 같은 호출, 타이머, 로테이션 링크는 IP 변경 방법에도 있습니다.

bash

# by position (1 = first modem)
curl 'http://192.168.1.100/api/v1/rotate_ip/position/1'

# or by proxy (host:port)
curl 'http://192.168.1.100/api/v1/rotate_ip/proxy/192.168.1.100:4001'

# the box answers at once:
# {"status": true, "msg": "command_sent"}

# check on the new IP a few seconds later
curl 'http://192.168.1.100/api/v1/status/position/1'
# {"status": true, "public_ip": "203.0.113.77", "public_ip_v6": null,
#  "last_public_ip": "203.0.113.25", "msg": "MODEM_READY"}

Force API Auth가 켜져 있지 않으면 로그인이 필요 없습니다. 켜져 있다면 -u admin:YOUR_PASSWORD를 추가하세요.

도구에 넣을 프록시 목록을 일반 텍스트로 받으려면 어떻게 하나요?

bash

# plain text, one host:port per line
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/proxy'
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/socks5'

# 192.168.1.100:4001
# 192.168.1.100:4002

다른 유형: proxy_ipv6, socks5_ipv6, vless, vless_ipv6, ss. VLESS와 Shadowsocks는 공유 링크를 반환하며 Premium 플랜 이상이 필요합니다.

API가 로그인을 요구하게 하려면 어떻게 하나요?

General Settings → System Setting → Security를 열고 Force API Auth를 켠 다음 ① 저장하세요 ③. 먼저 사용자 이름과 비밀번호를 저장해 두어야 ② 호출할 때 보낼 로그인이 생깁니다.

System Setting의 Security 탭: Force API Auth 스위치, Username과 Password 입력란, Save가 표시된 모습 (데모 데이터) — Security → Password Authentication for dashboard: ① Force API Auth · ② Username과 Password · ③ Save.

응답은 무엇을 뜻하나요?

응답	의미
`{"status": true, "msg": "command_sent"}`	로테이션이 시작되었습니다. 새 IP는 몇 초 뒤에 나옵니다.
`need_upgrade`	현재 플랜에는 IP 로테이션이 없습니다. 구독 관리를 참고하세요.
`modem_resetting` 또는 `MODEM_RESETTING`	해당 모뎀에서 이미 로테이션이 진행 중입니다.
`MODEM_STOPPED`	모뎀이 중지되어 로테이션할 수 없습니다.
`slot_not_found`, `MODEM_NOT_FOUND`	해당 포트나 위치에 모뎀이 없습니다.
`invalid_format_proxy`	프록시는 `host:port` 형식이어야 합니다.
`MODEM_DISCONNECTED`	모뎀이 꺼져 있거나 분리되었습니다.
`COLLISION_IP`	로테이션 전과 같은 IP입니다(IP unchanged detect가 켜져 있을 때만).
HTTP 401, `{"message": "Unauthorized…"}`	대시보드 로그인이 필요한 호출입니다. 로그인을 추가하거나 화이트리스트에 있는 IP에서 호출하세요.
HTTP 403, Access Denied	Domain Only가 켜져 있습니다. IP 주소가 아니라 도메인 이름으로 호출하세요.

자주 묻는 질문

XProxy API 키는 어디서 받나요?

API 키는 없습니다. 대시보드 사용자 이름과 비밀번호를 HTTP Basic 로그인으로 사용하거나, 로컬 네트워크에서 로그인 없이 호출하세요. 로테이션과 상태 링크는 Force API Auth를 켠 뒤에만 로그인이 필요합니다.

코드에서 모바일 프록시 IP를 로테이션하려면 어떻게 하나요?

box에 GET /api/v1/rotate_ip/position/1을 보내세요. 바로 command_sent로 응답합니다. 그다음 msg가 MODEM_READY가 되고 public_ip가 바뀔 때까지 /api/v1/status/position/1을 호출하세요.

얼마나 자주 로테이션할 수 있나요?

같은 모뎀에서 다른 로테이션이 진행 중이면 요청이 거부됩니다(modem_resetting). Rotation Settings에서 한 포트의 두 로테이션 사이 최소 시간도 설정할 수 있습니다.

네트워크 밖에서 API를 호출할 수 있나요?

네, 밖에서 box에 접속할 수 있다면 가능합니다. 도메인이나 공인 주소를 기본 URL로 쓰고 대시보드 로그인을 추가하세요. 로테이션 링크도 로그인을 요구하도록 Force API Auth를 켜세요.

고객도 API를 사용할 수 있나요?

고객은 자기 프록시용 토큰이 담긴 별도 링크를 받으므로(Business 플랜) 내 대시보드 로그인이 필요 없습니다. Selling Platform 사용 방법을 참고하세요.

다음 단계는?

타이머로 로테이션하거나, 호출을 보호하거나, 프록시를 도구에 연결하세요.

IP 변경 →대시보드 보안 →Python Requests →Scrapy →

아직 해결되지 않았나요?기술자가 일회용 PIN으로 기기를 확인해 드립니다. Telegram으로 채팅하셔도 됩니다.

원격 지원 Telegram @xproxyio