openapi: 3.1.0
info:
  title: Gitcoin Core Bounties Grants API
  version: 0.1.0
  description: Read-only REST API providing access to Gitcoin bounties and grants data. Supports filtering by experience level, project length, bounty type, owner address, open status, and GitHub URL. Returns JSON-formatted data including funding amounts, contributor addresses, token types, and project metadata.
  termsOfService: https://gitcoin.co/terms
  contact:
    name: Gitcoin Support
    url: https://support.gitcoin.co/
  license:
    name: Gitcoin Terms
    url: https://gitcoin.co/terms
servers:
- url: https://gitcoin.co/api/v0.1
  description: Gitcoin API v0.1
tags:
- name: Grants
  description: Operations related to Gitcoin grants
paths:
  /grants/:
    get:
      operationId: listGrants
      summary: List Grants
      description: Returns a list of grants and their metadata including funding amounts, contributor addresses, and project information.
      tags:
      - Grants
      parameters:
      - name: title
        in: query
        description: Filter grants by title
        schema:
          type: string
      - name: admin_address
        in: query
        description: Filter grants by admin Ethereum address
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: description
        in: query
        description: Filter grants by description text
        schema:
          type: string
      - name: keyword
        in: query
        description: Filter grants by keyword
        schema:
          type: string
      - name: grant_type
        in: query
        description: Filter by grant type
        schema:
          type: string
      - name: pk
        in: query
        description: Return a single grant by its primary key ID
        schema:
          type: integer
      - name: limit
        in: query
        description: Limit number of results returned
        schema:
          type: integer
          example: 10
      - name: offset
        in: query
        description: Offset for pagination
        schema:
          type: integer
      responses:
        '200':
          description: A list of grants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Grant'
  /grants/grants.json:
    get:
      operationId: getAllGrants
      summary: Get All Grants
      description: Returns a full list of grants on the platform along with the addresses you can contribute to them at.
      tags:
      - Grants
      responses:
        '200':
          description: A list of all grants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GrantExport'
  /grants/v1/api/export_addresses/{grantId}.json:
    get:
      operationId: getContributorsByGrant
      summary: Get Contributors by Grant
      description: Returns a list of contributor addresses for a specific grant. Requires authentication as a team member of the grant.
      tags:
      - Grants
      parameters:
      - name: grantId
        in: path
        required: true
        description: The grant identifier in format 'grantX' where X is the grant ID
        schema:
          type: string
          pattern: ^grant\d+$
          example: grant12
      security:
      - ApiKeyAuth: []
      - GitHubAuth: []
      responses:
        '200':
          description: A list of contributor addresses for the specified grant
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EthereumAddress'
        '401':
          description: Unauthorized - must be authenticated as a team member
  /grants/v1/api/export_addresses/{grantRoundId}.json:
    get:
      operationId: getContributorsByGrantAndRound
      summary: Get Contributors by Grant and Round
      description: Returns a list of contributor addresses for a specific grant at a specific round. Requires authentication as a team member of the grant.
      tags:
      - Grants
      parameters:
      - name: grantRoundId
        in: path
        required: true
        description: The grant-round identifier in format 'grantX_roundY' where X is the grant ID and Y is the round number
        schema:
          type: string
          pattern: ^grant\d+_round\d+$
          example: grant12_round_7
      security:
      - ApiKeyAuth: []
      - GitHubAuth: []
      responses:
        '200':
          description: A list of contributor addresses for the specified grant at a specific round
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EthereumAddress'
        '401':
          description: Unauthorized - must be authenticated as a team member
  /grants/v1/api/export_info/{grantRoundId}.json:
    get:
      operationId: getContributorInfoByGrantAndRound
      summary: Get Contributor Social Info by Grant and Round
      description: Returns contributor social info (handle, picture, anonymized, comment) for a specific grant at a specific round. Requires authentication as a team member of the grant.
      tags:
      - Grants
      parameters:
      - name: grantRoundId
        in: path
        required: true
        description: The grant-round identifier in format 'grantX_roundY' where X is the grant ID and Y is the round number
        schema:
          type: string
          pattern: ^grant\d+_round\d+$
          example: grant12_round7
      security:
      - ApiKeyAuth: []
      - GitHubAuth: []
      responses:
        '200':
          description: Contributor social information for the specified grant at a specific round
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContributorInfo'
        '401':
          description: Unauthorized - must be authenticated as a team member
