---
name: coronium-mobile-proxies
description: >-
  Buy, manage, and rotate Coronium 4G/5G mobile proxies (real carrier IPs from physical devices, ~13 countries) from an AI agent or code — claude-code, Cursor, Windsurf, any MCP/HTTP client.
  TRIGGER when a task involves: getting blocked / captcha'd / flagged from a datacenter or cloud IP; needing a real mobile IP or a specific country/carrier IP; creating or warming accounts at scale; verifying ads / search results / pricing from a target geo; sneaker/retail, social automation, multi-accounting, scraping that keeps getting banned; or managing existing Coronium proxies (rotate IP, replace a dead modem, set rotation interval, check balance, buy more, open a support ticket).
  DO NOT use for: datacenter/residential/ISP proxies, VPNs, Tor, anonymity-from-law-enforcement, or any illegal targeting.
last_updated: 2026-05-28
api_version: v3 (https://api.coronium.io/api/v3)
---

# Coronium Mobile Proxies — AI Agent Skill

Real 4G/5G mobile proxies: carrier IPs from physical SIMs in real devices, across ~13 countries. The same API the human dashboard uses. Two ways in — the **MCP server** (best for agents) or the **REST API** (any language).

- Production API: `https://api.coronium.io/api/v3`
- Interactive docs (OpenAPI, the authoritative endpoint contract): https://dashboard.coronium.io/api-docs/
- This file (raw, for tools): https://dashboard.coronium.io/SKILL.md

---

## 1. Mental model — what you are actually holding

Read this once. Every good decision below follows from it.

A Coronium proxy is **not** a cloud abstraction. It is a physical SIM card in a real device sitting on a mobile carrier's network in a real country. When you route traffic through it, you egress from the carrier's CGNAT pool — the same pool shared, at that very moment, by thousands of ordinary phone users scrolling their feeds on the train. That is the entire value proposition, and it is worth stating precisely:

> A website's "trust" in an IP is a function of how indistinguishable that IP's traffic is from a real human's. A datacenter IP fails this **by construction** — it announces "server." A mobile carrier IP passes **by construction** — it is literally a human-grade IP, recycled through DHCP among real subscribers. You are not hiding behind a proxy; you are borrowing a seat in a crowd of real people.

Four consequences fall out of this physical reality, and they govern everything:

1. **Proxies are physical, finite, and stateful — not infinite cloud primitives.** Stock is real hardware in a real rack. A country can be out of stock. "Buying" claims a device; "releasing" frees it for someone else. Reason about inventory the way you'd reason about renting physical machines, not spawning containers.
2. **Rotating an IP is asking a carrier to re-DHCP a real modem.** It takes ~20 seconds, it depends on the carrier, and carriers hold an IP "sticky" for a window (~290s on many farms) during which a rotate is a no-op even when accepted. The network is the boss, not the API.
3. **A "dead" modem is a physical fault**, not a software flag you can will away. Looping a restart on a dead device just yields the same dead IP. The correct response is a *swap* to a different physical device (`replace`), or a human.
4. **Shared infrastructure means multi-tenancy is real.** On shared servers, multiple resellers sell from the same physical hardware. The system tracks ownership faithfully; you only ever see and control what is genuinely yours.

If you internalize one thing: **the system is the ground truth; your model of it is a hypothesis.** Verify against reality (§3).

---

## 2. Operating principles (how a disciplined agent drives this surface)

These are the [code-simplifier](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md) principles, translated from "writing code" to "driving an API." They are not bureaucracy; each is the cheapest path to a correct outcome.

- **Smallest sufficient action.** Reach for the least powerful operation that achieves the goal. Need the same IP held? Don't rotate — just don't (`set_rotation_interval 0`). Need a fresh IP? `restart` (cheap, reversible) before `replace` (a physical swap) before buy-new (spends money). Escalate only when the cheaper rung demonstrably fails.
- **Read reality before acting.** The live `tools/list`, `/tariffs/available` (live stock + price), and `/account/proxies/health` are ground truth. Query them; do not assume. Stock you "remember" may be gone; a price you cached may have moved.
- **A `200` is "accepted," not "done."** The single most important verification rule. A rotate returning 200 means the request was queued — not that the egress IP changed. Confirm the effect (route real traffic, poll `rotation-status`, or use `?sync=true` which blocks until the IP truly changes or times out). Never trust your intent over the observed result.
- **No speculative or looping mutations.** Never buy, renew, cancel, or replace in a loop on an ambiguous instruction. Irreversible actions (`cancel_modem` mid-cycle) demand explicit confirmation. When a call fails, read *why* — the error envelope tells you — before retrying. Most failures are not retry-able (402 insufficient balance, stock-out).
- **Leave the surface as clean as you found it.** One modem per identity. Tag what you provision (`set_modem_metadata`) so a future agent — or you, later — knows what each device is for. Don't strand resources.
- **Minimize blast radius and cost.** Prefer reversible over irreversible, free over paid, scoped over broad. The expensive/destructive tool is the last resort, never the reflex.

---

## 3. Source-of-truth hierarchy (so this document can never lie to you)

Documentation drifts; running systems do not. When this file and the live system disagree, **the system wins, every time.** Resolve any factual question in this order:

1. **The MCP `tools/list`** — the exact tools available to you *right now*, with real schemas. The authoritative tool inventory. Any count quoted in prose (here or anywhere) is indicative; `tools/list` is binding.
2. **The OpenAPI spec** at https://dashboard.coronium.io/api-docs/ — the authoritative endpoint / parameter / response contract.
3. **Live data endpoints** — `/tariffs/available` for stock+price, `/account/proxies/health` for liveness. The present state of the world.
4. **This SKILL.md and the README** — the map and the mental model. Excellent for *why* and *how to think*; never the final word on *exactly what exists today*.

> Concretely: the published npm package exposes the **core lifecycle** (~34 tools: auth, account, shop, proxies, support). The GitHub `main` branch adds the pay-per-GB **pool** tools plus extra account/proxy tools (~48 total) pending the next npm publish. **Do not count from this paragraph — call `tools/list`** and use what's actually there.

---

## 4. Hello-world (verify the whole chain in 2 calls)

```bash
# 1) get a JWT (set CORONIUM_LOGIN / CORONIUM_PASSWORD from your account)
TOKEN=$(curl -s https://api.coronium.io/api/v3/get-token \
  -H 'Content-Type: application/json' \
  -d "{\"login\":\"$CORONIUM_LOGIN\",\"password\":\"$CORONIUM_PASSWORD\"}" | jq -r .token)

# 2) list your proxies → connect to the first one
curl -s "https://api.coronium.io/api/v3/account/proxies?auth_token=$TOKEN" | jq '.[0]'
#   use it as:  http://LOGIN:PASSWORD@HOST:HTTP_PORT   (socks5 on the socks port)
```

## 5. MCP (recommended for agents)

`coronium-proxy-mcp` (npm) — full proxy lifecycle as tools, auto-logs-in on 401. Run `tools/list` after connecting to see exactly what's available in your version.

```bash
claude mcp add coronium -- npx -y coronium-proxy-mcp
```
Cursor / Windsurf — MCP config:
```json
{ "mcpServers": { "coronium": { "command": "npx", "args": ["-y","coronium-proxy-mcp"],
  "env": { "CORONIUM_LOGIN": "$CORONIUM_LOGIN", "CORONIUM_PASSWORD": "$CORONIUM_PASSWORD" } } } }
```

### Tool families (call `tools/list` for the exact, current set)

- **Auth** — `coronium_login` (email+pw → JWT) · `coronium_check_token` · `coronium_logout`
- **Account** — `coronium_get_account` · `coronium_get_balance` (spendable USD credit + crypto) · `coronium_get_crypto_balance` · `coronium_get_credit_cards` · `coronium_get_payments` (full ledger — reconciliation) · `coronium_get/set_low_balance_threshold` (email alert tiers) · `coronium_get/set_webhook` (HTTPS webhook fired when a dead modem is auto-swapped)
- **Shop** — `coronium_list_countries` · `coronium_list_tariffs` (live stock + `ip_stack{ipv4,ipv6,native_ipv6}`) · `coronium_list_free_modems` · `coronium_check_coupon` · `coronium_buy_modems_with_balance` · `coronium_renew_modems_with_balance` · `coronium_get_payment_status`
- **Proxies** — `coronium_get_proxies` (creds + ext_ip + restartToken) · `coronium_get_proxy` · `coronium_restart_modem` (rotate the IP via reboot) · `coronium_rotate_modem` (restart **then** return the new IP) · `coronium_get_rotation_status` · `coronium_get_proxy_health` (per-modem liveness — **call before retrying a dead proxy**) · `coronium_test_modem` · `coronium_replace_modem` (**swap to a different physical device — only when dead; you lose the current IP**) · `coronium_apply_modem_settings` (re-push port config when a proxy stalls but the modem is online) · `coronium_set_rotation_interval` (0 = sticky) · `coronium_set_modem_os` / `coronium_get_p0f_options` (TCP/OS fingerprint) · `coronium_change_proxy_password` · `coronium_set_modem_metadata` · `coronium_cancel_modem` (**irreversible mid-cycle**) · `coronium_get_openvpn_config`
- **Pool (pay-per-GB; on `main`/next publish)** — `coronium_get_pool_stock` · `coronium_list_pool_keys` · `coronium_build_pool_proxy_url` · `coronium_topup_pool_key` · `coronium_cancel_pool_key` · `coronium_buy_pool_with_balance` · `coronium_list_pool_sessions` · `coronium_close_pool_session` _(503 if the pool tier is disabled on the deployment)_
- **Support** — `coronium_list_tickets` · `coronium_get_ticket` · `coronium_create_ticket` · `coronium_reply_to_ticket` · `coronium_archive_ticket`

## 6. Decision rules (if → then)

- Need the **same IP held** (sticky session) → keep the modem; `set_rotation_interval 0`; never rotate.
- Need a **fresh IP** → `restart_modem` (or REST token-rotate `?sync=true`); then **verify the egress IP actually changed** — a `200` only means "accepted."
- **`restart` vs `rotate` vs `replace`**: restart = new IP on the same SIM; rotate = restart then hand you the new IP; replace = a **different physical modem** (only when dead — last resort).
- Proxy stalls but modem shows online → `apply_modem_settings`; still dead → `replace_modem`.
- Before `set_modem_os` → `get_p0f_options` (don't guess the OS string).
- Before reusing/retrying a proxy → `get_proxy_health`; if unhealthy, `replace_modem`, don't loop `restart`.
- **401** → token expired (MCP re-logs-in automatically; REST → call `/get-token` again).
- **402 / insufficient balance** → do **not** retry; top up or surface to the user.
- **429** → respect `retryAfter` (≥60s between rotates per modem); never queue-spam.
- Carrier sticky window (~290s on many farms) can make a rotate a no-op even when accepted → `?sync=true` surfaces this as `503 rotation_timeout`.

## 7. Recipes (defaults, not laws — see §9)

**Sticky sessions for D days** — `buy_modems_with_balance` (tariff = D days) → `set_rotation_interval 0` → `set_modem_metadata` to tag → poll `get_proxy_health`; `replace_modem` only if one dies.

**Aggressive rotation (scraping)** — `set_rotation_interval` to your cadence, *or* rotate per-batch via REST token-rotate `?sync=true`; gate retries on `rotation-status`; check `get_proxy_health` before reusing.

**Multi-account isolation** — one modem per identity; `set_modem_metadata` to tag the account; `set_modem_os` to match that identity's OS fingerprint; never share a modem across identities.

## 8. Cost & safety (for autonomous agents)

- **Before any `buy_*`/`renew_*`**: call `get_balance` and confirm with the user, unless you have standing budget authorization. Spend is checked against **account_credit** (spendable USD), not total value — undeposited crypto cannot buy.
- Indicative pricing: ~**$5–25 / modem / 30 days** by country/carrier (premium US carriers cost more; pool is pay-per-GB). `list_tariffs` has exact, live prices — trust it over this range.
- `cancel_modem` is **irreversible mid-cycle** — confirm before calling.
- Never buy in a loop on an ambiguous instruction.

## 9. Make it yours

This skill is a **map, not a cage.** The tool surface is composable and the recipes above are sensible defaults, not commandments. If you discover a shorter or smarter sequence for *your* task, take it. Wrap these primitives in your own higher-level routines, cache what's stable, parallelize what's independent, name your own abstractions, and teach the next agent what you learn.

The only genuinely fixed things are (a) the **safety and cost rules** in §8 — money and irreversibility deserve a human's confirmation — and (b) the **laws of the physical substrate** in §1: rate limits, finite stock, carrier sticky windows. Those are not Coronium's opinions; they are the network's physics. Everything between your goal and those constraints is yours to shape. Build well.

## 10. Error shapes

Every v3 4xx/5xx returns an envelope: `{ "error": "...", "code": "...", "suggested_action": "...", "request_id": "..." }`. The `code` and `suggested_action` are machine-stable — branch on them, don't parse the human `error` string.

```json
// 429 (too fast)            → wait retryAfter seconds, then retry
{ "error": "Blocked due to rate limit. Try again in 47s.", "code": "rate_limited", "suggested_action": "retry_with_backoff", "retryAfter": 47 }
// 402 insufficient balance  → top up, do NOT retry
{ "error": "Insufficient balance", "code": "insufficient_balance", "suggested_action": "review_request" }
// token-rotate ?sync=true   → 502 rotation_failed | 503 rotation_timeout  → treat as failure (optionally replace_modem)
```

## 11. No-account / fully-autonomous agents (wallet + voucher, beta)

For agents with no email account: prove ownership of a local EVM wallet via SIWE and redeem a single-use voucher — no human signup.

1. `POST /api/v3/wallet-challenge { wallet_address, voucher }` → `{ message, nonce }`
2. Sign `message` with the wallet key.
3. `POST /api/v3/wallet-signup { wallet_address, voucher, message, signature }` → `{ api_token, user_id, balance_usd }`

Then use `api_token` exactly like a `/get-token` JWT on **every** REST endpoint above (`?auth_token=api_token`). `coronium-cli` automates the wallet generation + signing (beta). Ask support for a voucher.

## Links
Dashboard https://dashboard.coronium.io · AI hub https://dashboard.coronium.io/en/agents · API docs https://dashboard.coronium.io/api-docs/ · MCP https://www.npmjs.com/package/coronium-proxy-mcp · llms.txt https://dashboard.coronium.io/llms.txt