# ipbase: setup for AI coding agents

Official setup steps for ipbase (https://ipbase.com). Read this file raw (`curl -s https://ipbase.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 ipbase is
IP geolocation, ASN and hosted-domain lookups.
- API: https://api.ipbase.com, JSON over HTTPS, the key in the `apikey` header. Not in the URL: `?apikey=` works, but URLs end up in logs.
- Free plan: 150 requests a month, 10 a minute. Keys start with `ipb_`.
- Docs: https://ipbase.com/docs/llms.txt · OpenAPI: https://ipbase.com/docs/openapi.yaml · Plans (JSON): https://api.ipbase.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 `IPBASE_KEY` is set, check it for free: `curl -s -H "apikey: $IPBASE_KEY" https://api.ipbase.com/v2/status`. A 200 means it works: go to step 3.
- Without a key, up to 10 requests an hour from your IP work (leave out the `apikey` header). Enough to build and test; get a key before you finish.
- Permanent key, one click for your human:
  1. `curl -s -X POST https://api.ipbase.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.ipbase.com/v1/agent/sessions/token -H "content-type: application/json" -d '{"device_code":"<device_code>"}'); printf '%s' "$r" | jq -r '.api_key // empty | "\nIPBASE_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 `IPBASE_KEY`. Name the team in your summary without waiting for an answer; only if your human says it is not theirs, delete `IPBASE_KEY` from .env and start again.
- Keep .env out of git; add `IPBASE_KEY=` to .env.example.

## 3. Integrate
- Server-side code only; read the key from `IPBASE_KEY`.
- Plain HTTP is enough (fetch, requests, net/http, Laravel Http). Do not use ipbase-go v0.1.1: it calls the wrong endpoint and exits the process.
- First call: `curl -s -H "apikey: $IPBASE_KEY" "https://api.ipbase.com/v2/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 ipbase https://api.ipbase.com/mcp --header "apikey: $IPBASE_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.ipbase.com/mcp with the header `apikey` set to `IPBASE_KEY` (the client's env syntax where it has one; never paste the key into chat). Per-client snippets: https://ipbase.com/agents/

## 5. Plans (always ask your human first)
- Read https://api.ipbase.com/v1/agent/plans. Pick the cheapest plan that covers the expected requests a month and the features needed. Security data and the ASN and hosted-domain endpoints need medium or higher.
- Do not guess the volume. If the task does not say how many requests a month it needs (and whether the use is commercial), ask your human, best in the same message as step 2's link.
- Ask: "The free plan covers 150 requests a month. I recommend <plan> at <price> a month plus VAT because <reason>. Shall I set it up?"
- On yes: give your human the plan's `upgrade_url` (they have an account) or `register_url` (they don't). Nothing is charged until they confirm there.
- Check: `curl -s -H "apikey: $IPBASE_KEY" https://api.ipbase.com/v2/status` shows `plan.name`.

## 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.
```
ipbase setup
- Key: in .env as IPBASE_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://ipbase.com/agents.md; fetch it again to check them.
<!-- everapi-agent product=ipbase keyless=1 trial=0 sessions=1 checkout=0 -->