# Whizbrew for agents: quote, start, add money, claim

This file is for you, the AI agent. Whizbrew is one MCP server and one API for 890 live marketing data tools in 25 groups, paid per call: a typical call costs $0.002 ($2 per 1,000 calls), prices run from $0.001 to $0.52 a call, only a call that returns data is charged (an empty or failed call is free), and there is no subscription. A new account starts with $2 of free credit, about 1,000 typical calls, with no card.

| Tool | What it returns | Per call that returns data | Per 1,000 calls |
|---|---|---|---|
| `tiktok.profile` | Public TikTok profile of a creator or a brand: its stats (followers, following, likes, number of videos), bio, | $0.002 | $2 |
| `ig.profile` | Public Instagram profile and its counts (followers, following, posts), bio and link, every link of the bio (bi | $0.003 | $3 |
| `reddit.search` | Search Reddit threads inside one subreddit, or in up to 5 subreddits in one call (newest first across them) | $0.002 | $2 |
| `tiktok.comments` | Top-level comments on a public TikTok video (text, author, likes, reply count) | $0.003 | $3 |
| `tiktok.posts` | A TikTok account's recent videos (its posts), newest first: the latest videos of a creator, each with its view | $0.003 | $3 |
| `ig.posts` | Recent Instagram posts and reels of an account, newest first, up to 100 | $0.003 | $3 |
| `appstore.history` | Daily chart rank history of an app | $0.004 | $4 |
| `appstore.reviews` | User reviews of an App Store (iOS) app, newest first or most helpful: star rating, title, text, app version re | $0.004 | $4 |
| `apple_ads.app_ads` | The App Store ads of one app (search results, Today tab, Search tab, product pages) from Apple's ad repository | $0.003 | $3 |
| `appstore.rankings` | Top chart of the App Store for a country and category: 200 deep for free and paid, 100 for grossing | $0.004 | $4 |

All 890 tools with their prices: [https://whizbrew.com/tools?a=7adbfed5ef76](https://whizbrew.com/tools?a=7adbfed5ef76), as data [https://whizbrew.com/v1/tools](https://whizbrew.com/v1/tools).

Whizbrew gives you live public marketing data (social profiles and posts, ad libraries, app stores, SEO, shops, trends: one tool per lookup). You can begin without your human: no email, no sign-up form, no key to paste. Four small steps, each one request. Every answer ends with `next`: the one thing to do or to say to your human. Follow it.

Rules for the whole flow:
- Your key goes only to https://whizbrew.com, only in the header `Authorization: Bearer <key>`. Never print it, never put it in a URL, never put a code in a URL.
- Never pay yourself and never type card data. A payment link is for your human.
- Ask your human one small question at a time, in the words `next` gives you.

## 1. Quote (free, no key)

Before you spend anything, ask what the task costs.

```sh
curl -s "https://whizbrew.com/v1/agent/guide?goal=tiktok+profile+and+recent+videos+of+a+creator&quantity=20&budget_usd=2&a=7adbfed5ef76"
```

- `goal`: the task in plain words. `quantity`: how many calls you expect (default 1). `budget_usd`: what your human allows (optional).
- The answer: `tools` (the tools that do it, best first, each with its price and an example call), `calls` (the requests in order), `estimate` (`price_per_call_usd`, `cost_usd`, the free credit or your balance, `cash_needed_usd`, and with a budget how many calls it buys), `next`.
- A quote never spends and never reserves. `?format=md` gives the same as markdown. Send your key and the quote counts your own balance.
- Only a call that returns data is charged. An empty answer or an error costs nothing.

## 2. Start (no email)

```sh
curl -s -X POST https://whizbrew.com/v1/agent/start?a=7adbfed5ef76 -H 'content-type: application/json' -d '{"agent":"<your name, e.g. Claude Code>"}'
# {"api_key":"sk_tapi_...","claimed":false,"balance_usd":<the free credit>,"expires_at":"...","next":"..."}
```

- `api_key` works at once and holds the free credit. It is shown once: store it now (a file with mode 600, or your secret store).
- The account belongs to nobody yet. **Its key and its credit stop after 7 days unless your human claims it** (step 4).
- Then call a tool:

```sh
curl -s -X POST https://whizbrew.com/v1/call/tiktok.profile -H "Authorization: Bearer $WHIZBREW_API_KEY" \
  -H 'content-type: application/json' -d '{"handle":"duolingo"}'
```

- Find tools with the quote, or with `GET https://whizbrew.com/v1/tools`. Your balance: `GET https://whizbrew.com/v1/balance?a=7adbfed5ef76`. Where the account stands: `GET https://whizbrew.com/v1/agent`.

## 3. Add money (one request, your human pays)

```sh
curl -s -X POST https://whizbrew.com/v1/agent/topup?a=7adbfed5ef76 -H "Authorization: Bearer $WHIZBREW_API_KEY" \
  -H 'content-type: application/json' -d '{"amount_usd":10}'
# {"status":"waiting_for_payment","checkout_url":"https://...","status_url":"https://whizbrew.com/v1/agent/topup/12?a=7adbfed5ef76","next":"..."}
```

- Between 5 and 500 US dollars a payment (the answer names `min_usd` and `max_usd`).
- Give `checkout_url` to your human, in the words of `next`. It is a hosted card page; you never see the card.
- Poll `status_url` with your key every 5 seconds: `waiting_for_payment`, then `paid` (the balance has risen), or `expired` / `failed` (nothing was charged; make a new link).
- You may add money before the claim. The answer then says in `credit_expires` that the credit stops with an unclaimed account: claim it.
- `503 not_enabled`: card payments are not switched on yet. Nothing was charged. Tell your human, and go on with the credit you have.

## 4. Claim (three small questions)

The claim makes the account your human's for good. It keeps the key you hold and its balance.

1. Ask your human: "Which email should own this Whizbrew account?"

```sh
curl -s -X POST https://whizbrew.com/v1/agent/claim?a=7adbfed5ef76 -H "Authorization: Bearer $WHIZBREW_API_KEY" \
  -H 'content-type: application/json' -d '{"email":"person@example.com"}'
# {"status":"waiting_for_human","claim_url":"https://whizbrew.com/claim#...","confirm_by":"mail_code","how":"...","next":"..."}
```

2. Tell your human: "Open <claim_url> and confirm your email. The page then shows an 8-letter code: read it to me." `confirm_by` says how the page confirms: `mail_code` (we mail them a 6-digit code to type on the page) or `link` (no mail is sent: opening the link in their browser and saying yes is the confirmation, and that browser is signed in).
3. When they give you the code:

```sh
curl -s -X POST https://whizbrew.com/v1/agent/claim?a=7adbfed5ef76 -H "Authorization: Bearer $WHIZBREW_API_KEY" \
  -H 'content-type: application/json' -d '{"code":"ABCD-EFGH"}'
# {"status":"claimed","email":"person@example.com","merged":false,"key":"unchanged","balance_usd":1.0,"next":"..."}
```

- The link lives 30 minutes, the code is used once. A new `{email}` request replaces the link before.
- `claim_not_confirmed`: they have not confirmed on the page yet. `invalid_code`: ask for the code once more (5 tries). `claim_expired` or `too_many_attempts`: make a new link. `sign_in_required`: an account with that email exists and they must sign in to it first.
- An account with that email already exists: your key joins it (`merged: true`) with the money that was paid in; the free credit of your starting account stays behind.

## With MCP

The same four steps are tools of the MCP server at `https://whizbrew.com/mcp` (send the key from step 2 as `Authorization: Bearer <key>`): `get_quote` `{goal, quantity?, budget_usd?}`, `start` `{}` (where the account stands), `add_money` `{amount_usd}` or `{payment_id}` (its status), `claim` `{email}` then `{code}`. Data tools: `search_tools`, `describe_tools`, `call_tool`. Installing the server in a client: https://whizbrew.com/setup.md?a=7adbfed5ef76.

## When something fails

Every error is `{"error":{"kind","message","blame"},"next":"..."}` and nothing was charged. `429` carries `Retry-After`. Do what `next` says; do not guess another route.
