openapi: 3.0.3
info:
  title: WSO2 Transactional API
  description: The wso2 transactional API documentation
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

paths:
  /api/v1:
    get:
      operationId: AppController_getHealth
      summary: Health check of WSO2 transactional api
      tags:
        - health
      responses:
        '200':
          description: Get welcome message.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad request or wallet address not found.
        '500':
          description: Server Error.

  /api/v1/blockchain/master-wallet-balance:
    get:
      operationId: BlockchainController_getMasterWalletBalance
      summary: Get master wallet balance
      description: This endpoint will return master wallet balance in wso2 tokens
      tags:
        - Transactional
      responses:
        '200':
          description: Retrieve master wallet balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MasterWalletBalanceResponseDto'
        '400':
          description: Bad request.
        '500':
          description: Server Error.

  /api/v1/blockchain/get-balance/{walletAddress}:
    get:
      operationId: BlockchainController_getBalanceByWalletAddress
      summary: Retrieve wso2 token balance by wallet address
      parameters:
        - name: walletAddress
          required: true
          in: path
          description: Address of the wallet
          schema:
            type: string
      tags:
        - Transactional
      responses:
        '200':
          description: Successfully retrieved balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBalanceByAddressResponseDto'
        '400':
          description: Bad request or wallet address not found.
        '500':
          description: Server Error.

  /api/v1/blockchain/transfer-token:
    post:
      operationId: BlockchainController_transferTokens
      summary: Transfer tokens to a specified wallet address
      tags:
        - Transactional
      requestBody:
        required: true
        description: Recipient wallet address and amount are required for token transfer.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferTokenDto'
      responses:
        '200':
          description: Token successfully transferred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenTransferResponseDto'
        '400':
          description: Bad request or transfer failed.
        '500':
          description: Server Error.

  /api/v1/blockchain/transactions/search:
    post:
      operationId: BlockchainController_browseTransactions
      summary: Search Transfer events with optional filters and pagination
      tags:
        - Transactional
      requestBody:
        required: false
        description: Optional filters and pagination parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrowseTransactionsDto'
      responses:
        '200':
          description: Successfully retrieved transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponseDto'
        '400':
          description: Bad request.
        '500':
          description: Server Error.

  /api/v1/blockchain/get-transaction-details/{txHash}:
    get:
      operationId: BlockchainController_getTransactionDetailsByTxHash
      summary: Get the full transaction details and status of the given tx hash
      parameters:
        - name: txHash
          required: true
          in: path
          description: Transaction hash of the transaction start with 0x
          schema:
            type: string
      tags:
        - Transactional
      responses:
        '200':
          description: Successfully retrieved transaction details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetailsResponseDto'
        '400':
          description: Bad request or transaction not found.
        '500':
          description: Server Error.

tags:
  - name: wso2
    description: ''

