# gitBeacon API — GitHub trend intelligence for AI agents on x402 — daily LLM-analyzed digests of trending new repos plus the raw trending-repo data. Per-call, no signup. (v1.0.0)

> gitBeacon is a pay-per-call GitHub trend intelligence API for AI agents. A daily scan of trending new GitHub repos is LLM-analyzed into a structured digest, and the raw trending-repo rows are served behind a paid endpoint. Every digest feed is free to poll (/v1/index, /v1/brief, /v1/digests/latest) and a frozen /v1/sample shows the response shape before you pay; the two paid endpoints (top repos, historical digests) settle per call via x402 (USDC on Base). Try the free /v1/sample or /v1/digests/latest to learn the shape before paying.

## Base URL
- API: https://api.gitbeacon.dev
- This document: https://api.gitbeacon.dev/llms.txt  ·  Extended: https://api.gitbeacon.dev/llms-full.txt
- Discovery (JSON): https://api.gitbeacon.dev/discovery
- OpenAPI 3.1: https://api.gitbeacon.dev/openapi.json
- 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

## Free endpoints (no auth, no payment)

| Method | Path | Description |
|--------|------|-------------|
| 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) |

## Paid endpoints (x402 V2, USDC on Base, per-call)

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| 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. |

## How to pay (x402)
Each paid call answers a 402 challenge; sign an x402 `exact` USDC authorization for one advertised rail (Base) and retry. Standard @x402 V2 clients send the `PAYMENT-SIGNATURE` header; legacy clients send `X-PAYMENT`. Prices are USD, settled as USDC (6 decimals).

## 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
- Website: https://gitbeacon.dev

## What gitBeacon covers
gitBeacon watches new repositories that trend on GitHub each day. The daily scan enriches each candidate repo (stars, forks, language, topics, license, author followers, README excerpt) and an LLM synthesizes the day into a digest: the dominant categories of work, emerging tools and frameworks, language-popularity trends, the most notable projects, and an overall sentiment. The paid /v1/repos endpoint returns the raw enriched repo rows from the latest scan (filterable by language); the paid /v1/digests endpoint returns the historical digests so you can track how open-source trends evolve over time.

## Free funnel & honesty
/v1/sample is a FROZEN sample digest (captured from the 2026-02-13 scan) — it never changes and is labelled as such, so it is safe for testing without implying live data. /v1/brief, /v1/index, and /v1/digests/latest are live, rate-limited reads of the current digest. The paid endpoints carry scanDate/digestDate provenance so you always know how fresh the data is.