# MangoProxy Tools API

Use MangoProxy's free public network tools programmatically: IP lookup, proxy
checker, port scanner and IP trace. No account or API key is required.

## Discovery

- API catalog (RFC 9727): https://mangoproxy.com/.well-known/api-catalog
- OpenAPI 3.1 spec: https://mangoproxy.com/.well-known/openapi.json
- Health: https://mangoproxy.com/.well-known/health
- Human documentation: https://mangoproxy.com/tools/

## Transport

All tools are dispatched through WordPress `admin-ajax.php` using an `action`
parameter and are protected by a per-session WordPress nonce obtained from the
matching tool page. They are rate-limited per client IP and return a WordPress
JSON envelope: `{ "success": true|false, "data": { ... } }`.

Endpoint base: `https://mangoproxy.com/wp-admin/admin-ajax.php`

## Tools

### IP lookup
- Action: `ip_lookup` (GET)
- Parameters: `ip` (IPv4/IPv6), `_nonce` (nonce for the `mangoproxy_ip_lookup` action)
- Returns: geolocation, ISP, ASN and network details for the address.

### Proxy checker
- Action: `proxy_checker_test` (POST)
- Parameters: `proxy` (`host:port` or `host:port:login:password`), `_wpnonce`
  (nonce for the `proxy_checker_nonce` action)
- Returns: working status, detected type (HTTP/SOCKS4/SOCKS5), anonymity, speed
  and location.

### Port scanner
- Action: `port_scanner_scan` (POST)
- Parameters: `target` (IP or domain), `scan_type` (`popular` | `all`),
  `_wpnonce` (nonce for the `port_scanner_nonce` action)
- Returns: open/closed status for the scanned ports.

### IP trace
- Action: `ip_trace` (POST)
- Parameters: `target` (IP or domain), `_wpnonce` (nonce for the `ip_trace_nonce` action)
- Returns: the network path (hops) to the target.

## Browser agents (WebMCP)

When a MangoProxy page is loaded in a WebMCP-capable browser, the same tools are
also exposed via `navigator.modelContext` under the names `ip_lookup`,
`proxy_checker`, `port_scanner` and `ip_trace`. The in-browser tools handle the
WordPress nonce automatically, so no manual nonce handling is needed.

## Notes

- The nonce is a CSRF token tied to a page view. For direct HTTP calls, load a
  tool page first to obtain a valid nonce, or use the WebMCP tools in-browser.
- Respect the rate limits; the endpoints return HTTP 429 when they are exceeded.