> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.vcm.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# List carbon credit buyers

> Get aggregated buyer statistics derived from retirement transaction data.

    Buyer names are harmonized across registries — the same entity appearing under
    different names is resolved to a canonical name where possible.

    **How it works:** Aggregates all retirement transactions by buyer, computing
    volume metrics, transaction counts, and activity flags. Project and credit
    filters are applied *before* aggregation; buyer-specific filters (volume ranges,
    activity flags) are applied *after*.

    **Key metrics per buyer:**
    - `total_volume` / `volume_12m` / `volume_60d` — retired credit quantities
    - `total_transactions` / `transactions_12m` / `transactions_60d` — transaction counts
    - `avg_transaction_size` — average credits per retirement
    - `is_active_12m` / `is_active_60d` — activity flags
    - `first_purchase` / `last_purchase` / `days_since_last` — temporal data

    **Sorting:** Available fields: `total_volume`, `volume_12m`, `volume_60d`,
    `avg_transaction_size`, `total_transactions`, `transactions_12m`, `transactions_60d`,
    `first_purchase`, `last_purchase`. Prefix with `-` for descending.

    **Example queries:**
    - Buyers of forest credits in Brazil: `?category=forest&country=Brazil`
    - Active buyers (last 60 days): `?is_active_60d=true`
    - High-volume buyers: `?total_volume_min=100000`



## OpenAPI

