Superform Protocol API

openapi: 3.1.0
info:
  title: Superform Auxiliary Protocol API
  version: 1.0.0
servers:
- url: https://api.superform.xyz
tags:
- name: Protocol
paths:
  /protocol/{id}:
    get:
      description: Get one protocol by ID
      operationId: get-protocol
      parameters:
      - description: Protocol ID to return stats for
        example: 20ea4lMXEYCmpAhjuLKuD
        in: path
        name: id
        required: true
        schema:
          description: Protocol ID to return stats for
          examples:
          - 20ea4lMXEYCmpAhjuLKuD
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Protocol'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Get protocol by ID
      tags:
      - Protocol
  /protocol/{id}/stats:
    get:
      description: Get historical stats for a protocol, comprising all of its vaults. If no parameters are passed, response will span the full range of available data.If a timestamp is passed, the data will be for that point in time. If a start and end timestamp are passed, the data will be for that range.
      operationId: protocol-stats
      parameters:
      - description: Unix timestamp for the start of the time series data
        example: 1726225932
        explode: false
        in: query
        name: start_timestamp
        schema:
          description: Unix timestamp for the start of the time series data
          examples:
          - 1726225932
          format: int64
          type: integer
      - description: Unix timestamp for the end of the time series data
        example: 1729225932
        explode: false
        in: query
        name: end_timestamp
        schema:
          description: Unix timestamp for the end of the time series data
          examples:
          - 1729225932
          format: int64
          type: integer
      - description: Granularity of the time series data. Default is day.
        example: day
        explode: false
        in: query
        name: granularity
        schema:
          description: Granularity of the time series data. Default is day.
          enum:
          - hour
          - day
          examples:
          - day
          type: string
      - description: Protocol ID to return stats for
        example: 20ea4lMXEYCmpAhjuLKuD
        in: path
        name: id
        required: true
        schema:
          description: Protocol ID to return stats for
          examples:
          - 20ea4lMXEYCmpAhjuLKuD
          type: string
      - description: Unix timestamp if you want the data at a point in time instead of a range
        example: 1726654050
        explode: false
        in: query
        name: timestamp
        schema:
          description: Unix timestamp if you want the data at a point in time instead of a range
          examples:
          - 1726654050
          format: int64
          type: integer
      - description: Calculate the Superform (not overall) TVL for all the vaults comprising this protocol
        example: true
        explode: false
        in: query
        name: fetch_superform_tvl
        schema:
          description: Calculate the Superform (not overall) TVL for all the vaults comprising this protocol
          examples:
          - true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalProtocolResponseBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Get protocol stats
      tags:
      - Protocol
  /protocols:
    get:
      description: Get all protocols listed on Superform.
      operationId: get-protocols-all
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Protocol'
                type: array
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Get all protocols
      tags:
      - Protocol
