# Coronium — Mobile 4G/5G Proxies for AI agents & developers

Real carrier mobile IPs from physical 4G/5G devices across ~13 countries.
A mobile proxy here is a real SIM in a real device on a carrier network —
you egress from a CGNAT pool shared with thousands of real phone users, so
sites see human-grade traffic, not "server." Use for account creation,
scraping, ad/SERP verification, retail/sneaker, social automation,
multi-accounting, geo-checks. Same API the human dashboard uses.

Production API: https://api.coronium.io/api/v3
Interactive docs (OpenAPI / Swagger): https://dashboard.coronium.io/api-docs/
Agent skill file (mental model + principles + recipes): https://dashboard.coronium.io/SKILL.md

## Source of truth (docs drift; the running system does not)

When this file disagrees with the system, the system wins. In order:
1. MCP `tools/list` — the exact tools you have right now (counts in prose are indicative).
2. OpenAPI at /api-docs/ — the endpoint contract.
3. Live `/tariffs/available` (stock+price) and `/account/proxies/health` (liveness).
4. This file + SKILL.md — the map and the why, never the final word on what exists today.

## How agents/devs integrate

- MCP server (Claude Code, Claude Desktop, Cursor, Windsurf):
    claude mcp add coronium -- npx -y coronium-proxy-mcp
  npm: https://www.npmjs.com/package/coronium-proxy-mcp
  source: https://github.com/coroniumio/coronium-proxy-mcp
  Auth: CORONIUM_LOGIN + CORONIUM_PASSWORD (a dashboard account).
  After connecting, call tools/list — the published npm package exposes the
  core lifecycle (~34 tools); GitHub main adds pool + extras (~48), pending publish.

- REST API: https://api.coronium.io/api/v3  (JWT via ?auth_token=… from POST /get-token)

## Core flow (buy → use → rotate)

1. GET /tariffs/available   — tariffs with live `stock` + `ip_stack:{ipv4,ipv6,native_ipv6}`
2. POST /payment/buy-modems-with-crypto-balance   — buy from account balance
3. GET /account/proxies   — host, ports, login/password, ext_ip, restartToken
4. Use: http://LOGIN:PASSWORD@HOST:HTTP_PORT  (socks5 on the socks port)
5. Rotate IP: POST /modems/{id}/restart  OR  GET /modems/rotate-modem-by-token/{token}?sync=true
6. Health: GET /account/proxies/health   — don't retry dead modems; POST /modems/{id}/replace to swap

## Operating principles (code-simplifier, for agents)

- Smallest sufficient action: don't rotate when sticky works; restart before replace before buy-new.
- Read reality before acting: tools/list, /tariffs/available, health — query, don't assume.
- A rotate 200 means "accepted," not "done" — use ?sync=true or verify the egress IP changed.
- No looping/speculative mutations; irreversible actions (cancel mid-cycle) need confirmation.
- ~60s/modem rotate cooldown (429 if faster); carrier sticky window ~290s.
- The recipes are defaults, not laws — compose your own; only safety/cost + network physics are fixed.

## Auth options

- Customer (email/password): the MCP above, or POST /get-token.
- Agent-native (wallet + voucher, no email): coronium-cli mints a wallet-bound JWT via SIWE (beta).

Dashboard: https://dashboard.coronium.io
AI Agents hub: https://dashboard.coronium.io/en/agents