# VCM.fyi API

> Carbon market intelligence API — programmatic access to 11,000+ carbon credit projects across 6 registries.

## Base URL

https://api.vcm.fyi/v1

## Authentication

All requests require an API key in the X-API-KEY header.
API access requires a Pro or Enterprise plan.
Keys are generated at https://app.vcm.fyi/settings/api

## Endpoints

### Projects
- GET /v1/projects/ — Search and filter carbon credit projects. Params: registry, country, category, protocol, status, search, is_compliance, current_page, per_page, sort.
- GET /v1/projects/{project_id} — Get a single project by ID (e.g. VCS-1396, GS-1234, CAR-123).
- GET /v1/projects/types — List all project type values.

### Credits
- GET /v1/credits/ — Query credit transactions (issuances, retirements, cancellations). Params: project_id, transaction_type, vintage, country, current_page, per_page, sort.

### Buyers
- GET /v1/buyers/ — List buyers with retirement volumes and activity metrics. Params: search, current_page, per_page, sort.
- GET /v1/buyers/{buyer_name} — Get a specific buyer profile.
- GET /v1/buyers/{buyer_name}/analytics — Get buyer analytics (category breakdown, country breakdown, activity timeline).

### Charts
- GET /v1/charts/projects_by_listing_date — Projects binned by listing date.
- GET /v1/charts/credits_by_transaction_date — Credits binned by transaction date.
- GET /v1/charts/credits_by_transaction_date/{project_id} — Credits for a specific project by date.
- GET /v1/charts/credits_issuances_by_vintage/{project_id} — Issuances by vintage for a project.
- GET /v1/charts/credits_retirements_by_vintage/{project_id} — Retirements by vintage for a project.
- GET /v1/charts/projects_by_credit_totals — Projects binned by credit totals.
- GET /v1/charts/projects_by_category — Projects grouped by category.
- GET /v1/charts/credits_by_category — Credits grouped by category.
- GET /v1/charts/top_buyers — Top buyers by retirement volume.

### Forensics (AI Risk Analysis)
- GET /v1/forensics/v2/latest — Latest AI-generated risk entries across all projects.
- GET /v1/forensics/v2/{project_id} — Risk analysis for a specific project.
- GET /v1/forensics/v2/{project_id}/entries — Individual risk entries for a project.
- GET /v1/forensics/v2/{project_id}/diff — Weekly diff of changes for a project.

### Proponent Forensics
- GET /v1/proponent-forensics/ — List all proponent risk assessments.
- GET /v1/proponent-forensics/by-proponent/{proponent_key} — Risk data for a specific proponent/developer.
- GET /v1/proponent-forensics/by-project/{project_id} — Proponent risk data linked to a project.

### Countries
- GET /v1/countries/ — List all countries with carbon market policy data.
- GET /v1/countries/{country_code} — Get a country's policy profile (Article 6, CORSIA, carbon pricing, VCM regulation).
- GET /v1/countries/{country_code}/updates — Get policy update history for a country.
- GET /v1/countries/stats/summary — Aggregated statistics across all countries.

### Satellite
- GET /v1/satellite/{project_id} — Forest integrity metrics (tree cover loss, GLAD alerts, fire alerts).
- GET /v1/satellite/{project_id}/boundary — Project boundary GeoJSON.
- GET /v1/satellite/ — List all projects with satellite data.

### Supply & Demand
- GET /v1/supply-demand/ — Aggregated issuance vs. retirement volumes over time.

### API Keys
- GET /v1/api-keys/ — List your active API keys.
- POST /v1/api-keys/ — Create a new API key.
- DELETE /v1/api-keys/{key_id} — Revoke an API key.
- GET /v1/api-keys/usage — View your API usage statistics.

## Pagination

List endpoints return: { "pagination": { "total_entries", "current_page", "total_pages", "next_page" }, "data": [...] }
Use current_page and per_page (max 200) query parameters.

## Rate Limits

Pro: 300 requests/min, 100,000/month.
Enterprise: 1,000 requests/min, unlimited monthly.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

## Documentation

Full API reference: https://docs.api.vcm.fyi
Support: support@vcm.fyi