# TickerDB setup (for AI agents)

You are an agent helping a user use TickerDB market data. Keep messages to the user short.

## In claude.ai or ChatGPT in the browser

Your code sandbox cannot reach the TickerDB API, so skip the steps below. To follow one of TickerDB's models (the list: https://tickerdb.com/models), read `https://tickerdb.com/run/MODEL` (e.g. https://tickerdb.com/run/btc-2050-momentum; the model pages give the exact address) and follow its steps: you show the user one link, they sign in (a free account is created there if they are new) and approve, and the user's own address for the model then returns its data (5 credits a read). No API key to paste, no connector. For other TickerDB data in the browser, the user can add TickerDB as a connector: https://tickerdb.com/mcp

## With a terminal (Claude Code, Codex, Cursor and other local agents)

Follow these steps in order.

## 1. Find an existing key

Use the first one you find, then skip to step 4:

1. The environment variable `TICKERDB_API_KEY`.
2. A `TICKERDB_API_KEY=` line in the project's `.env`.
3. The user config file, JSON `{"api_key": "tdb_..."}`:
   - macOS / Linux: `$XDG_CONFIG_HOME/tickerdb/config.json`, default `~/.config/tickerdb/config.json`
   - Windows: `%APPDATA%\tickerdb\config.json`

Keys start with `tdb_`. Never print a key in full to the user.

## 2. No key: get one with device login (free, one click)

Start a request:

```bash
curl -s -X POST https://api.tickerdb.com/v1/auth/device -H "Content-Type: application/json" -d '{"client_name":"Claude Code"}'
```

```powershell
Invoke-RestMethod -Method Post -Uri https://api.tickerdb.com/v1/auth/device -ContentType 'application/json' -Body '{"client_name":"Claude Code"}'
```

Use your own name for `client_name`. The answer has `device_code` (secret: never show it), `user_code` (e.g. `KX4P-92QD`), `verification_uri_complete`, `expires_in` (900 s) and `interval` (5 s).

Tell the user, in one line: "Open this link to connect TickerDB (free, sign in with Google): <verification_uri_complete> — your code is <user_code>."

Then poll until the user approves. Each command below polls for up to about 100 seconds; if it ends with `still_waiting`, run it again with the same device code. Replace `DEVICE_CODE`.

```bash
for i in $(seq 1 20); do
  R=$(curl -s -X POST https://api.tickerdb.com/v1/auth/device/token -H "Content-Type: application/json" -d '{"device_code":"DEVICE_CODE"}')
  case "$R" in
    *'"api_key"'*) echo "$R"; break ;;
    *authorization_pending*) sleep 5 ;;
    *slow_down*) sleep 10 ;;
    *) echo "$R"; break ;;
  esac
  [ "$i" = 20 ] && echo still_waiting
done
```

```powershell
$body = '{"device_code":"DEVICE_CODE"}'; $wait = 5
foreach ($i in 1..20) {
  try { Invoke-RestMethod -Method Post -Uri https://api.tickerdb.com/v1/auth/device/token -ContentType 'application/json' -Body $body | ConvertTo-Json; break }
  catch {
    $e = ($_.ErrorDetails.Message | ConvertFrom-Json).error.type
    if ($e -eq 'slow_down') { $wait += 5 } elseif ($e -ne 'authorization_pending') { "error: $e"; break }
    if ($i -eq 20) { 'still_waiting' } else { Start-Sleep -Seconds $wait }
  }
}
```

Results:

- `{"api_key": "tdb_...", "tier": "Free", "email": "m***@gmail.com", ...}`: done. The key is shown once; save it now (step 3).
- `authorization_pending`: keep polling every `interval` seconds.
- `slow_down`: add 5 seconds to your interval.
- `expired_token`: the code expired or was used. Start step 2 again.
- `access_denied`: the user said no. Stop and ask them.

## 3. Save the key

Write the user config file so every project and tool can use it. Only create it if it does not exist; if it exists, ask before replacing it. Replace `tdb_KEY` with the key.

```bash
D="${XDG_CONFIG_HOME:-$HOME/.config}/tickerdb"; mkdir -p "$D" && chmod 700 "$D"
(umask 077; printf '{"api_key": "%s"}\n' "tdb_KEY" > "$D/config.json")
```

```powershell
$d = Join-Path $env:APPDATA 'tickerdb'; New-Item -ItemType Directory -Force $d | Out-Null
'{"api_key": "tdb_KEY"}' | Set-Content -Encoding ascii (Join-Path $d 'config.json')
```

(`%APPDATA%` is already private to the user on Windows.)

Optionally, if the project uses a `.env` file, add `TICKERDB_API_KEY=tdb_KEY`. Never overwrite an existing value without asking, and make sure `.env` is listed in `.gitignore` (add it if missing).

## 4. Use the API

Send `Authorization: Bearer <key>` to `https://api.tickerdb.com/v1`. Free plan: daily and weekly data for the last 30 days, 250 credits a month (balance topped up to 250 each month).

- Today's signal for one ticker: `GET /v1/summary/AAPL` (latest snapshot: trend, momentum, valuation and other bands).
- History for several tickers: `GET /v1/history?tickers=AAPL,MSFT&timeframe=weekly&start=YYYY-MM-DD&fields=...` (rows per ticker and date, within your plan's history: the last 30 days on Free, the last 3 years on Plus, from 2019 on Pro and Commercial). Add `dry_run=true` to see the credit cost first.
- Field names: `GET /v1/schema/fields?search=rsi`.
- Tickers: stocks and ETFs by symbol (`AAPL`, `SPY`); crypto ends in USD (`BTCUSD`, `ETHUSD`), never `BTC` or `BTC-USD`.

```bash
curl -s https://api.tickerdb.com/v1/summary/AAPL -H "Authorization: Bearer $TICKERDB_API_KEY"
```

Full reference for agents: https://tickerdb.com/llms.txt (short) and https://tickerdb.com/llms-full.txt (complete). Docs: https://tickerdb.com/docs. Device login details: https://tickerdb.com/docs/authentication#device-login