# GovGreed — Agent Integration Guide

> **For the AI assistant of a GovGreed Founders member** (Claude Code, ChatGPT,
> Cursor, Claude Desktop — all covered below). This file tells you, the agent,
> how to authenticate, which endpoints to call, how to map bills to tickers,
> read committee intelligence, follow best practices, and **send structured
> feedback** to the GovGreed team. Hand this whole file to your assistant.

GovGreed tracks every STOCK Act disclosure in Congress, scores them across a
7-layer signal model, maps bills to the tickers they move, and predicts which
bills pass because the people voting stand to profit.

---

## 1. Authentication & credentials

- **API key:** your `gg_pub_…` key (from your welcome email). Treat it like a password.
- **Tier:** Founders — **750 API calls/day**, **5 requests/sec** burst.
- **Base URL:** `https://www.govgreed.com/api/v1`
- **Auth — send on every request, either header works:**
  - `X-API-Key: gg_pub_…`  **or**
  - `Authorization: Bearer gg_pub_…`
- **Authoritative spec (read this first):** `https://www.govgreed.com/api/v1/openapi.json`
  — standard OpenAPI 3.1. If you can read a URL, read it and generate a typed client.

Sanity check (shows your key + remaining quota):
```bash
curl https://www.govgreed.com/api/v1/me -H "X-API-Key: gg_pub_YOUR_KEY"
```

---

## 2. Connecting from your tool

**Claude Code**
- Simplest: just give Claude the spec — *"Read https://www.govgreed.com/api/v1/openapi.json and build me a typed client; auth is header X-API-Key."*
- Or run the MCP server as a tool:
  ```bash
  claude mcp add govgreed -e GOVGREED_API_KEY=gg_pub_YOUR_KEY -- python /full/path/to/govgreed_mcp.py
  ```
  (deps: `pip install "mcp[cli]>=1.2.0" httpx`). Then the tools below are callable natively.

**ChatGPT**
- Build a **Custom GPT → Actions → Import from URL**: `https://www.govgreed.com/api/v1/openapi.json`.
  Set Authentication = **API Key**, header name **`X-API-Key`**. GPT can then call every endpoint.
- Or have it call the REST endpoints directly with the key in the header.

**Claude Desktop / Cursor (MCP)**
- Download `govgreed_mcp.py` (link in your welcome email), then add to the MCP config:
  ```json
  "govgreed": { "command": "python", "args": ["/full/path/to/govgreed_mcp.py"],
                "env": { "GOVGREED_API_KEY": "gg_pub_YOUR_KEY" } }
  ```
  Restart, then ask *"What GovGreed tools do you have?"*

> **REST vs MCP, one line:** REST = your assistant builds a client against
> endpoints; MCP = your assistant gets the tools natively and you skip the glue.
> Same key, same 750/day either way.

---

## 3. Endpoint catalog

All `GET`, all return `{ "data": …, "meta": { quota, request_id, count, … } }`.
(MCP tool name in parentheses where it differs.)

**Congressional data**
- `/politicians/search?q=` → resolve a name to a `bioguide_id` *(search_politicians)*
- `/politicians/{bioguide_id}/profile` → trades, sectors, style *(politician_profile)*
- `/politicians/{bioguide_id}/donors` → top donors
- `/trades` *(if present in your spec build)* / member trades surface via the profile
- `/signals/top?limit=&min_tier=` → scored trade feed, S/A+/A tiers *(top_signals)*
- `/herd-signals` → 3+ members converging on one ticker *(herd_signals)*
- `/predictions/top` → forward-looking predictions
- `/whale-opportunities` → bills ranked by pass × impact × insider activity *(whale_opportunities)*

**Bill-to-ticker mapping** (see §4)
- `/bills/{bill_number}` → stage, winners/losers, passage odds *(bill_intelligence)*
- `/bills/{n}/carveouts` → line-item → ticker, with confidence *(bill_carveouts)*
- `/bills/{n}/timeline`, `/bills/{n}/pass-likelihood`, `/bills/{n}/votes`
- `/companies/{ticker}/carveouts` → the inverse (which bills touch this ticker)
- `/companies/{ticker}` (+ `/insider-signal`, `/political-influence`, `/contracts`, `/forecast`)

**Committee intelligence** (see §5)
- `/politicians/{bioguide_id}/committees` → who sits where
- `/politicians/{bioguide_id}/conflict-score` → committee-vs-holdings conflict
- `/sectors/{sector}/positioning` → buy/sell pressure by sector

**Account**
- `/me`, `/me/usage` → your key, tier, quota burn

IDs: `bioguide_id` like `P000197` (resolve via search first). `bill_number` like
`HR.1` or `S.1071` (URL-encode the dot if your client needs it).