````yaml https://api.vcm.fyi/v1/openapi.json get /v1/buyers/
openapi: 3.1.0
info:
  title: VCM.fyi API
  version: 1.0.0
  description: >

    # VCM.fyi API


    Programmatic access to carbon market intelligence — covering

    11,000+ carbon credit projects across 6 major registries (Verra, Gold
    Standard,

    CAR, ACR, Isometric, Puro Earth).


    ## Resources


    | Resource | Description |

    |---|---|

    | **Projects** | Search, filter, and retrieve carbon credit project metadata
    |

    | **Credits** | Individual credit transactions (issuances, retirements,
    cancellations) |

    | **Buyers** | Aggregated buyer intelligence from retirement transaction
    data |

    | **Charts** | Pre-aggregated chart data for visualizations |

    | **Countries** | Country-level carbon market policy intelligence (Article
    6, CORSIA, carbon pricing) |

    | **Forensics** | AI-generated project risk analysis from weekly news
    scanning |

    | **Proponent Forensics** | Developer/proponent-level risk ratings and due
    diligence |

    | **Satellite** | Forest integrity and deforestation metrics |

    | **Supply & Demand** | Aggregated issuance vs. retirement volumes over time
    |

    | **API Keys** | Manage your API keys and view usage statistics |


    ## Authentication


    All endpoints require an API key passed in the `X-API-KEY` header:


    ```bash

    curl -H "X-API-KEY: vcm_live_your_key_here" https://api.vcm.fyi/v1/projects/

    ```


    Get your API key at
    [app.vcm.fyi/settings/api](https://app.vcm.fyi/settings/api).


    ## Rate Limits


    | Plan | Requests/min | Monthly Calls |

    |------|-------------|---------------|

    | Pro | 300 | 100,000 |

    | Enterprise | 1,000 | Unlimited |


    Rate limit headers are included in every response:

    - `X-RateLimit-Limit` — Your limit per minute

    - `X-RateLimit-Remaining` — Remaining requests in current window

    - `X-RateLimit-Reset` — Unix timestamp when the window resets


    ## Pagination


    List endpoints return paginated results:


    ```json

    {
      "pagination": {
        "total_entries": 11234,
        "current_page": 1,
        "total_pages": 113,
        "next_page": "/v1/projects/?current_page=2&per_page=100"
      },
      "data": [...]
    }

    ```
  contact:
    name: VCM.fyi Support
    email: support@vcm.fyi
    url: https://vcm.fyi
  termsOfService: https://vcm.fyi/terms
  x-logo:
    url: https://app.vcm.fyi/logo.svg
    altText: VCM.fyi
servers:
  - url: https://vcm-fyi-api.fly.dev
    description: Production
security: []
tags:
  - name: API Keys
    description: Create, list, revoke your API keys and view usage statistics.
  - name: Buyers
    description: >-
      Aggregated buyer intelligence derived from retirement transactions.
      Includes volume metrics, activity flags, category/country breakdowns, and
      analytics.
  - name: Charts
    description: >-
      Pre-aggregated chart data for visualizations: projects by listing date,
      credits by transaction date, category breakdowns, credit histograms, and
      top buyers.
  - name: Countries
    description: >-
      Country-level carbon market policy intelligence covering Article 6 status,
      CORSIA eligibility, carbon pricing, VCM regulation, and AI-generated
      policy summaries.
  - name: Credits
    description: >-
      Query individual credit transactions — issuances, retirements, and
      cancellations — with quantity, vintage, date, and beneficiary details.
  - name: Forensics
    description: >-
      AI-generated project risk analysis from weekly scanning of 100+ news
      sources. Includes entries, memos, weekly diffs, and legacy v1 endpoints.
  - name: Projects
    description: >-
      Search, filter, and retrieve metadata for 11,000+ carbon credit projects
      across Verra, Gold Standard, CAR, ACR, Isometric, and Puro Earth.
  - name: Proponent Forensics
    description: >-
      Developer/proponent-level risk ratings and due diligence analysis with
      governance, financial, legal, social, and institutional risk pillar
      scores.
  - name: Satellite
    description: >-
      Forest integrity and deforestation metrics from Global Forest Watch,
      including tree cover loss, GLAD alerts, fire alerts, and project boundary
      GeoJSON.
  - name: Supply & Demand
    description: >-
      Aggregated issuance (supply) vs. retirement (demand) volumes over time,
      with monthly, quarterly, or yearly aggregation.
paths:
  /v1/buyers/:
    get:
      tags:
        - Buyers
      summary: List carbon credit buyers
      description: >-
        Get aggregated buyer statistics derived from retirement transaction
        data.

            Buyer names are harmonized across registries — the same entity appearing under
            different names is resolved to a canonical name where possible.

            **How it works:** Aggregates all retirement transactions by buyer, computing
            volume metrics, transaction counts, and activity flags. Project and credit
            filters are applied *before* aggregation; buyer-specific filters (volume ranges,
            activity flags) are applied *after*.

            **Key metrics per buyer:**
            - `total_volume` / `volume_12m` / `volume_60d` — retired credit quantities
            - `total_transactions` / `transactions_12m` / `transactions_60d` — transaction counts
            - `avg_transaction_size` — average credits per retirement
            - `is_active_12m` / `is_active_60d` — activity flags
            - `first_purchase` / `last_purchase` / `days_since_last` — temporal data

            **Sorting:** Available fields: `total_volume`, `volume_12m`, `volume_60d`,
            `avg_transaction_size`, `total_transactions`, `transactions_12m`, `transactions_60d`,
            `first_purchase`, `last_purchase`. Prefix with `-` for descending.

            **Example queries:**
            - Buyers of forest credits in Brazil: `?category=forest&country=Brazil`
            - Active buyers (last 60 days): `?is_active_60d=true`
            - High-volume buyers: `?total_volume_min=100000`
      operationId: get_buyers_v1_buyers__get
      parameters:
        - name: project_id
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter by specific project ID(s)
            title: Project Id
          description: Filter by specific project ID(s)
        - name: current_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number
            default: 1
            title: Current Page
          description: Page number
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Items per page
            default: 100
            title: Per Page
          description: Items per page
        - name: sort
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            description: >-
              List of sorting parameters. Available: total_volume, volume_12m,
              volume_60d, avg_transaction_size, total_transactions,
              transactions_12m, transactions_60d, transactions_per_year,
              first_purchase, last_purchase, days_since_last. Prefix with - for
              descending.
            default:
              - '-total_volume'
            title: Sort
          description: >-
            List of sorting parameters. Available: total_volume, volume_12m,
            volume_60d, avg_transaction_size, total_transactions,
            transactions_12m, transactions_60d, transactions_per_year,
            first_purchase, last_purchase, days_since_last. Prefix with - for
            descending.
        - name: registry
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  enum:
                    - verra
                    - gold-standard
                    - american-carbon-registry
                    - climate-action-reserve
                    - art-trees
                    - isometric
                    - puro-earth
                    - plan-vivo
                    - none
                  type: string
              - type: 'null'
            description: Registry name
            title: Registry
          description: Registry name
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Country name
            title: Country
          description: Country name
        - name: protocol
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Protocol name
            title: Protocol
          description: Protocol name
        - name: category
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Category name
            title: Category
          description: Category name
        - name: is_compliance
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Whether project is an ARB project
            title: Is Compliance
          description: Whether project is an ARB project
        - name: listed_at_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
              - type: 'null'
            description: 'Format: YYYY-MM-DD'
            title: Listed At From
          description: 'Format: YYYY-MM-DD'
        - name: listed_at_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
              - type: 'null'
            description: 'Format: YYYY-MM-DD'
            title: Listed At To
          description: 'Format: YYYY-MM-DD'
        - name: issued_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum number of issued credits
            title: Issued Min
          description: Minimum number of issued credits
        - name: issued_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum number of issued credits
            title: Issued Max
          description: Maximum number of issued credits
        - name: retired_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum number of retired credits
            title: Retired Min
          description: Minimum number of retired credits
        - name: retired_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum number of retired credits
            title: Retired Max
          description: Maximum number of retired credits
        - name: project_type
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: 'Project type '
            title: Project Type
          description: 'Project type '
        - name: proponent
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Project proponent/developer name
            title: Proponent
          description: Project proponent/developer name
        - name: sdg_goals
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: integer
                type: array
              - type: 'null'
            description: >-
              UN SDG goals (1-17). Multiple values = AND filter (must have ALL
              selected goals)
            title: Sdg Goals
          description: >-
            UN SDG goals (1-17). Multiple values = AND filter (must have ALL
            selected goals)
        - name: certifications
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Specific certification labels (e.g., ccb-gold,
              ccb-biodiversity-gold, corsia). Multiple values = OR filter
            title: Certifications
          description: >-
            Specific certification labels (e.g., ccb-gold,
            ccb-biodiversity-gold, corsia). Multiple values = OR filter
        - name: corc_durability
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Puro.earth CORC durability (100+ or 1000+). Multiple values = OR
              filter
            title: Corc Durability
          description: >-
            Puro.earth CORC durability (100+ or 1000+). Multiple values = OR
            filter
        - name: has_ccb
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Ccb
            description: Has CCB (Climate, Community & Biodiversity) certification
          description: Has CCB (Climate, Community & Biodiversity) certification
        - name: has_icvcm_ccp
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Icvcm Ccp
            description: Has ICVCM Core Carbon Principles certification
          description: Has ICVCM Core Carbon Principles certification
        - name: has_corsia
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Corsia
            description: CORSIA eligible
          description: CORSIA eligible
        - name: has_sdvista
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Sdvista
            description: Has SD VISta certification
          description: Has SD VISta certification
        - name: has_social_carbon
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Social Carbon
            description: Has Social Carbon certification
          description: Has Social Carbon certification
        - name: article6_authorized
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Article6 Authorized
            description: Authorized under Paris Agreement Article 6
          description: Authorized under Paris Agreement Article 6
        - name: article6_authorization_types
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Article 6 authorization types: NDC Use, Intl mitigation purposes,
              Other purposes
            title: Article6 Authorization Types
          description: >-
            Article 6 authorization types: NDC Use, Intl mitigation purposes,
            Other purposes
        - name: transaction_type
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Transaction type
            title: Transaction Type
          description: Transaction type
        - name: vintage
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: integer
                type: array
              - type: 'null'
            description: Vintage
            title: Vintage
          description: Vintage
        - name: transaction_date_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
              - type: 'null'
            description: 'Format: YYYY-MM-DD'
            title: Transaction Date From
          description: 'Format: YYYY-MM-DD'
        - name: transaction_date_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
              - type: 'null'
            description: 'Format: YYYY-MM-DD'
            title: Transaction Date To
          description: 'Format: YYYY-MM-DD'
        - name: quantity_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum transaction quantity
            title: Quantity Min
          description: Minimum transaction quantity
        - name: quantity_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum transaction quantity
            title: Quantity Max
          description: Maximum transaction quantity
        - name: buyer_search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Search buyer name (case insensitive)
            title: Buyer Search
          description: Search buyer name (case insensitive)
        - name: total_volume_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum total volume of credits purchased
            title: Total Volume Min
          description: Minimum total volume of credits purchased
        - name: total_volume_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum total volume of credits purchased
            title: Total Volume Max
          description: Maximum total volume of credits purchased
        - name: volume_12m_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum volume purchased in last 12 months
            title: Volume 12M Min
          description: Minimum volume purchased in last 12 months
        - name: volume_12m_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum volume purchased in last 12 months
            title: Volume 12M Max
          description: Maximum volume purchased in last 12 months
        - name: avg_transaction_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum average transaction size
            title: Avg Transaction Min
          description: Minimum average transaction size
        - name: avg_transaction_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum average transaction size
            title: Avg Transaction Max
          description: Maximum average transaction size
        - name: transaction_count_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum number of transactions
            title: Transaction Count Min
          description: Minimum number of transactions
        - name: transaction_count_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum number of transactions
            title: Transaction Count Max
          description: Maximum number of transactions
        - name: is_active_12m
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Filter for buyers active in last 12 months
            title: Is Active 12M
          description: Filter for buyers active in last 12 months
        - name: is_active_60d
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Filter for buyers active in last 60 days
            title: Is Active 60D
          description: Filter for buyers active in last 60 days
      responses:
        '200':
          description: Paginated list of buyers with aggregated retirement statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBuyers'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    PaginatedBuyers:
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          anyOf:
            - items:
                $ref: '#/components/schemas/BuyerStats'
              type: array
            - items:
                additionalProperties: true
                type: object
              type: array
          title: Data
      type: object
      required:
        - pagination
        - data
      title: PaginatedBuyers
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Pagination:
      properties:
        total_entries:
          type: integer
          title: Total Entries
        current_page:
          type: integer
          title: Current Page
        total_pages:
          type: integer
          title: Total Pages
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
      type: object
      required:
        - total_entries
        - current_page
        - total_pages
      title: Pagination
    BuyerStats:
      properties:
        buyer_name:
          type: string
          title: Buyer Name
        total_volume:
          type: integer
          title: Total Volume
        volume_12m:
          type: integer
          title: Volume 12M
        volume_60d:
          type: integer
          title: Volume 60D
        avg_transaction_size:
          type: integer
          title: Avg Transaction Size
        total_transactions:
          type: integer
          title: Total Transactions
        transactions_12m:
          type: integer
          title: Transactions 12M
        transactions_60d:
          type: integer
          title: Transactions 60D
        transactions_per_year:
          type: number
          title: Transactions Per Year
        first_purchase:
          type: string
          format: date
          title: First Purchase
        last_purchase:
          type: string
          format: date
          title: Last Purchase
        days_since_last:
          type: integer
          title: Days Since Last
        top_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Top Category
        top_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Top Country
        top_registry:
          anyOf:
            - type: string
            - type: 'null'
          title: Top Registry
        is_active_12m:
          type: boolean
          title: Is Active 12M
        is_active_60d:
          type: boolean
          title: Is Active 60D
      type: object
      required:
        - buyer_name
        - total_volume
        - volume_12m
        - volume_60d
        - avg_transaction_size
        - total_transactions
        - transactions_12m
        - transactions_60d
        - transactions_per_year
        - first_purchase
        - last_purchase
        - days_since_last
        - top_category
        - top_country
        - top_registry
        - is_active_12m
        - is_active_60d
      title: BuyerStats
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY

````