openapi: 3.1.0
info:
  title: Gitcoin Core Bounties Stamp API 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: Stamp API
paths:
  /v2/stamps/{scorer_id}/score/{address}:
    get:
      operationId: v2_api_api_stamps_a_submit_passport
      summary: Retrieve Stamp-based unique humanity score for a specified address
      parameters:
      - in: path
        name: scorer_id
        schema:
          title: Scorer Id
          type: integer
        required: true
      - in: path
        name: address
        schema:
          title: Address
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ScoreResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
      description: This is the primary endpoint that integrators should use. This endpoint will return the latest score and Stamp data for a single address.<br /><br /><a href="https://docs.passport.xyz/building-with-passport/passport-api-v2/api-reference" target="_blank">Docs</a>
      tags:
      - Stamp API
      security:
      - function: []
  /v2/stamps/{scorer_id}/score/{address}/history:
    get:
      operationId: v2_api_api_stamps_get_score_history
      summary: Retrieve historical Stamp-based unique humanity score for a specified address
      parameters:
      - in: path
        name: scorer_id
        schema:
          title: Scorer Id
          type: integer
        required: true
      - in: path
        name: address
        schema:
          title: Address
          type: string
        required: true
      - in: query
        name: created_at
        schema:
          title: Created At
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ScoreResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ErrorMessageResponse'
                - $ref: '#/components/schemas/NoScoreResponse'
                title: Response
      description: This endpoint will return the historical score and Stamp data for a single address at a specified time. **Note:** To access this endpoint, you must submit your use case and be approved by the Passport team. To do so, please fill out the following form, making sure to provide a detailed description of your use case. The Passport team typically reviews and responds to form responses within 48 hours.<br /><br />[Request access](https://forms.gle/4GyicBfhtHW29eEu8)<br /><br /><a href="https://docs.passport.xyz/building-with-passport/passport-api-v2/api-reference" target="_blank">Docs</a>
      tags:
      - Stamp API
      security:
      - ApiKey: []
  /v2/stamps/metadata:
    get:
      operationId: v2_api_api_stamps_stamp_display
      summary: Receive all Stamps available in Passport
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/StampDisplayResponse'
                title: Response
                type: array
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
      description: <a href="https://docs.passport.xyz/building-with-passport/passport-api-v2/api-reference" target="_blank">Docs</a>
      tags:
      - Stamp API
      security:
      - ApiKey: []
  /v2/stamps/{address}:
    get:
      operationId: v2_api_api_stamps_get_passport_stamps
      summary: Retrieve the Stamps that a specified account has verified.
      parameters:
      - in: path
        name: address
        schema:
          title: Address
          type: string
        required: true
      - in: query
        name: token
        schema:
          default: ''
          title: Token
          type: string
        required: false
      - in: query
        name: limit
        schema:
          default: 1000
          title: Limit
          type: integer
        required: false
      - in: query
        name: include_metadata
        schema:
          default: false
          title: Include Metadata
          type: boolean
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPaginatedStampCredentialResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageResponse'
      description: Use this endpoint to retrieve the Stamps verified by a specified address.<br /><br />This endpoint will return a `CursorPaginatedStampCredentialResponse`.<br /><br /><a href="https://docs.passport.xyz/building-with-passport/passport-api-v2/api-reference" target="_blank">Docs</a>
      tags:
      - Stamp API
      security:
      - ApiKey: []
components:
  schemas:
    V2ScoreResponse:
      properties:
        address:
          title: Address
          type: string
        score:
          anyOf:
          - type: number
          - type: string
          - type: 'null'
          title: Score
        passing_score:
          title: Passing Score
          type: boolean
        last_score_timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Score Timestamp
        expiration_timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiration Timestamp
        threshold:
          anyOf:
          - type: number
          - type: string
          title: Threshold
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        stamps:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/V2StampScoreResponse'
            type: object
          - type: 'null'
          title: Stamps
        points_data:
          anyOf:
          - $ref: '#/components/schemas/PointsData'
          - type: 'null'
        possible_points_data:
          anyOf:
          - $ref: '#/components/schemas/PointsData'
          - type: 'null'
        linked_score:
          anyOf:
          - $ref: '#/components/schemas/LinkedScoreResponse'
          - type: 'null'
      required:
      - address
      - score
      - passing_score
      - last_score_timestamp
      - expiration_timestamp
      - threshold
      - error
      - stamps
      title: V2ScoreResponse
      type: object
    NoScoreResponse:
      properties:
        address:
          title: Address
          type: string
        status:
          title: Status
          type: string
      required:
      - address
      - status
      title: NoScoreResponse
      type: object
    V2StampScoreResponse:
      properties:
        score:
          title: Score
          type: string
        dedup:
          title: Dedup
          type: boolean
        expiration_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiration Date
        source_wallet:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Wallet
      required:
      - score
      - dedup
      - expiration_date
      title: V2StampScoreResponse
      type: object
    PointsData:
      properties:
        total_points:
          title: Total Points
          type: integer
        is_eligible:
          title: Is Eligible
          type: boolean
        multiplier:
          title: Multiplier
          type: integer
        breakdown:
          additionalProperties:
            type: integer
          title: Breakdown
          type: object
      required:
      - total_points
      - is_eligible
      - multiplier
      - breakdown
      title: PointsData
      type: object
    StampDisplayResponseGroup:
      properties:
        name:
          title: Name
          type: string
        stamps:
          items:
            $ref: '#/components/schemas/StampDisplayResponseStamp'
          title: Stamps
          type: array
      required:
      - name
      - stamps
      title: StampDisplayResponseGroup
      type: object
    ErrorMessageResponse:
      properties:
        detail:
          title: Detail
          type: string
      required:
      - detail
      title: ErrorMessageResponse
      type: object
    StampDisplayResponse:
      properties:
        id:
          title: Id
          type: string
        icon:
          title: Icon
          type: string
        name:
          title: Name
          type: string
        description:
          title: Description
          type: string
        connectMessage:
          title: Connectmessage
          type: string
        groups:
          items:
            $ref: '#/components/schemas/StampDisplayResponseGroup'
          title: Groups
          type: array
      required:
      - id
      - icon
      - name
      - description
      - connectMessage
      - groups
      title: StampDisplayResponse
      type: object
    LinkedScoreResponse:
      description: Score data from the canonical wallet in a linked wallet group.
      properties:
        address:
          title: Address
          type: string
        score:
          anyOf:
          - type: number
          - type: string
          - type: 'null'
          title: Score
        passing_score:
          title: Passing Score
          type: boolean
        last_score_timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Score Timestamp
        expiration_timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiration Timestamp
        threshold:
          anyOf:
          - type: number
          - type: string
          title: Threshold
        stamps:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/V2StampScoreResponse'
            type: object
          - type: 'null'
          title: Stamps
        wallet_stamps:
          anyOf:
          - additionalProperties:
              additionalProperties:
                $ref: '#/components/schemas/V2StampScoreResponse'
              type: object
            type: object
          - type: 'null'
          title: Wallet Stamps
      required:
      - address
      - score
      - passing_score
      - last_score_timestamp
      - expiration_timestamp
      - threshold
      - stamps
      title: LinkedScoreResponse
      type: object
    CursorPaginatedStampCredentialResponse:
      properties:
        next:
          anyOf:
          - type: string
          - type: 'null'
          title: Next
        prev:
          anyOf:
          - type: string
          - type: 'null'
          title: Prev
        items:
          items:
            $ref: '#/components/schemas/StampCredentialResponse'
          title: Items
          type: array
      required:
      - next
      - prev
      - items
      title: CursorPaginatedStampCredentialResponse
      type: object
    StampCredentialResponseMetadataForPlatform:
      properties:
        id:
          title: Id
          type: string
        icon:
          title: Icon
          type: string
        name:
          title: Name
          type: string
        description:
          title: Description
          type: string
        connectMessage:
          title: Connectmessage
          type: string
      required:
      - id
      - icon
      - name
      - description
      - connectMessage
      title: StampCredentialResponseMetadataForPlatform
      type: object
    StampCredentialResponseMetadata:
      properties:
        group:
          title: Group
          type: string
        platform:
          $ref: '#/components/schemas/StampCredentialResponseMetadataForPlatform'
        name:
          title: Name
          type: string
        description:
          title: Description
          type: string
        hash:
          title: Hash
          type: string
      required:
      - group
      - platform
      - name
      - description
      - hash
      title: StampCredentialResponseMetadata
      type: object
    StampCredentialResponse:
      properties:
        version:
          title: Version
          type: string
        credential:
          title: Credential
          type: object
        metadata:
          anyOf:
          - $ref: '#/components/schemas/StampCredentialResponseMetadata'
          - type: 'null'
      required:
      - version
      - credential
      title: StampCredentialResponse
      type: object
    StampDisplayResponseStamp:
      properties:
        name:
          title: Name
          type: string
        description:
          title: Description
          type: string
        hash:
          title: Hash
          type: string
      required:
      - name
      - description
      - hash
      title: StampDisplayResponseStamp
      type: object
externalDocs:
  description: Gitcoin API Documentation
  url: https://docs.gitcoin.co/mk_rest_api/