# gitBeacon API

gitBeacon — GitHub trend intelligence for AI agents. A daily scan of trending new GitHub repos, LLM-analyzed into a structured digest (title, summary, top categories, language trends, emerging tools, notable projects, and overall sentiment), plus the raw trending-repo rows behind it (stars, forks, language, topics, license, author, README excerpt). Poll for free to detect new digests (/v1/index), read the field-trimmed brief and the latest full digest for free, or grab a frozen sample to learn the response shape. Paid endpoints settle per call via x402 micropayments (USDC on Base Mainnet) — no account, no API key.

- **Base URL**: https://api.gitbeacon.dev
- **Docs (agent-facing)**: https://api.gitbeacon.dev/llms.txt · https://api.gitbeacon.dev/llms-full.txt
- **OpenAPI 3.1**: https://api.gitbeacon.dev/openapi.json
- **Discovery (JSON)**: https://api.gitbeacon.dev/discovery
- **x402 manifest**: https://api.gitbeacon.dev/.well-known/x402
- **Agent card (A2A)**: https://api.gitbeacon.dev/.well-known/agent-card.json
- **Terms**: https://api.gitbeacon.dev/terms.txt

GitHub trend intelligence aggregated from public GitHub data — informational, provided as-is,
not investment or engineering advice.

## Free (no auth, no payment)

| Method | Path | What |
|--------|------|------|
| GET | /health | Liveness + payment mode |
| GET | /v1/brief | Free (rate-limited 10/min per IP). Field-trimmed snapshot of the current daily GitHub digest — title, summary, top categories, language trends, overall sentiment, and digestDate. Full digest at GET /v1/digests/latest (free). (rate limit: 10/min) |
| GET | /v1/index | Free (rate-limited 10/min per IP). Poll target — returns the current digest id, digestDate, and updatedAt plus the nextExpected time (24h cadence), so agents detect new digests without paying. (rate limit: 10/min) |
| GET | /v1/sample | Free (rate-limited 5/min per IP). A FROZEN sample digest captured from the 2026-02-13 scan — the same shape as a real digest, but it never changes. Use it to learn the response contract before paying. (rate limit: 5/min) |
| GET | /v1/digests/latest | Free (rate-limited 5/min per IP). The most recent completed daily GitHub digest with full fields: fullAnalysis, notableProjects, emergingTools, language trends, and volume metrics. (rate limit: 5/min) |
| GET | /terms.txt · /terms.json | Terms of Service |

## Paid (x402 V2 — USDC on eip155:8453, per-call)

| Method | Path | Price | What |
|--------|------|-------|------|
| GET | /v1/repos | $0.01 | Paid ($0.01 USDC via x402). Top trending GitHub repos from the latest daily scan, sorted by stars — description, language, topics, license, forks, author followers, and README excerpt. Filterable by programming language. Response carries the scanDate provenance. Compute-first / settle-after — you are never charged for an error. |
| GET | /v1/digests | $0.05 | Paid ($0.05 USDC via x402). Historical daily GitHub digests (1-30 day lookback). Track how open-source trends, language popularity, and emerging tools evolve over time — each digest carries the same rich analysis as /v1/digests/latest, keyed by digestDate provenance. Compute-first / settle-after — you are never charged for an error. |

Prices are USD, settled as USDC (6 decimals). Compute-first / settle-after: you are never
charged for errors.

## Quickstart — pay per call (x402, USDC)

```
# 1) Call a paid route with no payment → 402 challenge
curl -s "https://api.gitbeacon.dev/v1/repos"
# → { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "USDC",
#     "price": "$0.01", "payTo": "0x…" } ], "terms": "https://api.gitbeacon.dev/terms.txt" }

# 2) Sign an x402 'exact' USDC authorization for one accepts[] rail, then retry.
#    Standard @x402 V2 clients send PAYMENT-SIGNATURE; legacy clients send X-PAYMENT.
curl -s "https://api.gitbeacon.dev/v1/repos?limit=10" -H "PAYMENT-SIGNATURE: <payload>"
# → 200 { …, "charged": true }
```

## Links
- Docs: https://api.gitbeacon.dev/llms.txt
- Full: https://api.gitbeacon.dev/llms-full.txt
- OpenAPI: https://api.gitbeacon.dev/openapi.json
- Discovery: https://api.gitbeacon.dev/discovery
- Agent card: https://api.gitbeacon.dev/.well-known/agent-card.json