openapi: 3.2.0
info:
  title: Earn Provider Server Stakes API
  version: 1.1.0
tags:
- name: Stakes
paths:
  /v1/{network}/stakes:
    get:
      description: Get details about a user's staking position based on the provided network and stake addresses.
      operationId: getV0NetworkStakes
      parameters:
      - name: network
        in: path
        required: true
        schema:
          type: string
          enum:
          - ethereum
          - cosmos
          - solana
          - cardano
          - tezos
          - near
          - osmo
          - injective
          example: ethereum
      - name: stake_addresses
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated list of stake addresses
          example: 0x1D1479C185d32EB90533a08b36B3CFa5F84A0E6B%2C0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5
      responses:
        '200':
          description: ''
          headers:
            Cache-Control:
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      $ref: '#/components/schemas/WalletView'
                    stake:
                      $ref: '#/components/schemas/StakeView'
                example:
                - id:
                    network: ethereum
                    address: '0x1D1479C185d32EB90533a08b36B3CFa5F84A0E6B'
                  stake:
                    protocol_name: figment
                    currency: ethereum/erc20/lombard_staked_bitcoin
                    interest:
                      type: APY
                      value: '0'
                    logo: https://path-to-logo
                    since: '2024-06-07T13:11:23Z'
                    staked_balance: '1'
                    status: activated
                    commission: Net
                    rewards:
                    - total: '89102191421829'
                      last_day: '0'
                      last_week: '0'
                      last_month: '0'
                      reward_name: LombardPoints
                      interest_rate: '0'
                      points_value_in_currency: '0'
                      type: RewardsPointsView
                    - total: '89102191421829'
                      last_day: '0'
                      last_week: '0'
                      last_month: '0'
                      reward_name: BabylonPoints
                      interest_rate: '0'
                      points_value_in_currency: '0'
                      type: RewardsPointsView
                    - total: '89102191421829'
                      last_day: '133010301'
                      last_week: '230414144'
                      last_month: '3423424242'
                      reward_name: LBTC Rewards
                      currency: ethereum/erc20/lombard_staked_bitcoin
                      interest_rate: '4.5'
                      type: RewardsTokenView
                    details:
                      contract_address: '0xae7ab96520de3a18e5e111b5eaab095312d7fe84'
                      type: EthDeFiDetailsView
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequest'
              example:
                msg: Invalid request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              example:
                realm: earn
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              example:
                what: 0x00000000000 not found
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Stakes
components:
  schemas:
    StakeKitStakeDetailsView:
      title: StakeKitStakeDetailsView
      type: object
      required:
      - symbol
      - validator
      - rewards
      - balance
      - net_apy
      - yield_id
      properties:
        symbol:
          type: string
          description: The symbol of the token held by the user.
        validator:
          type: string
          description: The address of the validator the user delegated assets to.
        net_apy:
          type: number
          format: double
          description: Net annual percentage yield.
        yield_id:
          type: string
          description: Stakekit Integration ID.
    SolanaDetailsView:
      title: SolanaDetailsView
      type: object
      required:
      - stake_account
      - withdraw_pubkey
      - balance
      - activated_epoch
      - activated_at
      - net_apy
      - validator_address
      - updated_at
      properties:
        stake_account:
          type: string
        withdraw_pubkey:
          type: string
        balance:
          type: integer
        activated_epoch:
          type: integer
          format: int32
        activated_at:
          type: string
          format: date-time
        net_apy:
          type: number
          format: double
        validator_address:
          type: string
        updated_at:
          type: string
          format: date-time
    InjectiveDetailsView:
      title: InjectiveDetailsView
      type: object
      required:
      - validator_address
      - delegator_address
      - rewards
      - available_rewards
      - balance
      - net_apy
      - updated_at
      properties:
        validator_address:
          type: string
        delegator_address:
          type: string
        delegated_at:
          type: string
          format: date-time
        undelegated_at:
          type: string
          format: date-time
        rewards:
          type: integer
        available_rewards:
          type: integer
        balance:
          type: integer
        net_apy:
          type: number
          format: double
        updated_at:
          type: string
          format: date-time
    StakeKitVaultDetailsView:
      title: StakeKitVaultDetailsView
      type: object
      required:
      - contract_address
      - protocol
      - protocol_display_name
      - protocol_icon
      - asset_icon
      - shared_symbol
      properties:
        contract_address:
          type: string
          description: Address of the token held in the user’s wallet.
        protocol:
          type: string
          description: The name of the protocol.
        protocol_display_name:
          type: string
          description: The name of the protocol to display.
        protocol_icon:
          type: string
          description: The URL pointing to the protocol's icon in PNG format.
        asset_icon:
          type: string
          description: The URL pointing to the asset’s icon in PNG format.
        shared_symbol:
          type: string
          description: The symbol of the asset held in the user’s wallet.
    CommissionView:
      title: CommissionView
      description: The commission type
      type: string
      enum:
      - Net
    EthNativeDetailsView:
      title: EthNativeDetailsView
      type: object
      required:
      - validator_address
      - consensus_rewards
      - execution_rewards
      properties:
        validator_address:
          description: The Ethereum address of the validator.
          type: string
        withdrawal_credentials:
          description: The withdrawal credentials for accessing staked ETH and rewards. This can be a BLS public key or an Ethereum address.
          type: string
        deposit_tx_sender:
          description: TThe Ethereum address that initiated the deposit transaction to the staking contract. This indicates the source of the staked ETH.
          type: string
        execution_fee_recipient:
          description: The Ethereum address that will receive execution layer rewards, including transaction fees and Maximal Extractable Value (MEV).
          type: string
        consensus_rewards:
          description: The total rewards earned from validating blocks and participating in consensus, represented in wei.
          type: string
        execution_rewards:
          description: The total execution layer rewards earned from transaction fees and MEV, represented in wei.
          type: string
    WalletView:
      title: WalletView
      type: object
      required:
      - network
      - address
      properties:
        network:
          description: Network name
          type: string
        address:
          description: User wallet address
          type: string
    OsmosisDetailsView:
      title: OsmosisDetailsView
      type: object
      required:
      - delegator_address
      - rewards
      - available_rewards
      - balance
      - net_apy
      - updated_at
      properties:
        delegator_address:
          type: string
        rewards:
          type: integer
        available_rewards:
          type: integer
        balance:
          type: integer
        net_apy:
          type: number
          format: double
        updated_at:
          type: string
          format: date-time
    EthDeFiDetailsView:
      title: EthDeFiDetailsView
      type: object
      required:
      - contract_address
      properties:
        contract_address:
          type: string
        type:
          type: string
      example:
        contract_address: '0x4dac23030b3ce359681fb7c00426f989a84e5298'
        type: EthDefiDetailsView
    StakeViewSuccess:
      title: Success
      type: object
      required:
      - protocol_name
      - currency
      - interest
      - status
      - commission
      - rewards
      - details
      - since
      - logo
      - staked_balance
      properties:
        protocol_name:
          description: The name of the protocol
          type: string
        currency:
          description: The currency of the staked asset in Ledger's crypto currency ID
          type: string
        interest:
          $ref: '#/components/schemas/InterestView'
          description: The interest rate
        logo:
          $ref: '#/components/schemas/Uri'
          description: The logo of the protocol (path to logo in .svg format)
        since:
          description: The date when the stake was created
          type: string
          format: date-time
        staked_balance:
          description: The staked balance, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        status:
          $ref: '#/components/schemas/StatusView'
        commission:
          $ref: '#/components/schemas/CommissionView'
        rewards:
          $ref: '#/components/schemas/RewardsView'
        details:
          $ref: '#/components/schemas/DetailsView'
    StatusView:
      title: StatusView
      type: string
      description: The status of the stake
      enum:
      - activated
      - activating
      - archived
      - deactivated
      - deactivating
    Failure:
      title: Failure
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/FailureView'
    RewardsView:
      title: RewardsView
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/RewardsTokensView'
        - $ref: '#/components/schemas/RewardsPointsView'
        - $ref: '#/components/schemas/RewardsViewError'
    Map_String:
      title: Map_String
      type: object
      additionalProperties:
        type: string
    InvalidRequest:
      title: InvalidRequest
      type: object
      required:
      - msg
      properties:
        msg:
          type: string
    Unauthorized:
      title: Unauthorized
      type: object
      required:
      - realm
      properties:
        realm:
          type: string
    InterestView:
      title: InterestView
      type: object
      required:
      - type
      - value
      properties:
        type:
          description: The type of interest - APY
          type: string
        value:
          description: The Net APY interest rate. Interest user is getting from their staking position. Not the protocol's APY.
          type: string
    RewardsViewError:
      title: RewardsViewError
      type: object
      required:
      - code
      - reason
      properties:
        code:
          description: Error code
          type: integer
          format: int32
        reason:
          description: Error message
          type: string
    RewardsPointsView:
      title: RewardsPointsView
      type: object
      required:
      - total
      - last_day
      - last_week
      - last_month
      - reward_name
      - interest_rate
      - points_value_in_currency
      - type
      properties:
        total:
          description: Total rewards earned, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        last_day:
          description: Rewards earned in the last 24 hours, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        last_week:
          description: Rewards earned in the last 7 days, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        last_month:
          description: Rewards earned in the last 30 days, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        reward_name:
          description: The name of the reward
          type: string
        interest_rate:
          description: The interest rate if it exists else 0.
          type: string
        points_value_in_currency:
          description: The value of the reward in the currency if it exists else 0.
          type: string
        type:
          description: The type of the reward view
          type: string
          enum:
          - RewardsPointsView
    NotFound:
      title: NotFound
      type: object
      required:
      - what
      properties:
        what:
          type: string
    RewardsTokensView:
      title: RewardsTokenView
      type: object
      required:
      - total
      - last_day
      - last_week
      - last_month
      - reward_name
      - interest_rate
      - currency
      - type
      properties:
        total:
          description: Total rewards earned, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        last_day:
          description: Rewards earned in the last 24 hours, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        last_week:
          description: Rewards earned in the last 7 days, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        last_month:
          description: Rewards earned in the last 30 days, denominated in the smallest unit of the currency (e.g., wei for ETH).
          type: string
        reward_name:
          description: The name of the reward
          type: string
        interest_rate:
          description: The Net APY interest rate
          type: string
        currency:
          description: Ledger crypto currency ID
          type: string
        type:
          description: The type of the reward view
          type: string
          enum:
          - RewardsTokenView
    ServerError:
      title: ServerError
      type: object
      required:
      - msg
      properties:
        msg:
          type: string
    StakeView:
      title: StakeView
      oneOf:
      - $ref: '#/components/schemas/StakeViewSuccess'
      - $ref: '#/components/schemas/Failure'
    DetailsView:
      oneOf:
      - $ref: '#/components/schemas/EthDeFiDetailsView'
      - $ref: '#/components/schemas/AdaDetailsView'
      - $ref: '#/components/schemas/CosmosDetailsView'
      - $ref: '#/components/schemas/EthNativeDetailsView'
      - $ref: '#/components/schemas/InjectiveDetailsView'
      - $ref: '#/components/schemas/CoinbaseEthereumPoolingDetailsView'
      - $ref: '#/components/schemas/NearDetailsView'
      - $ref: '#/components/schemas/OsmosisDetailsView'
      - $ref: '#/components/schemas/SolanaDetailsView'
      - $ref: '#/components/schemas/StakeKitStakeDetailsView'
      - $ref: '#/components/schemas/StakeKitVaultDetailsView'
      - $ref: '#/components/schemas/TezosDetailsView'
    TezosDetailsView:
      title: TezosDetailsView
      type: object
      required:
      - stake_address
      - backer_address
      - balance
      - rewards
      - gross_apy
      - delegated_cycle
      - updated_at
      properties:
        stake_address:
          type: string
        backer_address:
          type: string
        balance:
          type: integer
        rewards:
          type: integer
        gross_apy:
          type: number
          format: double
        delegated_at:
          type: string
          format: date-time
        delegated_block:
          type: integer
        delegated_cycle:
          type: integer
          format: int32
        activated_cycle:
          type: integer
          format: int32
        activated_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CoinbaseEthereumPoolingDetailsView:
      title: CoinbaseEthereumPoolingDetailsView
      type: object
      required:
      - owner
      - delegated_block
      - delegated_at
      properties:
        owner:
          type: string
        delegated_block:
          type: integer
        delegated_at:
          type: string
          format: date-time
    CosmosDetailsView:
      title: CosmosDetailsView
      type: object
      required:
      - validator_address
      - delegator_address
      - rewards
      - available_rewards
      - balance
      - net_apy
      - updated_at
      properties:
        validator_address:
          type: string
        delegator_address:
          type: string
        delegated_at:
          type: string
          format: date-time
        undelegated_at:
          type: string
          format: date-time
        rewards:
          type: integer
        available_rewards:
          type: integer
        balance:
          type: integer
        net_apy:
          type: number
          format: double
        updated_at:
          type: string
          format: date-time
    AdaDetailsView:
      title: AdaDetailsView
      type: object
      required:
      - poolId
      - activationEpoch
      - activationDate
      properties:
        poolId:
          type: string
        activationEpoch:
          type: integer
          format: int32
        activationDate:
          type: string
          format: date-time
    NearDetailsView:
      title: NearDetailsView
      type: object
      required:
      - stakeAccount
      - canWithdraw
      - validator
      - netApy
      - activatedEpoch
      - activatedAt
      - updatedAt
      properties:
        stakeAccount:
          type: string
        canWithdraw:
          type: boolean
        validator:
          type: string
        netApy:
          type: number
          format: double
        activatedEpoch:
          type: integer
          format: int32
        activatedAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Uri:
      title: Uri
      type: string
    FailureView:
      title: FailureView
      type: object
      required:
      - code
      - reason
      - details
      properties:
        code:
          description: The error code
          type: integer
          format: int32
        reason:
          description: The error reason
          type: string
        details:
          $ref: '#/components/schemas/Map_String'
          description: The error details