# Client IP API
> Find the real client IP behind proxies, CDNs and load balancers. The client endpoint takes an X-Forwarded-For list (or an RFC 7239 Forwarded header) together with a count of proxies you trust, and returns the actual client address — stripping the trusted proxies from the right-hand side so that a spoofed left-most value cannot fool you — along with the full ordered hop chain, the left-most and right-most entries and the address family. The parse endpoint decomposes a Forwarded header into its for/by/host/proto hops, or an X-Forwarded-For header into its ordered list of addresses, stripping ports and IPv6 brackets so you get clean IPs. Getting this right matters for security: trusting the wrong entry lets clients spoof their IP, so the trusted-proxy model returns the first address you did not put there yourself. Everything is computed locally and deterministically, so it is instant and private. Ideal for reverse proxies and API gateways, rate limiting and abuse prevention, audit logging and analytics, geo and fraud checks, and any backend sitting behind a load balancer. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This parses forwarding headers to find the client IP; to geolocate that IP use an IP-geolocation API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/clientip-api/..."
```

## Pricing
- **Free** (Free) — 3,135 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 12,650 calls/Mo, 8 req/s
- **Pro** ($25/Mo) — 177,500 calls/Mo, 20 req/s
- **Mega** ($63/Mo) — 930,000 calls/Mo, 50 req/s

## Endpoints

### Client IP

#### `GET /v1/client` — Find the client IP

**Parameters:**
- `xff` (query, optional, string) — The X-Forwarded-For header value Example: `203.0.113.5, 70.41.3.18, 150.172.238.178`
- `forwarded` (query, optional, string) — An RFC 7239 Forwarded header (alternative to xff)
- `trusted` (query, optional, string) — Number of trusted proxies to skip from the right (default 0) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clientip-api/v1/client?xff=203.0.113.5%2C+70.41.3.18%2C+150.172.238.178&trusted=1"
```

**Response:**
```json
{
    "data": {
        "hops": 3,
        "kind": "ipv4",
        "chain": [
            "203.0.113.5",
            "70.41.3.18",
            "150.172.238.178"
        ],
        "leftmost": "203.0.113.5",
        "client_ip": "70.41.3.18",
        "rightmost": "150.172.238.178",
        "trusted_proxies": 1
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:01.602Z",
        "request_id": "9525950b-0d71-453d-9cf5-f0ceb80a3f18"
    },
    "status": "ok",
    "message": "Find the client IP",
    "success": true
}
```

#### `GET /v1/parse` — Parse a forwarding header

**Parameters:**
- `header` (query, required, string) — A Forwarded or X-Forwarded-For header value Example: `203.0.113.5, 70.41.3.18, 150.172.238.178`
- `type` (query, optional, string) — auto (default), forwarded or xff

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clientip-api/v1/parse?header=203.0.113.5%2C+70.41.3.18%2C+150.172.238.178"
```

**Response:**
```json
{
    "data": {
        "type": "x-forwarded-for",
        "count": 3,
        "addresses": [
            {
                "ip": "203.0.113.5",
                "raw": "203.0.113.5",
                "kind": "ipv4"
            },
            {
                "ip": "70.41.3.18",
                "raw": "70.41.3.18",
                "kind": "ipv4"
            },
            {
                "ip": "150.172.238.178",
                "raw": "150.172.238.178",
                "kind": "ipv4"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:01.688Z",
        "request_id": "7aed550f-ea98-4fe1-9bdf-748114f32428"
    },
    "status": "ok",
    "message": "Parse a forwarding header",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clientip-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Client IP API",
        "notes": "X-Forwarded-For is ordered client, proxy1, proxy2 (left to right); the right-most entry is the closest proxy. Set trusted to the number of proxies in front of your app so the returned IP is the first untrusted one. Ports and IPv6 [brackets] are stripped. This parses headers — it does not geolocate the IP. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/client",
                "params": {
                    "xff": "the X-Forwarded-For header value",
                    "trusted": "number of trusted proxies to skip from the right (default 0)",
                    "forwarded": "an RFC 7239 Forwarded header (alternative to xff)"
                },
                "returns": "the client IP and the full chain"
            },
            {
                "path": "/v1/parse",
                "params": {
                    "type": "auto (default), forwarded or xff",
                    "header": "a Forwarded or X-Forwarded-For header value (required)"
                },
                "returns": "the parsed hops or address list"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Find the real client IP behind proxies and load balancers. The client endpoint takes an X-Forwarded-For list (or an RFC 7239 Forwarded head
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/clientip-api
OpenAPI spec: https://www.oanor.com/api/clientip-api/openapi.json