# freeiplookupapi: setup for AI coding agents

Official setup steps for freeiplookupapi (https://freeiplookupapi.com). Read this file raw (`curl -s https://freeiplookupapi.com/agents.md`): a summary drops the commands. Run the steps yourself, in order. Where a step says "Ask your human", send the message, then end your turn and wait for the reply.
Never print the API key in chat or logs, commit it, or put it in client-side code. Never fill in our signup, login or payment pages yourself: they are for your human. Never start anything that costs money without your human's yes.

## 1. What freeiplookupapi is
Free IP geolocation lookup.
- API: https://api.freeiplookupapi.com, JSON over HTTPS, the key in the `apikey` header. Not in the URL: `?apikey=` works, but URLs end up in logs.
- Free plan: 5,000 requests a month, 10 a minute. Keys start with `fil_`.
- Docs: https://freeiplookupapi.com/docs/llms.txt · OpenAPI: https://freeiplookupapi.com/docs/openapi.yaml · Plans (JSON): https://api.freeiplookupapi.com/v1/agent/plans

## 2. Get an API key
- The commands below read the key from your shell; load .env first if it is there (`set -a; . ./.env; set +a`), and again after a step wrote the key to it. Those steps need `jq`: they write the key to .env and print the answer without it.
- Have one? If `FREEIPLOOKUPAPI_KEY` is set, check it for free: `curl -s -H "apikey: $FREEIPLOOKUPAPI_KEY" https://api.freeiplookupapi.com/v1/status`. A 200 means it works: go to step 3.
- Permanent key, one click for your human:
  1. `curl -s -X POST https://api.freeiplookupapi.com/v1/agent/sessions -H "content-type: application/json" -d '{"kind":"key","agent":"<your name>"}'`
  2. Ask your human: "Please open <verification_uri_complete>, check that it shows the code <user_code>, sign in (Google or GitHub is fastest), click Approve and tell me when it's done." Then end your turn: do not poll, sleep or loop before your human replies.
  3. When your human replies, fetch the key: `r=$(curl -s -X POST https://api.freeiplookupapi.com/v1/agent/sessions/token -H "content-type: application/json" -d '{"device_code":"<device_code>"}'); printf '%s' "$r" | jq -r '.api_key // empty | "\nFREEIPLOOKUPAPI_KEY=" + .' >> .env; printf '%s' "$r" | jq 'del(.api_key)'`. `error.code` `authorization_pending`: not approved yet, ask your human to finish and end your turn again; `slow_down`: wait the answer's `interval` seconds before the next try; `access_denied` or `expired_token`: stop and tell your human.
  4. The 200 answer carries `api_key`, once, and `team`: the command put the key in .env as `FREEIPLOOKUPAPI_KEY`. Name the team in your summary without waiting for an answer; only if your human says it is not theirs, delete `FREEIPLOOKUPAPI_KEY` from .env and start again.
- Keep .env out of git; add `FREEIPLOOKUPAPI_KEY=` to .env.example.

## 3. Integrate
- Server-side code only; read the key from `FREEIPLOOKUPAPI_KEY`.
- Plain HTTP is enough (fetch, requests, net/http, Laravel Http).
- First call: `curl -s -H "apikey: $FREEIPLOOKUPAPI_KEY" "https://api.freeiplookupapi.com/v1/info?ip=1.1.1.1"` should answer 200.
- In the code: set an HTTP client timeout, and on an error log `error.code`; never let a 401, 403 or 429 switch the feature off silently.
- Errors are JSON: `error.code` plus `actions` (URLs for the next step). 429: wait `Retry-After` seconds; `quota` shows the month's use. `email_not_verified`: ask your human to click the link in our email (a paid plan does not fix it); if they just did, wait 30 s and retry once before you ask again.

## 4. MCP (optional)
- Claude Code: `claude mcp add --transport http freeiplookupapi https://api.freeiplookupapi.com/mcp --header "apikey: $FREEIPLOOKUPAPI_KEY"` (your shell fills in the key, so the command does not show it; default local scope keeps it out of the repo).
- Other clients: streamable HTTP at https://api.freeiplookupapi.com/mcp with the header `apikey` set to `FREEIPLOOKUPAPI_KEY` (the client's env syntax where it has one; never paste the key into chat). Per-client snippets: https://freeiplookupapi.com/agents/

## 5. Plans (always ask your human first)
- freeiplookupapi only has a free plan. For more requests, move to ipbase (its own API key): https://ipbase.com/agents.md

## 6. Finish: tell your human
Finish with a permanent key (or name the step your human still has to do), and always with the Plan line.
```
freeiplookupapi setup
- Key: in .env as FREEIPLOOKUPAPI_KEY (not committed)
- First call: <endpoint> -> 200
- MCP: added | skipped
- Plan: <current>; recommended: <plan> at <price> because <requests a month, features> | none (why the free plan is enough)
```
These steps are published at https://freeiplookupapi.com/agents.md; fetch it again to check them.
<!-- everapi-agent product=freeiplookupapi keyless=0 trial=0 sessions=1 checkout=0 -->