StatesideIP API documentation

Authentication

Every request except the public catalogue carries an API key: Authorization: Bearer API_KEY. A key is shown in full once, when you create it: store it like a password. Revoke a key at any time; requests made with it then return 401 unauthorized.

curl -s "https://statesideip.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"

Requests and responses

• JSON in, JSON out: send Content-Type: application/json with a body.
• Lists that can grow are paginated with page (from 1) and perPage (1–100, default 20) and return { "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }. Short lists return { "data": [...] }.
• IDs are opaque strings with a type prefix: ord_ (order), top_ (top-up), txn_ (balance movement), res_ (traffic subscription), mob_ (mobile port), key_ (API key), ipw_ (whitelisted IP).
• Safe retries: POST /v1/orders and POST /v1/topups accept an Idempotency-Key header (any unique string, kept 24 h). Replaying the same key returns the first response instead of buying or topping up twice.
• Examples show the shape of each answer: the IDs, IPs, amounts and dates in them are illustrative, the plan ids and prices are the real ones.

Errors

Every error has the same body. code is stable and meant for your code; message is an English sentence that may change. Validation errors list each invalid field in fields. New codes may be added: handle unknown codes as a generic failure.

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}

Rate limits

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Above the limit the API answers 429 rate_limited with a Retry-After header (seconds): wait that long, then retry. Changing the IP of a mobile port is limited separately: one rotation every 30 seconds per port by default (429 rotation_too_soon).