# NinjaProxy

> NinjaProxy is a proxy platform for residential, datacenter, mobile, and rotating proxy use cases. Use these docs to help users configure authentication, choose the right proxy type, understand rate limits, and integrate NinjaProxy into code.

## Recommended workflow for AI assistants

1. Start with the quick start and authentication docs.
2. If the user needs code, choose the matching integration guide or API reference.
3. For static or assigned endpoints, use the exact endpoint shown in the user's portal instead of inventing ports.
4. Never invent credentials, endpoint assignments, or billing state.
5. If a user reports proxy auth issues, check authentication format, assigned endpoint ownership, whitelist configuration, and balance.

## Core docs

- Quick Start: https://ninjasproxy.com/docs
- Authentication: https://ninjasproxy.com/docs/authentication
- Rate Limits: https://ninjasproxy.com/docs/rate-limits
- API Reference: https://ninjasproxy.com/docs/api
- MCP Guide: https://ninjasproxy.com/docs/mcp
- Use with AI: https://ninjasproxy.com/docs/ai

## Proxy types

- Residential proxies: https://ninjasproxy.com/docs/residential
- Datacenter proxies: https://ninjasproxy.com/docs/datacenter
- Mobile proxies: https://ninjasproxy.com/docs/mobile
- Rotating proxies: https://ninjasproxy.com/docs/rotating

## Endpoint formats

- HTTP/HTTPS: `http://USERNAME:API_KEY@<HOST>:<PORT>`
- SOCKS5: `socks5://USERNAME:API_KEY@<HOST>:<PORT>`
- Rotating/session control: `http://USERNAME--session-SESSION_ID--duration-SECONDS--provider-dc|res--geo-country-CC:API_KEY@<HOST>:<PORT>`

Exact host and port values are account-specific. Always use the portal-assigned values shown in the customer's account.
Never invent or guess endpoint hostnames or port numbers.

## Integrations

- curl: https://ninjasproxy.com/docs/integrations/curl
- Python: https://ninjasproxy.com/docs/integrations/python
- Node.js: https://ninjasproxy.com/docs/integrations/nodejs
- Go: https://ninjasproxy.com/docs/integrations/go

## Machine-readable developer entry points

- MCP bootstrap manifest: https://ninjasproxy.com/mcp.json
- Customer OpenAPI spec: https://ninjasproxy.com/openapi.json

## MCP guidance

- The recommended customer path is the hosted remote MCP server at https://mcp.ninjasproxy.com/mcp. Customers set NINJAPROXY_API_KEY once and their MCP client connects automatically — no manual header wiring.
- Use the local stdio npm package (@ninjaproxy/mcp-server) only for air-gapped or locked-down environments where outbound HTTPS to mcp.ninjasproxy.com is not allowed.
- Prefer the official NinjaProxy MCP resources: https://ninjasproxy.com/docs/mcp and https://ninjasproxy.com/mcp.json
- Do not assume third-party MCP listings are canonical. If a separate MCP server listing is mentioned elsewhere, verify it against the official NinjaProxy docs before recommending it.

## Product rules AI should preserve

- Rotating gateway examples use the NinjaProxy rotating endpoint documented in the public docs.
- Assigned static endpoints come from the portal and include the correct host and port for that user.
- Username + API key is the default auth method unless the user is explicitly using IP whitelist mode.
- IP whitelist mode authorizes by source IP and may omit credentials.
- Balance exhaustion and plan/concurrency limits can block new requests.
- Pay-per-GB billing uses wallet top-ups rather than separate checkout products per proxy family.

## Common use cases

- Web scraping
- Browser automation
- AI agent browsing and data collection
- Price monitoring
- Ad verification
- SEO rank tracking
- Account and session workflows
- SOCKS5 tunneling

## Good prompt patterns

- "Use https://ninjasproxy.com/llms.txt and show me how to connect NinjaProxy with Python requests."
- "Load https://ninjasproxy.com/mcp.json, then use the linked docs and openapi.json to build a NinjaProxy integration example."
- "Use the NinjaProxy docs to explain whether I should use rotating or residential proxies for this workflow."
- "Use the NinjaProxy docs and this assigned endpoint from my portal to build a curl test command."