API 및 연동 문서
SocksNode를 연동하는 두 가지 방법: HTTP(S) 또는 SOCKS5로 프록시 게이트웨이에 직접 연결하거나, REST API를 통해 대역폭, 사용량, 프록시를 프로그래밍 방식으로 관리하세요.
이 페이지에서
모바일 프록시
4G/5G REST API
4G/5G 모바일 프록시를 API로 구매하고 관리하세요. 각 Mobile IP는 선택한 기간 동안 로테이션되는 통신사 IP(최대 3개 연결)입니다. 대여와 갱신은 선불 계정 잔액(USD)에서 차감됩니다. read:proxies / write:proxies 범위를 사용합니다.
https://socksnode.com/api/v1인증
기본 URL https://socksnode.com/api/v1. Dashboard → API access에서 키를 생성하고 Bearer 토큰으로 전송하세요. 키는 범위가 지정되어 있으므로 필요한 것만 요청하세요.
| 범위 | 권한 |
|---|---|
| read:usage | 잔액 및 사용량 분석 |
| read:proxies | 저장된 프록시 자격 증명 목록 |
| write:proxies | 새 프록시 자격 증명 생성 |
| purchase | 로테이팅 주거용·데이터센터·모바일 프록시용 GB 구매, 고정 IP와 ISP IP 구매 및 연장, 4G/5G 포트 대여 및 연장, 자동 연장 설정, 24시간 IP와 IP Vault 주소 및 대역폭 구매 — 잔액에서 결제됩니다. |
속도 제한: 키당 분당 120개 요청 (프록시 생성은 추가로 제한됩니다). 키는 비밀로 유지하고 서버 측에 보관하세요.
GET /api/v1/account HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_YOUR_API_KEY오류
오류는 해당 HTTP 상태와 함께 JSON 본문 { "error": { "code", "message" } }을 반환합니다:
| 상태 | 의미 |
|---|---|
| 400 | 잘못된 요청 본문 또는 매개변수 |
| 401 | 누락되거나 잘못되었거나 취소된 API 키 |
| 402 | 프록시를 생성하기에 대역폭 잔액이 부족함 |
| 403 | API 키에 필요한 범위가 없음 |
| 404 | 찾을 수 없거나 본인 소유가 아닙니다. |
| 409 | 포트 상태상 지금은 불가합니다(예: 만료됨). |
| 429 | 속도 제한 초과 — Retry-After 헤더 참조 |
| 502 | 업스트림 네트워크 오류. 요금이 청구되지 않았습니다. |
| 503 | 제품 점검 중입니다. 잠시 후 다시 시도하세요. |
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": {
"code": "no_bandwidth",
"message": "…"
}
}API 엔드포인트
기간, 국가, 주 및 통신사
GET/mobile/catalog
범위: read:proxies
쿼리 파라미터
countryinteger선택 사항국가 id. 해당 주 목록을 반환합니다.
stateinteger선택 사항주 id. 해당 통신사 목록을 반환합니다.
availabilitystring선택 사항1로 설정하면 각 옵션의 현재 여유량을 함께 반환합니다.
1tierstring선택 사항재고를 확인할 요금제.
economybasicturbo기본값:basicmodemsstring선택 사항state와 함께 1로 설정하면 해당 주의 모든 모뎀(여유·사용 중)과 각 모뎀의 IP 유지 시간을 반환합니다. 필드는 /mobile/proxies/PROXY_ID/modems와 같습니다.
1carrierinteger선택 사항통신사 id. modems=1과 함께 쓰면 그 통신사의 모뎀만 반환합니다.
curl "https://socksnode.com/api/v1/mobile/catalog?state=12&availability=1" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": {
"carriers": [
{ "id": 34, "name": "5G AT&T", "status": "ok", "pct": 82 },
{ "id": 35, "name": "5G T-Mobile", "status": "low", "pct": 11 },
{ "id": 36, "name": "5G Verizon", "status": "none", "pct": 0 }
]
}
}
// status: "ok" | "low" | "none" | "unknown"
// Country and state stock is refreshed every ~15 min;
// carrier stock is checked live, right before you choose.모바일 프록시 목록(자격 증명 포함)
GET/mobile/proxies
범위: read:proxies
파라미터 없음.
curl "https://socksnode.com/api/v1/mobile/proxies" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": [
{
"id": "clx…",
"name": "Port 1",
"host": "mobile.socksnode.com",
"port": 9094,
"protocol": "socks5",
"username": "sn_a1b2c3d4",
"password": "…",
"authMode": "userpass",
"allowedIps": [],
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"rotationMinutes": 15,
"modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
"status": "active",
"paused": false,
"bytesUsed": 0,
"lastExitIp": null,
"expiresAt": "2026-10-30T04:46:53.000Z"
}
]
}프록시 1개
GET/mobile/proxies/{id}
사용 데이터 + 마지막 출구 IP 포함
범위: read:proxies
경로 파라미터
idstring필수모바일 프록시 id.
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": {
"id": "clx…",
"name": "Port 1",
"host": "mobile.socksnode.com",
"port": 9094,
"protocol": "socks5",
"username": "sn_a1b2c3d4",
"password": "…",
"authMode": "userpass",
"allowedIps": [],
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"rotationMinutes": 15,
"modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
"status": "active",
"paused": false,
"bytesUsed": 0,
"lastExitIp": null,
"expiresAt": "2026-10-30T04:46:53.000Z"
}
}N개 포트 구매(잔액에서 차감; 부족 시 402)
POST/mobile/proxies
범위: purchase
본문 파라미터
tierKeystring선택 사항대여할 요금제.
economybasicturbo기본값:basicdurationKeystring필수대여 기간. 해당 요금제가 판매하는 기간이어야 합니다.
2h12h1d3d7d15d30dquantityinteger선택 사항대여할 포트 수, 1–50. 생성되지 않은 포트는 청구되지 않습니다.
기본값:
1countryIdinteger선택 사항카탈로그의 국가 id. 생략하면 사용 가능한 아무 위치.
cityIdinteger선택 사항카탈로그의 주 id.
spIdinteger선택 사항카탈로그의 통신사 id.
modemIdstring선택 사항/mobile/catalog?modems=1의 모뎀 id(같은 플랜). cityId와 quantity 1이 필요합니다. 빈 자리가 없으면 409 modem_taken이며 요금은 청구되지 않습니다.
protocolstring선택 사항포트의 프로토콜.
sockshttp기본값:socks
curl -X POST "https://socksnode.com/api/v1/mobile/proxies" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"durationKey": "30d",
"quantity": 1,
"countryId": 1,
"cityId": 12,
"spId": 34,
"protocol": "socks"
}'{
"data": [
{
"id": "clx…",
"name": "Port 1",
"host": "mobile.socksnode.com",
"port": 9094,
"protocol": "socks5",
"username": "sn_a1b2c3d4",
"password": "…",
"authMode": "userpass",
"allowedIps": [],
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"rotationMinutes": 15,
"modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
"status": "active",
"paused": false,
"bytesUsed": 0,
"lastExitIp": null,
"expiresAt": "2026-10-30T04:46:53.000Z"
}
],
"charged": 40
}국가/주/통신사 변경(무료)
POST/mobile/proxies/{id}/switch
범위: write:proxies
경로 파라미터
idstring필수모바일 프록시 id.
본문 파라미터
countryIdinteger필수카탈로그의 국가 id.
cityIdinteger선택 사항카탈로그의 주 id.
spIdinteger선택 사항카탈로그의 통신사 id.
modemIdstring선택 사항모뎀 목록의 모뎀 id. cityId가 필요합니다. 포트는 그 모뎀으로만 이동합니다. 가득 차면 409 modem_taken, 목록에서 빠졌으면 404 modem_gone.
protocolstring선택 사항기본값은 포트의 현재 프로토콜.
sockshttp
curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/switch" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"countryId": 3,
"cityId": 12,
"spId": 34,
"modemId": "8d21e7c40b9a6f5e3c12"
}'{
"data": {
"id": "clx…",
"host": "mobile.socksnode.com",
"port": 9095,
"protocol": "socks5",
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"status": "active"
}
}
// + every other field of GET /mobile/proxies/{id}포트용 주별 모뎀 목록
GET/mobile/proxies/{id}/modems
범위: read:proxies
경로 파라미터
idstring필수모바일 프록시 id.
쿼리 파라미터
stateinteger필수카탈로그의 주 id. 이 포트의 플랜 기준으로 그 주의 모뎀을 반환합니다.
carrierinteger선택 사항통신사 id. modems=1과 함께 쓰면 그 통신사의 모뎀만 반환합니다.
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/modems?state=12&carrier=34" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": {
"modems": [
{
"id": "3f9c0a1b2d4e5f607182",
"code": "K7QM",
"carrier": "5G AT&T",
"free": true,
"current": true,
"yours": 0,
"yourPorts": [],
"rotationMinutes": 30,
"lastIp": "174.208.161.27",
"lastOkAt": "2026-10-28T03:12:40.000Z",
"failing": false
},
{
"id": "8d21e7c40b9a6f5e3c12",
"code": "R4XB",
"carrier": "5G AT&T",
"free": false,
"current": false,
"yours": 0,
"yourPorts": [],
"rotationMinutes": 60,
"lastIp": null,
"lastOkAt": null,
"failing": false
}
],
"free": 1,
"total": 2
}
}
// free: has a slot for one more port. current: this port is on it.
// yours: your other live ports on it (they share its IP); yourPorts: their port numbers.
// rotationMinutes: how long the modem keeps one IP.새 출구 IP(무료)
POST/mobile/proxies/{id}/rotate
범위: write:proxies
경로 파라미터
idstring필수모바일 프록시 id.
curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": {
"id": "clx…",
"host": "mobile.socksnode.com",
"port": 9095,
"protocol": "socks5",
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"status": "active"
}
}
// + every other field of GET /mobile/proxies/{id}API 키 불필요
GET/mobile/proxies/{id}/rotate?token=…
대시보드에서 복사한 링크 하나면 충분합니다. 브라우저, curl, 크론 작업, 북마크 등으로 열면 IP가 로테이션되며, 위치 파라미터를 추가하면 국가/주/통신사 전환도 가능합니다.
쿼리 파라미터
tokenstring필수포트의 로테이션 토큰, 대시보드의 포트 카드에서 확인. API 키 불필요.
countryIdinteger선택 사항선택. IP만 바꾸는 대신 이 위치로 전환합니다.
cityIdinteger선택 사항카탈로그의 주 id.
spIdinteger선택 사항카탈로그의 통신사 id.
formatstring선택 사항응답 형식.
jsonhtml기본값:json
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate?token=YOUR_ROTATE_TOKEN"{
"ok": true,
"data": {
"id": "clx…",
"host": "mobile.socksnode.com",
"port": 9095,
"protocol": "socks5",
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"status": "active"
}
}
// + every other field of GET /mobile/proxies/{id}실시간 출구 IP 조회
GET/mobile/proxies/{id}/check-ip
범위: read:proxies
경로 파라미터
idstring필수모바일 프록시 id.
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/check-ip" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": { "ip": "174.208.161.27" }
}SOCKS5 ↔ HTTP(S) 전환
POST/mobile/proxies/{id}/protocol
범위: write:proxies
경로 파라미터
idstring필수모바일 프록시 id.
본문 파라미터
protocolstring필수포트의 프로토콜.
sockshttp
curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/protocol" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"protocol": "http"
}'{
"data": {
"id": "clx…",
"host": "mobile.socksnode.com",
"port": 9095,
"protocol": "socks5",
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"status": "active"
}
}
// + every other field of GET /mobile/proxies/{id}인증 방식 변경
POST/mobile/proxies/{id}/auth
범위: write:proxies
경로 파라미터
idstring필수모바일 프록시 id.
본문 파라미터
modestring필수userpass는 사용자명과 비밀번호로 인증, whitelist는 목록의 IP가 비밀번호 없이 연결.
userpasswhitelistallowedIpsstring[]선택 사항공인 IPv4 또는 IPv6 주소 최대 3개, 대역 불가. whitelist에 필요.
기본값:
[]
curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/auth" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "whitelist",
"allowedIps": [
"203.0.113.7"
]
}'{
"data": {
"id": "clx…",
"host": "mobile.socksnode.com",
"port": 9095,
"protocol": "socks5",
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"status": "active"
}
}
// + every other field of GET /mobile/proxies/{id}포트 연장(잔액에서 차감)
POST/mobile/proxies/{id}/renew
범위: purchase
경로 파라미터
idstring필수모바일 프록시 id.
본문 파라미터
durationKeystring필수대여 기간. 포트의 요금제가 판매하는 기간이어야 합니다.
2h12h1d3d7d15d30d
curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/renew" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"durationKey": "30d"
}'{
"data": {
"id": "clx…",
"host": "mobile.socksnode.com",
"port": 9095,
"protocol": "socks5",
"country": "UNITED STATES",
"state": "FLORIDA",
"carrier": "5G AT&T",
"status": "active"
},
"charged": 40
}
// + every other field of GET /mobile/proxies/{id}