### Example
```bash
curl "https://www.govgreed.com/api/v1/bills/HR.1/carveouts" -H "X-API-Key: gg_pub_YOUR_KEY"
```
```json
{ "data": [ { "section": "Sec. 112", "ticker": "HII",
              "rationale": "funds Virginia-class submarine procurement",
              "confidence": 0.90 } ],
  "meta": { "request_id": "req_…", "count": 1,
            "quota": { "limit": 750, "remaining": 742, "reset_at": "…T00:00:00Z" } } }
```

---

## 4. Bill-to-ticker mapping (how to read it)

Two complementary tools:
- **`/bills/{n}/carveouts`** — the strongest mapping. Specific bill sections →
  the companies they fund/affect, each with a `confidence` (0–1). Prefer
  carveouts with a cited `section` and `confidence ≥ 0.7`.
- **`/bills/{n}` (`bill_intelligence`)** — `winners`/`losers` ticker arrays with
  narrative reasoning + an LLM `passage_pct`. Good for the thesis; use the
  deterministic `/bills/{n}/pass-likelihood` when you need a model score to act on.
- **`/companies/{ticker}/carveouts`** — the inverse: every bill touching a ticker.

Caveat: topical/ceremonial bills (e.g. a local land/water bill) can surface
spurious ticker matches — sanity-check that a carveout cites a real section.

---

## 5. Committee intelligence

The edge in this data is *committee timing* — members on the committee that
marks up a bill often trade the affected sector first.

- **`/politicians/{id}/committees`** — committee assignments per member.
- **`/whale-opportunities`** — the markup-driven signal: ranks bills by
  passage × ticker impact × insider activity. Markup timing is the trigger.
- **`/bills/{n}/timeline`** — the bill's stage transitions *plus* the trades
  and markups clustered around each stage. This is where you see "committee met,
  then member bought" patterns.
- **`/politicians/{id}/conflict-score`** — flags when a member's committee
  overlaps their holdings.
- **`/sectors/{sector}/positioning`** — aggregate congressional buy/sell
  pressure for a sector, useful as a committee-driven confirmation layer.

---

## 6. Best practices

- **Respect the budget.** 750 calls/day, 5/sec. One complex agent task can fan
  out to 5–15 calls — plan for a few hundred meaningful ops/day. Read
  `meta.quota.remaining` on every response; check `/me/usage` for the trend.
- **Back off on 429.** If you hit the rate limit, exponential backoff (start ~2s).
- **Cache slow-moving data.** Bill text, committee rosters, donor profiles change
  rarely. Signals/predictions refresh **nightly (~23:15 UTC)** — don't poll faster.
- **Resolve IDs once.** Cache the `bioguide_id` for a member instead of searching
  by name every call.
- **Read the envelope.** Errors are RFC-7807 problem+json with a `code` and a
  `request_id`. Always keep `request_id` — it's how the team finds your call in logs.
- **Direction conflicts = no signal.** The signal model and the prediction model
  are independent; if `/signals/top` says BULLISH and `/predictions/top` says
  BEARISH for the same name+ticker, treat it as no clear edge.
- **Format.** Tickers as cashtags (`$NVDA`). `master_score` is 0–100; tiers
  S 75+, A+ 60+, A 50+, B 40+, C 30+.
- **Not financial advice.** This is research data on public disclosures, not a
  recommendation engine. Surface the reasoning, not "buy/sell."

---

## 7. How to send feedback to the GovGreed team

GovGreed is small (two people, **Aaron and Stephen**) and the API + MCP are in
active development. Specific, structured feedback gets acted on fast — **the
team's own AI agents read incoming feedback, triage it, and reply**.

**Protocol:** when your human asks you to report a bug, a wrong result, or a
feature request, produce an email body in this format. Your human pastes it into
an email to **`info@govgreed.com`** (subject prefix `GovGreed feedback:`).

```
Subject: GovGreed feedback: <one-line summary>

USER: <name / account email>
SURFACE: <REST API | MCP | both> · ENDPOINT/TOOL: <e.g. /bills/{n}/carveouts>
SEVERITY: <blocker | wrong-result | annoyance | feature-request>

WHAT I DID:        <exact call(s) — endpoint + params, or MCP tool + args>
EXPECTED:          <what a correct response would look like>
GOT:               <actual response — paste the JSON / relevant fields, trimmed>
WHY IT MATTERS:    <one or two sentences on downstream impact>
REQUEST_ID(s):     <copy meta.request_id from the response>
```

One issue per email keeps the thread clean. Include `request_id` whenever you
have it. They'll read it, fix or update, and reply on the same thread.

---

*Not financial advice. All data from public federal disclosures.*