IP Transit API v1.0.0

https://shulker.in/api/ip_transit-v1.0/

X-API-Key: sk_1e14aecda1a06bc22062f8fcb8e90cbde309d29d1e7955378b1aeaf6c130cdc3

Authorization: Bearer sk_1e14aecda1a06bc22062f8fcb8e90cbde309d29d1e7955378b1aeaf6c130cdc3

?api_key=sk_1e14aecda1a06bc22062f8fcb8e90cbde309d29d1e7955378b1aeaf6c130cdc3

{
  "read": [],
  "write": [],
  "ip_transit": ["list", "view", "monitor", "history"]
}

X-RateLimit-Remaining-Minute: 47
X-Request-Id: req_9f2c1a7b3d4e5f60
Retry-After: 60            # only present on 429

"_meta": {
  "request_id": "req_9f2c1a7b3d4e5f60",
  "timestamp": "2026-01-07T16:28:03+00:00",
  "response_time": "0.0412s",
  "version": "1.0.0",
  "rate_limit": {
    "minute_remaining": 47,
    "hour_remaining": 982,
    "day_remaining": 9961
  }
}

{
  "success": false,
  "error": "This API key does not have permission for this action.",
  "error_code": "insufficient_permissions",
  "code": 403,
  "required_permission": "monitor",
  "granted_permissions": ["list", "view"],
  "_meta": {
    "request_id": "req_9f2c1a7b3d4e5f60",
    "timestamp": "2026-01-07T16:28:03+00:00",
    "response_time": "0.0021s",
    "version": "1.0.0",
    "rate_limit": {
      "minute_remaining": 59,
      "hour_remaining": 999,
      "day_remaining": 9999
    }
  }
}

import os
import requests
from typing import Optional, Dict, Any


class IPTransitAPI:
    def __init__(self, api_key: str,
                 base_url: str = "https://shulker.in/api/ip_transit-v1.0/"):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "X-API-Key": api_key,
            "Accept": "application/json",
        })

    def _request(self, params: Dict[str, Any], method: str = "GET") -> Dict[str, Any]:
        if method.upper() == "GET":
            response = self.session.get(self.base_url, params=params)
        else:
            response = self.session.request(method, self.base_url, json=params)
        return response.json()

    def info(self) -> Dict[str, Any]:
        return self._request({"action": "info"})

    def list_ips(self, status: Optional[str] = None) -> Dict[str, Any]:
        params = {"action": "list"}
        if status:
            params["status"] = status
        return self._request(params)

    def get_ip(self, ip_id: Optional[int] = None,
               ip: Optional[str] = None) -> Dict[str, Any]:
        params = {"action": "get"}
        if ip_id is not None:
            params["id"] = ip_id
        elif ip:
            params["ip"] = ip
        return self._request(params)

    def monitor(self, ip_id: Optional[int] = None,
                ip: Optional[str] = None) -> Dict[str, Any]:
        params = {"action": "monitor"}
        if ip_id is not None:
            params["id"] = ip_id
        elif ip:
            params["ip"] = ip
        return self._request(params)

    def history(self, ip_id: Optional[int] = None,
                limit: int = 50) -> Dict[str, Any]:
        params = {"action": "history", "limit": limit}
        if ip_id is not None:
            params["id"] = ip_id
        return self._request(params)

    def set_alias(self, ip_id: int, alias: str) -> Dict[str, Any]:
        return self._request(
            {"action": "set_alias", "id": ip_id, "alias": alias},
            method="POST",
        )

    def install_command(self, ip_id: int, ttl_hours: int = 24) -> Dict[str, Any]:
        return self._request(
            {"action": "install_command", "id": ip_id, "ttl_hours": ttl_hours},
            method="POST",
        )