components:
  schemas:
    MasterWalletBalanceDto:
      type: object
      properties:
        masterWalletAddress:
          type: string
          description: The wallet address of the ws02 master wallet
        balance:
          type: string
          description: WSO2 Token balance
        tokenBalanceUnFormatted:
          type: string
          description: Solidity's format representation of the WSO2 token balance.
        decimals:
          type: number
          description: The token's decimal precision defined in our smart contract.
      required:
        - masterWalletAddress
        - balance
        - tokenBalanceUnFormatted
        - decimals

    MasterWalletBalanceResponseDto:
      type: object
      properties:
        message:
          type: string
          description: A message indicating the result of the API request.
        httpCode:
          type: number
          description: HTTP status code of the response.
        payload:
          $ref: '#/components/schemas/MasterWalletBalanceDto'
      required:
        - message
        - httpCode
        - payload

    WalletBalanceByAddressDto:
      type: object
      properties:
        walletAddress:
          type: string
          description: The wallet address.
        balance:
          type: string
          description: WSO2 Token balance.
        tokenBalanceUnFormatted:
          type: string
          description: Solidity's format representation of the WSO2 token balance.
        decimals:
          type: number
          description: The token's decimal precision.
      required:
        - walletAddress
        - balance
        - tokenBalanceUnFormatted
        - decimals

    WalletBalanceByAddressResponseDto:
      type: object
      properties:
        message:
          type: string
          description: A message indicating the result of the API request.
        httpCode:
          type: number
          description: HTTP status code of the response.
        payload:
          $ref: '#/components/schemas/WalletBalanceByAddressDto'
      required:
        - message
        - httpCode
        - payload

    TransferTokenDto:
      type: object
      properties:
        recipientWalletAddress:
          type: string
          description: The wallet address of the recipient.
        amount:
          type: integer
          description: The amount of tokens to transfer.
      required:
        - recipientWalletAddress
        - amount

    TokenTransferResponseDto:
      type: object
      properties:
        message:
          type: string
          description: A message indicating the result of the API request.
        httpCode:
          type: number
          description: HTTP status code of the response.
        payload:
          type: object
          properties:
            transactionHash:
              type: string
              description: The hash of the token transfer transaction.
            blockNumber:
              type: string
              description: The block number in which the transaction was included.
            cumulativeGasUsed:
              type: string
              description: The total amount of gas used when the transaction was included in a block.
      required:
        - message
        - httpCode
        - payload

    TransactionDetailsDto:
      type: object
      properties:
        txHash:
          type: string
          description: The transaction hash (0x-prefixed).
        found:
          type: boolean
          description: Whether the transaction was found on-chain.
        success:
          type: boolean
          description: Whether the transaction executed successfully (receipt.status === 1).
        status:
          type: string
          description: Human-readable status of the transaction.
          enum:
            - SUCCESS
            - FAILED
            - PENDING
            - NOT_FOUND
        timestamp:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601 timestamp of the block containing the transaction, or null if unknown.
        amountFormatted:
          type: string
          nullable: true
          description: Formatted transferred token amount using the token decimals (human-readable), or null if not applicable/unavailable.
        txDetails:
          type: object
          nullable: true
          description: Raw transaction details returned by the provider, or null if not found.
        decodedData:
          type: object
          nullable: true
          description: Decoded version of the input data, providing more human-readable information about the call, or null if not found.
      required:
        - txHash
        - found
        - success
        - status
        - timestamp
        - amountFormatted
        - txDetails
        - decodedData

    TransactionDetailsResponseDto:
      type: object
      properties:
        message:
          type: string
          description: A message indicating the result of the API request.
        httpCode:
          type: number
          description: HTTP status code of the response.
        payload:
          $ref: '#/components/schemas/TransactionDetailsDto'
      required:
        - message
        - httpCode
        - payload

    BrowseTransactionsDto:
      type: object
      properties:
        senderAddresses:
          type: array
          items:
            type: string
          description: Filter by sender (from) wallet address(es).
        receiverAddresses:
          type: array
          items:
            type: string
          description: Filter by receiver (to) wallet address(es).
        transactionHash:
          type: string
          description: Filter by exact transaction hash.
        startTime:
          type: string
          format: date-time
          description: Return only transactions after this time (ISO-8601, exclusive).
        endTime:
          type: string
          format: date-time
          description: Return only transactions before this time (ISO-8601, exclusive).
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Maximum number of results to return (1-100). Defaults to 10.
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of results to skip for pagination. Defaults to 0.

    TransactionItemDto:
      type: object
      properties:
        txHash:
          type: string
          description: Transaction hash (0x-prefixed).
        blockNumber:
          type: integer
          description: Block number in which the transaction was mined.
        senderAddress:
          type: string
          description: Sender wallet address.
        receiverAddress:
          type: string
          description: Receiver wallet address.
        amount:
          type: string
          description: Transferred amount formatted using token decimals (human-readable).
        amountRaw:
          type: string
          description: Raw transferred amount as an unformatted string.
        timestamp:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601 timestamp of the block, or null if unavailable.
      required:
        - txHash
        - blockNumber
        - senderAddress
        - receiverAddress
        - amount
        - amountRaw
        - timestamp

    TransactionListDto:
      type: object
      properties:
        hasMore:
          type: boolean
          description: Whether more results exist beyond the current page.
        offset:
          type: integer
          description: Number of results skipped.
        limit:
          type: integer
          description: Maximum number of results returned per page.
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionItemDto'
          description: List of matching transactions, ordered newest first.
      required:
        - hasMore
        - offset
        - limit
        - transactions

    TransactionListResponseDto:
      type: object
      properties:
        message:
          type: string
          description: A message indicating the result of the API request.
        httpCode:
          type: number
          description: HTTP status code of the response.
        payload:
          $ref: '#/components/schemas/TransactionListDto'
      required:
        - message
        - httpCode
        - payload