openapi: 3.0.0
info:
  title: Rakurai API
  description: >-
    API for managing deposits, withdrawals, and retrieving information related
    to Solana stake pools.
  version: 1.0.0
servers:
  - url: https://api.rakurai.io
security:
  - apiKey: []
paths:
  /api/deposit:
    post:
      operationId: depositIntoStakePool
      summary: /api/deposit
      description: >-
        Accepts a public key and amount in lamports to deposit into the stake
        pool.
      requestBody:
        description: JSON object with the user's public key and the amount to deposit.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pubkey:
                  type: string
                  description: Public key of the client.
                  example: Fg5kC6tJ9N5M5MS83M842ms23sNN2732N108dD2
                amount:
                  type: integer
                  description: Amount in lamports to deposit.
                  example: 54
      responses:
        '200':
          description: Transaction message ready for client signing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  txn:
                    type: string
                    description: Serialized transaction message for client signing.
                    example: BASE64_ENCODED_TRANSACTION_DATA
        '400':
          description: Insufficient funds in client account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Insufficient funds
        '500':
          description: Server error or stake pool not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Server exception
        x-hideTryItPanel: true
  /api/withdraw:
    post:
      operationId: withdrawFromStakePool
      summary: /api/withdraw
      description: >-
        Processes a withdrawal request from the stake pool based on the user's
        public key and amount.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pubkey:
                  type: string
                  description: Public key of the client.
                  example: Fg5kC6tJ9N5M5MS83M842ms23sNN2732N108dD2
                amount:
                  type: integer
                  description: Amount in lamports to withdraw.
                  example: 3000000
      responses:
        '200':
          description: Transaction message ready for client signing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  txn:
                    type: string
                    description: Serialized transaction message for client signing.
                    example: BASE64_ENCODED_TRANSACTION_DATA
                  pub_key:
                    type: string
                    description: Public key of the destination stake account.
                    example: Fg5kC6tJ9N5M5MS83M842ms23sNN2732N108dD2
                  sec_key:
                    type: string
                    description: Secret key of the destination stake account.
                    example: SECRET_KEY_BASE64_ENCODED
                  sig:
                    type: string
                    description: Signature of the transaction.
                    example: TRANSACTION_SIGNATURE_BASE64_ENCODED
        '400':
          description: Insufficient funds or insufficient active stake in the validator.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Insufficient funds
        '500':
          description: Server error or stake pool not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Server exception
  /api/tokenvalue:
    get:
      operationId: getTokenValue
      summary: /api/tokenvalue
      description: >-
        Returns the current value of tokens in the stake pool by calculating the
        ratio of total lamports to pool token supply.
      responses:
        '200':
          description: Successfully retrieves the token value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokenValue:
                    type: number
                    format: float
                    description: Current value of each pool token.
                    example: 1.25
        '500':
          description: Server error or stake pool not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Server exception
  /api/solvalue:
    get:
      operationId: getSolValue
      summary: /api/solvalue
      description: Retrieves the current USD value of SOL from an external API.
      responses:
        '200':
          description: Successfully retrieved SOL USD value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  solValue:
                    type: number
                    description: The current USD value of SOL.
                    example: 163.479
        '500':
          description: Server error or failed request to external API.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: SERVER_EXCEPTION
  /api/epochinfo:
    get:
      operationId: getEpochInfo
      summary: /api/epochinfo
      description: >-
        Retrieves the current epoch details including the number of remaining
        slots and the estimated time left in seconds.
      responses:
        '200':
          description: Successfully retrieved epoch information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  epochSeconds:
                    type: integer
                    description: Estimated remaining time in the current epoch, in seconds.
                    example: 12000
                  epoch:
                    type: integer
                    description: The current epoch number.
                    example: 234
        '500':
          description: Server error while fetching epoch info.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: SERVER_EXCEPTION
  /api/send:
    post:
      summary: /api/send
      description: Sends a serialized and signed transaction to the blockchain.
      operationId: sendTransaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                txn:
                  type: string
                  description: The serialized signed transaction in hex format to be sent.
                  example: 0xabcdef1234567890...
              required:
                - txn
      responses:
        '200':
          description: Successful transaction submission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  txn_signature:
                    type: string
                    description: The signature of the submitted transaction.
                    example: TransactionSignature
        '500':
          description: Server error while processing the transaction request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: SERVER_EXCEPTION
  /api/staking/account-status:
    post:
      summary: /api/staking/account-status
      description: >-
        Retrieves the status of a staking account based on the provided stake
        account address.
      operationId: getStakingAccountStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                stake_account:
                  type: string
                  description: The public key of the stake account to check the status of.
                  example: StakeAccountPublicKey
              required:
                - stake_account
      responses:
        '200':
          description: Successful retrieval of staking account status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  stake_account:
                    type: object
                    properties:
                      address:
                        type: string
                        description: The address of the stake account.
                        example: StakeAccountPublicKey
                      status:
                        type: string
                        description: >-
                          The status of the stake account (e.g., Uninitialized,
                          Inactive).
                        example: Inactive
                      stake_authority:
                        type: string
                        description: The stake authority for the account.
                        example: StakeAuthorityPublicKey
                      withdraw_authority:
                        type: string
                        description: The withdrawal authority for the account.
                        example: WithdrawAuthorityPublicKey
                      vote_account:
                        type: string
                        description: The associated vote account for the stake account.
                        example: VoteAccountPublicKey
                      amount:
                        type: integer
                        description: The amount of stake associated with the account.
                        example: 1000000
        '400':
          description: Error indicating an invalid stake account address or account type.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message related to the invalid stake account.
                    example: Invalid account address
        '500':
          description: Server error while processing the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: SERVER_EXCEPTION
  /api/apy:
    get:
      summary: /api/apy
      description: >-
        Retrieves the APY values for specified epochs or the latest APY if no
        parameters are provided.
      operationId: fetchApy
      parameters:
        - name: epoch
          in: query
          required: false
          description: Specific epoch to fetch the APY for.
          schema:
            type: string
            example: '5'
        - name: start_epoch
          in: query
          required: false
          description: Start of the epoch range for fetching APY values.
          schema:
            type: string
            example: '1'
        - name: end_epoch
          in: query
          required: false
          description: End of the epoch range for fetching APY values.
          schema:
            type: string
            example: '10'
      responses:
        '200':
          description: Successful retrieval of APY values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  apy_values:
                    type: array
                    items:
                      type: object
                      properties:
                        epoch:
                          type: integer
                          description: The epoch number.
                          example: 5
                        apy:
                          type: number
                          format: float
                          description: The APY value for the epoch.
                          example: 0.045
        '400':
          description: Error indicating an invalid epoch range or epoch format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message related to the invalid epoch or range.
                    example: Invalid epoch range
        '404':
          description: No APY data found for the provided criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message indicating query failure.
                    example: No data found for the given query
        '500':
          description: Server error while processing the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: QUERY_FAILURE_ERROR
  /api/tps:
    get:
      summary: /api/tps
      description: Retrieves the TPS values for specified epochs or time ranges.
      operationId: fetchTps
      parameters:
        - name: epoch
          in: query
          required: false
          description: Specific epoch to fetch the TPS for.
          schema:
            type: string
            example: '5'
        - name: time
          in: query
          required: false
          description: Specific timestamp to fetch the TPS value.
          schema:
            type: string
            example: '1680345600'
        - name: start_time
          in: query
          required: false
          description: Start of the time range for fetching TPS values.
          schema:
            type: string
            example: '1680345600'
        - name: end_time
          in: query
          required: false
          description: End of the time range for fetching TPS values.
          schema:
            type: string
            example: '1680349200'
        - name: start_epoch
          in: query
          required: false
          description: Start of the epoch range for fetching TPS values.
          schema:
            type: string
            example: '1'
        - name: end_epoch
          in: query
          required: false
          description: End of the epoch range for fetching TPS values.
          schema:
            type: string
            example: '10'
      responses:
        '200':
          description: Successful retrieval of TPS values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tps_values:
                    type: array
                    items:
                      type: object
                      properties:
                        epoch:
                          type: integer
                          description: The epoch number.
                          example: 5
                        tps:
                          type: number
                          format: float
                          description: The TPS value for the epoch.
                          example: 1000.5
        '400':
          description: Error indicating an invalid epoch or time range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message related to the invalid epoch or time.
                    example: Invalid epoch range
        '404':
          description: No TPS data found for the provided criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message indicating query failure.
                    example: No data found for the given query
        '500':
          description: Server error while processing the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: QUERY_FAILURE_ERROR
  /api/tvl:
    get:
      summary: /api/tvl
      description: Retrieves the TVL values for specified epochs.
      operationId: fetchTvl
      parameters:
        - name: epoch
          in: query
          required: false
          description: Specific epoch to fetch the TVL for.
          schema:
            type: string
            example: '5'
        - name: start_epoch
          in: query
          required: false
          description: Start of the epoch range for fetching TVL values.
          schema:
            type: string
            example: '1'
        - name: end_epoch
          in: query
          required: false
          description: End of the epoch range for fetching TVL values.
          schema:
            type: string
            example: '10'
      responses:
        '200':
          description: Successful retrieval of TVL values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tvl_values:
                    type: array
                    items:
                      type: object
                      properties:
                        epoch:
                          type: integer
                          description: The epoch number.
                          example: 5
                        tvl:
                          type: number
                          format: float
                          description: The TVL value for the epoch.
                          example: 2500000.75
        '400':
          description: Error indicating an invalid epoch range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message related to the invalid epoch.
                    example: Invalid epoch range
        '500':
          description: Server error while processing the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message for server failure.
                    example: QUERY_FAILURE_ERROR
        '503':
          description: No TVL data found for the provided criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message indicating query failure.
                    example: No data found for the given query
components: {}
