개발자

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프록시를 생성하기에 대역폭 잔액이 부족함
403API 키에 필요한 범위가 없음
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로 설정하면 각 옵션의 현재 여유량을 함께 반환합니다.

    1

  • tierstring선택 사항

    재고를 확인할 요금제.

    economybasicturbo기본값: basic

  • modemsstring선택 사항

    state와 함께 1로 설정하면 해당 주의 모든 모뎀(여유·사용 중)과 각 모뎀의 IP 유지 시간을 반환합니다. 필드는 /mobile/proxies/PROXY_ID/modems와 같습니다.

    1

  • carrierinteger선택 사항

    통신사 id. modems=1과 함께 쓰면 그 통신사의 모뎀만 반환합니다.

curl "https://socksnode.com/api/v1/mobile/catalog?state=12&availability=1" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
응답200
{
  "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"
응답200
{
  "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"
응답200
{
  "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기본값: basic

  • durationKeystring필수

    대여 기간. 해당 요금제가 판매하는 기간이어야 합니다.

    2h12h1d3d7d15d30d

  • quantityinteger선택 사항

    대여할 포트 수, 1–50. 생성되지 않은 포트는 청구되지 않습니다.

    기본값: 1

  • countryIdinteger선택 사항

    카탈로그의 국가 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"
  }'
응답201
{
  "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"
  }'
응답200
{
  "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"
응답200
{
  "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"
응답200
{
  "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"
응답200
{
  "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"
  }'
응답200
{
  "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가 비밀번호 없이 연결.

    userpasswhitelist

  • allowedIpsstring[]선택 사항

    공인 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"
    ]
  }'
응답200
{
  "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"
  }'
응답200
{
  "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}

만들 준비가 되셨나요?

대시보드에서 자격 증명을 생성하거나 API 키를 만들어 자동화하세요.