# Usage
if __name__ == "__main__":
    client = IPTransitAPI(os.environ["SHULKER_API_KEY"])

    # Discover what this key can do
    info = client.info()
    if not info["success"]:
        raise SystemExit(info["error"])

    print(f"Key: {info['key']['name']} — perms: {info['granted_permissions']}")

    # List every IP, summarised
    listing = client.list_ips()
    for entry in listing["ips"]:
        print(f"{entry['ip']:16} {entry['status']:10} {entry['days_left']}d left")

    # Alert on anything not healthy
    for entry in listing["ips"]:
        if entry["status"] in ("expiring", "expired", "suspended"):
            print(f"WARN: {entry['ip']} is {entry['status']}")

    # Live traffic snapshot
    live = client.monitor()
    for entry in live.get("ips", []):
        print(f"{entry['ip']} online={entry['online']} rx={entry['rx_mbps']}Mbps tx={entry['tx_mbps']}Mbps")

class IPTransitAPI {
  constructor(apiKey, baseUrl = 'https://shulker.in/api/ip_transit-v1.0/') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async request(params, method = 'GET') {
    const url = new URL(this.baseUrl);

    if (method === 'GET') {
      url.search = new URLSearchParams(params).toString();
      const res = await fetch(url, { headers: { 'X-API-Key': this.apiKey } });
      return res.json();
    }

    const res = await fetch(url, {
      method,
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(params),
    });
    return res.json();
  }

  info()                { return this.request({ action: 'info' }); }
  listIPs(status)       { return this.request({ action: 'list', ...(status ? { status } : {}) }); }
  getIP(id)             { return this.request({ action: 'get', id }); }
  monitor(id)           { return this.request({ action: 'monitor', ...(id ? { id } : {}) }); }
  history(id, limit=50) { return this.request({ action: 'history', id, limit }); }
  setAlias(id, alias)   { return this.request({ action: 'set_alias', id, alias }, 'POST'); }
  installCommand(id, ttlHours = 24) {
    return this.request({ action: 'install_command', id, ttl_hours: ttlHours }, 'POST');
  }
}

// Usage
async function main() {
  const client = new IPTransitAPI(process.env.SHULKER_API_KEY);

  const info = await client.info();
  if (!info.success) throw new Error(info.error);

  console.log(`Key ${info.key.name} → ${info.granted_permissions.join(', ')}`);

  const listing = await client.listIPs();
  listing.ips.forEach(ip => {
    console.log(`${ip.ip}  ${ip.status}  ${ip.days_left}d left`);
  });

  // Rename an IP
  const renamed = await client.setAlias(42, 'Edge Frankfurt');
  console.log(`Alias set to: ${renamed.alias}`);

  // Live snapshot
  const live = await client.monitor();
  live.ips.forEach(ip => {
    console.log(`${ip.ip} online=${ip.online} rx=${ip.rx_mbps} tx=${ip.tx_mbps}`);
  });
}

main().catch(err => { console.error(err); process.exit(1); });

#!/usr/bin/env bash
set -euo pipefail

API_KEY="${SHULKER_API_KEY:?set SHULKER_API_KEY first}"
BASE="https://shulker.in/api/ip_transit-v1.0/"
IP_ID="42"

api() {
  # $1 = query string (no leading ?)
  curl -fsS "${BASE}?$1" -H "X-API-Key: ${API_KEY}"
}

api_post() {
  # $1 = JSON body
  curl -fsS -X POST "${BASE}" \
    -H "X-API-Key: ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d "$1"
}

echo "→ Listing IPs"
api "action=list" | jq -r '
  "Total: \(.summary.total)  active: \(.summary.active)  expiring: \(.summary.expiring)",
  (.ips[] | "  \(.ip)\t\(.status)\t\(.days_left)d left")'

echo "→ Live status for IP #${IP_ID}"
api "action=monitor&id=${IP_ID}" | jq -r '
  "online=\(.live.online) rx=\(.live.rx_mbps)Mbps tx=\(.live.tx_mbps)Mbps"'

echo "→ Generating a fresh install command (TTL 1h)"
INSTALL=$(api_post "{
  \"action\": \"install_command\",
  \"id\": ${IP_ID},
  \"ttl_hours\": 1
}" | jq -r '.install_command')

# Run it on the server that should announce the IP.
echo "Run on your server:"
echo "  ${INSTALL}"