name: Gitcoin API Plans
description: >-
  Gitcoin's public APIs are generally free to access with no formal pricing
  tiers for the core REST API (bounties, grants). The Gitcoin Passport Stamps
  API uses a tiered rate-limit model requiring an API key from the developer
  portal at developer.passport.xyz. Higher rate-limit tiers can be requested
  via a formal request form.
plans:
  - name: Free (Core API)
    description: >-
      Public read-only access to the Gitcoin Core REST API for bounties and
      grants data. No authentication required for most endpoints. Authenticated
      access to protected grant contributor export endpoints requires API key
      and secret.
    url: https://docs.gitcoin.co/mk_rest_api/
    authentication:
      - type: QueryParameter
        description: >-
          Optional _key and _secret query parameters for protected endpoints.
          Public endpoints require no authentication.
        parameters:
          - name: _key
            in: query
            required: false
          - name: _secret
            in: query
            required: false
    features:
      - Access to bounties endpoint
      - Access to grants endpoint
      - Filtering and ordering support
      - JSON response format
    limitations:
      - Read-only access
      - Some contributor export endpoints require authentication

  - name: Passport Tier 1
    description: >-
      Entry-level access to the Gitcoin Passport Stamps API. All new API key
      registrations begin at Tier 1. Requires free registration at the Gitcoin
      Passport developer portal.
    url: https://developer.passport.xyz
    authentication:
      - type: APIKey
        description: API key in X-API-KEY request header. Obtain from developer.passport.xyz.
        parameters:
          - name: X-API-KEY
            in: header
            required: true
    rateLimit:
      requests: 125
      period: 15 minutes
    features:
      - Score retrieval by scorer ID and address
      - Stamp verification for Ethereum addresses
      - Stamps metadata endpoint
      - Paginated responses
    limitations:
      - 125 requests per 15-minute window
      - 60-second endpoint timeout
      - Scorer ID required alongside API key

  - name: Passport Tier 2
    description: >-
      Elevated access tier for the Gitcoin Passport Stamps API. Requires formal
      request submission to Gitcoin for upgrade from Tier 1.
    url: https://developer.passport.xyz
    authentication:
      - type: APIKey
        description: API key in X-API-KEY request header.
        parameters:
          - name: X-API-KEY
            in: header
            required: true
    rateLimit:
      requests: 350
      period: 15 minutes
    features:
      - All Tier 1 features
      - Higher throughput for production applications
    limitations:
      - 350 requests per 15-minute window
      - 60-second endpoint timeout

  - name: Passport Tier 3
    description: >-
      High-volume access tier for the Gitcoin Passport Stamps API. Intended for
      high-traffic production applications. Requires formal request approval.
    url: https://developer.passport.xyz
    authentication:
      - type: APIKey
        description: API key in X-API-KEY request header.
        parameters:
          - name: X-API-KEY
            in: header
            required: true
    rateLimit:
      requests: 2000
      period: 15 minutes
    features:
      - All Tier 2 features
      - High-volume query support
    limitations:
      - 2000 requests per 15-minute window
      - 60-second endpoint timeout

  - name: Passport Tier 4
    description: >-
      Enterprise-level access tier for the Gitcoin Passport Stamps API with
      custom rate limits exceeding 2000 requests per 15 minutes. Available for
      large-scale applications upon formal request.
    url: https://developer.passport.xyz
    authentication:
      - type: APIKey
        description: API key in X-API-KEY request header.
        parameters:
          - name: X-API-KEY
            in: header
            required: true
    rateLimit:
      requests: 2000+
      period: 15 minutes
    features:
      - All Tier 3 features
      - Custom rate limits above 2000 requests per 15 minutes
      - Enterprise-scale throughput
    limitations:
      - Custom limits negotiated with Gitcoin
      - 60-second endpoint timeout