components:
  schemas:
    Grant:
      type: object
      description: A Gitcoin grant representing a public goods funding project
      properties:
        active:
          type: boolean
          description: Whether or not the Grant is active
        title:
          type: string
          description: Title of the Grant
        slug:
          type: string
          description: Slug for the Grant populated from title
        description:
          type: string
          description: Description of the Grant
        reference_url:
          type: string
          format: uri
          description: Associated reference URL of the Grant
        logo:
          type: string
          format: uri
          description: URL of the Grant logo image
        admin_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Wallet address of the Grant Admin where subscription funds will be sent
        amount_received:
          type: number
          format: float
          description: Total amount of contributions received by the Grant in USDT/DAI
        token_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Address of the token to be used with the Grant
        token_symbol:
          type: string
          description: Type of token to be used with the Grant
        contract_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Contract address of the Grant
        metadata:
          type: object
          description: Miscellaneous metadata about the Grant
        network:
          type: string
          description: Network in which the Grant contract resides
        required_gas_price:
          type: number
          format: float
          description: Required gas price for the Grant
        admin_profile:
          $ref: '#/components/schemas/Profile'
          description: Grant Admin's profile
        team_members:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
          description: Array of team members contributing to this Grant
    EthereumAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: An Ethereum wallet address with leading 0x
      example: '0x636f3093258412b96c43bef3663f1b853253ec59'
    ContributorInfo:
      type: object
      description: Social information about a grant contributor
      properties:
        handle:
          type: string
          description: GitHub handle of the contributor
        picture:
          type: string
          format: uri
          description: URL to the contributor's profile picture
        anonymized:
          type: boolean
          description: Whether the contributor has chosen to anonymize their data
        comment:
          type: string
          description: Comment left by the contributor
    Profile:
      type: object
      description: Gitcoin user profile
      properties:
        id:
          type: integer
          description: Profile ID
        url:
          type: string
          format: uri
          description: URL to the Gitcoin profile
        handle:
          type: string
          description: GitHub handle/username associated with the Profile
        keywords:
          type: array
          items:
            type: string
          description: Array of keywords associated with the Profile
        position:
          type: integer
          description: Position of the Profile in the Weekly Earners leaderboard
        avatar_url:
          type: string
          format: uri
          description: URL to the Gitcoin Avatar of the Profile
        github_url:
          type: string
          format: uri
          description: URL to the GitHub profile
        total_earned:
          type: number
          format: float
          description: Sum of ETH collected by the profile
        organizations:
          type: object
          description: Dictionary containing profiles that this user works with
    GrantExport:
      type: object
      description: A grant listing from the grants export endpoint
      properties:
        id:
          type: integer
          description: Grant ID
        title:
          type: string
          description: Title of the Grant
        slug:
          type: string
          description: URL slug for the Grant
        description:
          type: string
          description: Description of the Grant
        url:
          type: string
          format: uri
          description: URL to the grant on Gitcoin
        admin_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Wallet address of the Grant Admin
        token_address:
          $ref: '#/components/schemas/EthereumAddress'
          description: Token address for contributions
        token_symbol:
          type: string
          description: Token symbol (e.g., ETH, DAI)
        amount_received:
          type: number
          format: float
          description: Total amount received in USDT/DAI
        active:
          type: boolean
          description: Whether the grant is currently active
externalDocs:
  description: Gitcoin API Documentation
  url: https://docs.gitcoin.co/mk_rest_api/