Superform Token Distribution API

openapi: 3.1.0
info:
  title: Superform Auxiliary Token Distribution API
  version: 1.0.0
servers:
- url: https://api.superform.xyz
tags:
- name: Token Distribution
paths:
  /token-distribution/balance/{user}:
    get:
      description: Get the reward token balance for a user
      operationId: get-reward-token-balance
      parameters:
      - example: '0x1234567890123456789012345678901234567890'
        in: path
        name: user
        required: true
        schema:
          examples:
          - '0x1234567890123456789012345678901234567890'
          type: string
      - explode: false
        in: query
        name: force
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokenBalanceOutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Get reward token balance
      tags:
      - Token Distribution
  /token-distribution/claim/{user}:
    get:
      description: Start the piggy token claim process for a user and get the claim transaction
      operationId: start-piggy-token-claim
      parameters:
      - example: '0x1234567890123456789012345678901234567890'
        in: path
        name: user
        required: true
        schema:
          examples:
          - '0x1234567890123456789012345678901234567890'
          type: string
      - explode: false
        in: query
        name: simulation_required
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartTransactionRequest'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Start piggy token claim
      tags:
      - Token Distribution
  /token-distribution/slop-bucket/start/deposit/{user}:
    get:
      description: Start the slop bucket deposit process for a user and get the deposit transaction
      operationId: start-slop-bucket-deposit
      parameters:
      - example: '0x1234567890123456789012345678901234567890'
        in: path
        name: user
        required: true
        schema:
          examples:
          - '0x1234567890123456789012345678901234567890'
          type: string
      - example: '1000000000000000000'
        explode: false
        in: query
        name: amount
        required: true
        schema:
          examples:
          - '1000000000000000000'
          type: string
      - explode: false
        in: query
        name: approval_required
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartTransactionRequest'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Start slop bucket deposit
      tags:
      - Token Distribution
  /token-distribution/slop-bucket/start/harvest/{user}:
    get:
      description: Start the slop bucket claim process for a user and get the claim transaction
      operationId: start-slop-bucket-claim
      parameters:
      - example: '0x1234567890123456789012345678901234567890'
        in: path
        name: user
        required: true
        schema:
          examples:
          - '0x1234567890123456789012345678901234567890'
          type: string
      - explode: false
        in: query
        name: simulation_required
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartTransactionRequest'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Start slop bucket claim
      tags:
      - Token Distribution
  /token-distribution/slop-bucket/start/withdraw/{user}:
    get:
      description: Start the slop bucket withdraw process for a user and get the withdraw transaction
      operationId: start-slop-bucket-withdraw
      parameters:
      - example: '0x1234567890123456789012345678901234567890'
        in: path
        name: user
        required: true
        schema:
          examples:
          - '0x1234567890123456789012345678901234567890'
          type: string
      - example: '1000000000000000000'
        explode: false
        in: query
        name: amount
        required: true
        schema:
          examples:
          - '1000000000000000000'
          type: string
      - explode: false
        in: query
        name: approval_required
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartTransactionRequest'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Start slop bucket withdraw
      tags:
      - Token Distribution
  /token-distribution/{user}:
    get:
      description: Returns the distribution of the piggy token and superrewards for the user
      operationId: get-token-distribution
      parameters:
      - example: '0x1234567890123456789012345678901234567890'
        in: path
        name: user
        required: true
        schema:
          examples:
          - '0x1234567890123456789012345678901234567890'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokenDistributionOutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - apiKey: []
      summary: Get token distribution for a user
      tags:
      - Token Distribution
components:
  schemas:
    StartTransactionRequest:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.superform.xyz/schemas/StartTransactionRequest.json
          format: uri
          readOnly: true
          type: string
        approval:
          $ref: '#/components/schemas/ApprovalTransaction'
        gasPriceInGwei:
          format: double
          type:
          - number
          - 'null'
        to:
          type: string
        transactionData:
          type: string
        value:
          type: string
      required:
      - transactionData
      - to
      - value
      - gasPriceInGwei
      type: object
    PiggyTokenStats:
      additionalProperties: false
      properties:
        break_the_bank:
          format: double
          type: number
        break_the_bank_tokens:
          format: double
          type: number
        community_score:
          format: double
          type: number
        community_score_percentile:
          format: double
          type: number
        community_score_tokens:
          format: double
          type: number
        final_superform_xp:
          format: double
          type: number
        final_superform_xp_percentile:
          format: double
          type: number
        superform_xp_tokens:
          format: double
          type: number
        tokens_percentile:
          format: double
          type: number
        total_tokens:
          format: double
          type: number
        user_address:
          type: string
      required:
      - user_address
      - final_superform_xp
      - final_superform_xp_percentile
      - community_score
      - community_score_percentile
      - break_the_bank
      - superform_xp_tokens
      - community_score_tokens
      - break_the_bank_tokens
      - total_tokens
      - tokens_percentile
      type: object
    GetTokenBalanceOutputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.superform.xyz/schemas/GetTokenBalanceOutputBody.json
          format: uri
          readOnly: true
          type: string
        availableAmount:
          type: string
        depositedAmount:
          type: string
        piggyBalance:
          type: string
        piggyEthBalance:
          type: string
        rewardsAPY:
          format: double
          type: number
        user:
          type: string
      required:
      - user
      - piggyBalance
      - piggyEthBalance
      - depositedAmount
      - availableAmount
      - rewardsAPY
      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
    ApprovalTransaction:
      additionalProperties: false
      properties:
        approvingAmount:
          type: string
        to:
          type: string
        transactionData:
          type: string
      required:
      - transactionData
      - to
      - approvingAmount
      type: object
    GetTokenDistributionOutputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.superform.xyz/schemas/GetTokenDistributionOutputBody.json
          format: uri
          readOnly: true
          type: string
        rewards_claimed:
          type: boolean
        superrewards_stats:
          $ref: '#/components/schemas/PiggyTokenStats'
      required:
      - superrewards_stats
      - rewards_claimed
      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