components:
  schemas:
    User:
      additionalProperties: false
      properties:
        address:
          type: string
        created_at:
          format: date-time
          type: string
        dynamic_id:
          type: string
        dynamic_wallet_id:
          type: string
        id:
          type: string
        name:
          type: string
        protocol_id:
          type: string
        role:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - id
      - dynamic_id
      - dynamic_wallet_id
      - address
      - protocol_id
      - name
      - role
      - created_at
      - updated_at
      type: object
    HistoricalProtocolResponseBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.superform.xyz/schemas/HistoricalProtocolResponseBody.json
          format: uri
          readOnly: true
          type: string
        historical_data:
          $ref: '#/components/schemas/HistoricalDataStruct'
        superform_tvl:
          format: double
          type: number
        total_vaults:
          format: int64
          type: integer
        tvl:
          format: double
          type: number
        tvl_24h_change:
          format: double
          type: number
      required:
      - historical_data
      - total_vaults
      - tvl
      - tvl_24h_change
      type: object
    HistoricalDataStruct:
      additionalProperties: false
      properties:
        timestamp:
          items:
            format: int64
            minimum: 0
            type: integer
          type: array
        tvl:
          items:
            format: double
            type: number
          type: array
      required:
      - timestamp
      - tvl
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.superform.xyz/schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
    Protocol:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.superform.xyz/schemas/Protocol.json
          format: uri
          readOnly: true
          type: string
        analytics:
          items:
            $ref: '#/components/schemas/ProtocolAnalytic'
          type: array
        audits:
          items:
            $ref: '#/components/schemas/ProtocolAudit'
          type: array
        chain_ids:
          items:
            format: int64
            minimum: 0
            type: integer
          type: array
        created_at:
          format: date-time
          type: string
        defillama_id:
          type: string
        deploy_date:
          format: date-time
          type: string
        deployers:
          items:
            $ref: '#/components/schemas/Deployer'
          type: array
        description:
          type: string
        exploits:
          items:
            $ref: '#/components/schemas/ProtocolExploit'
          type: array
        faq:
          items:
            $ref: '#/components/schemas/ProtocolFAQ'
          type: array
        graphics:
          $ref: '#/components/schemas/ProtocolGraphics'
        id:
          type: string
        is_authenticated:
          type: boolean
        is_hidden:
          type: boolean
        links:
          $ref: '#/components/schemas/ProtocolLinks'
        name:
          type: string
        num_depositors:
          format: int64
          type: integer
        primary_color:
          type: string
        status:
          type:
          - string
          - 'null'
        status_message:
          type:
          - string
          - 'null'
        tagline:
          type: string
        tvl:
          format: double
          type: number
        tvl_day_change:
          format: double
          type: number
        tvl_month_change:
          format: double
          type: number
        tvl_week_change:
          format: double
          type: number
        type:
          type: string
        updated_at:
          format: date-time
          type: string
        users:
          items:
            $ref: '#/components/schemas/User'
          type: array
        vanity_url:
          type: string
        vaults_amount:
          format: int64
          type: integer
      required:
      - id
      - name
      - description
      - type
      - tagline
      - is_hidden
      - is_authenticated
      - defillama_id
      - vanity_url
      - primary_color
      - num_depositors
      - status
      - status_message
      - deploy_date
      - graphics
      - links
      - vaults_amount
      - tvl
      - tvl_day_change
      - tvl_week_change
      - tvl_month_change
      - created_at
      - updated_at
      type: object
    ProtocolExploit:
      additionalProperties: false
      properties:
        amount:
          type: string
        created_at:
          format: date-time
          type: string
        date:
          format: date-time
          type: string
        id:
          type: string
        is_deleted:
          type: boolean
        protocol_id:
          type: string
        title:
          type: string
        updated_at:
          format: date-time
          type: string
        url:
          type: string
      required:
      - id
      - protocol_id
      - title
      - amount
      - url
      - date
      - is_deleted
      - created_at
      - updated_at
      type: object
    Deployer:
      additionalProperties: false
      properties:
        address:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: string
        name:
          type: string
        status:
          type: string
        type:
          type: string
        updated_at:
          format: date-time
          type: string
        vault_count:
          format: int64
          type: integer
      required:
      - id
      - vault_count
      - address
      - name
      - status
      - type
      - created_at
      - updated_at
      type: object
    ProtocolAnalytic:
      additionalProperties: false
      properties:
        chart_title:
          type: string
        chart_url:
          type: string
        id:
          type: string
        is_deleted:
          type: boolean
        protocol_id:
          type: string
      required:
      - id
      - protocol_id
      - chart_title
      - chart_url
      - is_deleted
      type: object
    ProtocolFAQ:
      additionalProperties: false
      properties:
        answer:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: string
        is_deleted:
          type: boolean
        protocol_id:
          type: string
        question:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - id
      - protocol_id
      - question
      - answer
      - is_deleted
      - created_at
      - updated_at
      type: object
    ProtocolAudit:
      additionalProperties: false
      properties:
        audit_date:
          format: date-time
          type: string
        audit_link:
          type: string
        audit_name:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: string
        is_deleted:
          type: boolean
        protocol_id:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
      - id
      - protocol_id
      - audit_name
      - audit_link
      - audit_date
      - is_deleted
      - created_at
      - updated_at
      type: object
    ProtocolGraphics:
      additionalProperties: false
      properties:
        avatar:
          type: string
        header:
          type: string
        icon:
          type: string
        watermark:
          type: string
      required:
      - icon
      - header
      - avatar
      - watermark
      type: object
    ProtocolLinks:
      additionalProperties: false
      properties:
        discord:
          type: string
        telegram:
          type: string
        twitter:
          type: string
        website:
          type: string
      required:
      - website
      - twitter
      - discord
      - telegram
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    apiKey:
      description: Provide the api key issued to you
      in: header
      name: SF-API-KEY
      type: apiKey