openapi: 3.0.0
paths:
  /health:
    get:
      operationId: AppController_getHealth
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - App
      summary: Get App Health
  /version:
    get:
      operationId: AppController_getVersion
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - App
      summary: Get App Version
  /transfer/{customerId}/history:
    get:
      description: >-
        Retrieves all transfer history (deposits, withdrawals, mints,
        redemptions) for the customer.
      operationId: TransferController_getTransferHistory
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of transfers to return
          schema:
            example: 10
            type: number
      responses:
        '200':
          description: Transfer history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Transfer type
                        amount:
                          type: string
                          description: Transfer amount
                        chainType:
                          type: string
                          description: Blockchain type
                        status:
                          type: string
                          description: Transfer status
                        onchainStatus:
                          type: string
                          description: On-chain status
                        txHash:
                          type: string
                          description: Transaction hash
                        timestamp:
                          type: string
                          format: date-time
                          description: Transfer timestamp
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Get all transfer history
      tags:
        - Transfer
  /transfer/{customerId}/bank-transfers:
    get:
      description: >-
        Retrieves all bank transfers (SEPA, internal, deposits, withdrawals) for
        the customer.
      operationId: TransferController_getBankTransfers
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of transfers to return
          schema:
            example: 50
            type: number
      responses:
        '200':
          description: Bank transfers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Transfer type
                        amount:
                          type: string
                          description: Transfer amount
                        from:
                          type: string
                          description: Source account
                        to:
                          type: string
                          description: Destination account
                        status:
                          type: string
                          description: Transfer status
                        timestamp:
                          type: string
                          format: date-time
                          description: Transfer timestamp
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Get bank transfer history
      tags:
        - Transfer
  /transfer/{customerId}/crypto-transfers:
    get:
      description: Retrieves all crypto transfers (mints and redemptions) for the customer.
      operationId: TransferController_getCryptoTransfers
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of transfers to return
          schema:
            example: 50
            type: number
      responses:
        '200':
          description: Crypto transfers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - MINT
                            - REDEEM
                          description: Transfer type
                        amount:
                          type: string
                          description: Transfer amount
                        address:
                          type: string
                          description: Blockchain address
                        chainType:
                          type: string
                          enum:
                            - RIPPLE
                            - ETHEREUM
                            - POLYGON
                            - AVALANCHE
                          description: Blockchain type
                        status:
                          type: string
                          description: On-chain status
                        txHash:
                          type: string
                          description: Transaction hash
                        timestamp:
                          type: string
                          format: date-time
                          description: Transfer timestamp
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Get crypto transfer history
      tags:
        - Transfer
  /customer:
    get:
      description: >-
        Returns a paginated list of all customers created by the requesting
        superclient.
      operationId: CustomerController_getAllCustomers
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (starting from 1)
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of customers per page (max 100)
          schema:
            example: 10
            type: number
      responses:
        '200':
          description: Customers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Customer unique identifier
                        name:
                          type: string
                          description: Customer company name
                        companyIco:
                          type: string
                          description: Company ICO/registration number
                        defaultChain:
                          type: string
                          description: Default blockchain
                        defaultChainAddress:
                          type: string
                          description: Default blockchain address
                        defaultBankAddress:
                          type: string
                          description: Default bank IBAN address
                        kycVerified:
                          type: boolean
                          description: KYC verification status
                        balance:
                          type: number
                          description: Customer balance
                        createdAt:
                          type: string
                          format: date-time
                          description: Creation timestamp
                  pagination:
                    type: object
                    properties:
                      page:
                        type: number
                        description: Current page number
                      limit:
                        type: number
                        description: Number of items per page
                      total:
                        type: number
                        description: Total number of customers
                      totalPages:
                        type: number
                        description: Total number of pages
        '401':
          description: Unauthorized - Invalid or missing API key
      security:
        - api-key: []
      summary: Retrieve all customers created by the superclient
      tags:
        - Customer
    post:
      description: >-
        Allows superclients to create new customers in the system. The created
        customer will be automatically linked to the superclient that created
        it.
      operationId: CustomerController_createCustomer
      parameters: []
      requestBody:
        required: true
        description: Customer creation data
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Customer company name
                  example: Acme Corporation
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Customer unique identifier
                  name:
                    type: string
                    description: Customer company name
                  companyIco:
                    type: string
                    description: Company ICO/registration number
                  defaultChain:
                    type: string
                    description: Default blockchain
                  defaultChainAddress:
                    type: string
                    description: Default blockchain address
                  defaultBankAddress:
                    type: string
                    description: Default bank IBAN address
                  kycVerified:
                    type: boolean
                    description: KYC verification status
                  balance:
                    type: number
                    description: Customer balance
                  createdAt:
                    type: string
                    format: date-time
                    description: Creation timestamp
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
        '400':
          description: Bad Request - Invalid input data
        '401':
          description: Unauthorized - Invalid or missing API key
      security:
        - api-key: []
      summary: Create customer via superclient API
      tags:
        - Customer
  /customer/{customerId}:
    get:
      description: >-
        Allows superclients to retrieve customer information by customer ID.
        Only customers created by the requesting superclient can be accessed.
      operationId: CustomerController_getCustomerById
      parameters:
        - name: id
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        '200':
          description: Customer retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Customer unique identifier
                  name:
                    type: string
                    description: Customer company name
                  companyIco:
                    type: string
                    description: Company ICO/registration number
                  defaultChain:
                    type: string
                    description: Default blockchain
                  defaultChainAddress:
                    type: string
                    description: Default blockchain address
                  defaultBankAddress:
                    type: string
                    description: Default bank IBAN address
                  kycVerified:
                    type: boolean
                    description: KYC verification status
                  balance:
                    type: number
                    description: Customer balance
                  createdAt:
                    type: string
                    format: date-time
                    description: Creation timestamp
                  updatedAt:
                    type: string
                    format: date-time
                    description: Last update timestamp
                  addresses:
                    type: array
                    description: Customer addresses
                    items:
                      type: object
                  vibans:
                    type: array
                    description: Customer virtual IBANs
                    items:
                      type: object
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Retrieve customer information
      tags:
        - Customer
  /customer/superclient/info:
    get:
      description: Retrieves the information about the authenticated superclient.
      operationId: CustomerController_getSuperclientInfo
      parameters: []
      responses:
        '200':
          description: Superclient information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Superclient unique identifier
                  name:
                    type: string
                    description: Superclient name
                  createdAt:
                    type: string
                    format: date-time
                    description: Account creation timestamp
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Superclient not found
      security:
        - api-key: []
      summary: Get superclient info
      tags:
        - Customer
  /address/{customerId}/viban:
    post:
      description: >-
        Allows superclients to generate a VIBAN for a specific customer. Only
        customers created by the requesting superclient can have VIBANs
        generated.
      operationId: AddressController_generateViban
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      requestBody:
        required: true
        description: VIBAN generation data
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  type: string
                  description: Optional alias for the VIBAN (max 30 characters)
                  example: Primary Account
                  maxLength: 30
      responses:
        '201':
          description: VIBAN generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  listCOBO:
                    type: array
                    items:
                      type: string
                    description: List of COBO VIBANs
                  listPOBO:
                    type: array
                    items:
                      type: string
                    description: List of POBO VIBANs
                  status:
                    type: string
                    enum:
                      - success
                      - pending
                    description: Generation status
        '400':
          description: Bad Request - VIBANs already exist for this customer
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
        '500':
          description: Internal Server Error - VIBAN generation failed
      security:
        - api-key: []
      summary: Generate virtual IBAN for customer
      tags:
        - Address
  /address/{customerId}/wallet:
    post:
      description: >-
        Allows superclients to add a blockchain wallet address for a specific
        customer. Supports RIPPLE, ETHEREUM, POLYGON, and AVALANCHE.
      operationId: AddressController_addWalletAddress
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      requestBody:
        required: true
        description: Wallet address data
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - addressType
              properties:
                address:
                  type: string
                  description: Blockchain wallet address
                  example: rN7n7otQDd6FczFgLdlqtyMVrn3HMfXEEQ
                  minLength: 15
                  maxLength: 34
                addressType:
                  type: string
                  enum:
                    - RIPPLE
                    - ETHEREUM
                    - POLYGON
                    - AVALANCHE
                  description: Blockchain type
                  example: RIPPLE
                alias:
                  type: string
                  description: Optional alias for the wallet (max 30 characters)
                  example: Main Wallet
                  maxLength: 30
      responses:
        '200':
          description: Wallet address added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: Address added
        '400':
          description: Bad Request - Invalid address or address already exists
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
        '422':
          description: Unprocessable Entity - Invalid wallet address format
      security:
        - api-key: []
      summary: Add blockchain wallet address for customer
      tags:
        - Address
  /address/{customerId}/default-address:
    post:
      description: >-
        Sets which address type should be the default for the customer. The
        address of that type must already exist.
      operationId: AddressController_setDefaultAddress
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      requestBody:
        required: true
        description: Address type to set as default
        content:
          application/json:
            schema:
              type: object
              required:
                - addressType
              properties:
                addressType:
                  type: string
                  enum:
                    - RIPPLE
                    - ETHEREUM
                    - POLYGON
                    - AVALANCHE
                    - BANK
                  description: Address type to set as default
                  example: ETHEREUM
      responses:
        '200':
          description: Default address updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: Default address updated
        '400':
          description: Bad Request - Address type not found for this customer
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Set default blockchain or bank address type
      tags:
        - Address
  /address/{customerId}/default-iban:
    post:
      description: >-
        Sets which IBAN should be the default for the customer to receive money
        on and send money from. The IBAN must already exist for this customer.
      operationId: AddressController_setDefaultIban
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      requestBody:
        required: true
        description: IBAN to set as default
        content:
          application/json:
            schema:
              type: object
              required:
                - iban
              properties:
                iban:
                  type: string
                  description: IBAN to set as default
                  example: DE89370400440532013000
      responses:
        '200':
          description: Default IBAN updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: Default IBAN updated
        '400':
          description: Bad Request - IBAN not found for this customer
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Set default IBAN to receive and send money
      tags:
        - Address
  /address/{customerId}/list:
    get:
      description: >-
        Retrieves all blockchain addresses and IBANs (VIBANs) for the customer,
        including which ones are set as default.
      operationId: AddressController_getAddresses
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        '200':
          description: Addresses retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  addressList:
                    type: array
                    description: List of blockchain addresses
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Address ID
                        address:
                          type: string
                          description: Blockchain address
                        addressType:
                          type: string
                          enum:
                            - RIPPLE
                            - ETHEREUM
                            - POLYGON
                            - AVALANCHE
                          description: Blockchain type
                        alias:
                          type: string
                          description: Address alias
                        isDefault:
                          type: boolean
                          description: >-
                            Whether this is the default address for this
                            blockchain type
                  vibans:
                    type: array
                    description: List of VIBANs
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: VIBAN ID
                        iban:
                          type: string
                          description: VIBAN (IBAN)
                        type:
                          type: string
                          enum:
                            - COBO
                            - POBO
                          description: VIBAN type
                        alias:
                          type: string
                          description: VIBAN alias
                  defaultChain:
                    type: string
                    enum:
                      - RIPPLE
                      - ETHEREUM
                      - POLYGON
                      - AVALANCHE
                    description: Default blockchain type
                    nullable: true
                  defaultChainAddress:
                    type: string
                    description: Default blockchain address
                    nullable: true
                  defaultIban:
                    type: string
                    description: Default IBAN (can be a VIBAN or custom IBAN set by user)
                    nullable: true
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Get blockchain addresses and IBANs
      tags:
        - Address
  /address/{customerId}/redemption-addresses:
    get:
      description: >-
        Retrieves the redemption addresses for all supported blockchains where
        the customer can send tokens to convert to fiat.
      operationId: AddressController_getRedemptionAddresses
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        '200':
          description: Redemption addresses retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  RIPPLE:
                    type: string
                    description: Ripple redemption address
                  ETHEREUM:
                    type: string
                    description: Ethereum redemption address
                  POLYGON:
                    type: string
                    description: Polygon redemption address
                  AVALANCHE:
                    type: string
                    description: Avalanche redemption address
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Get blockchain redemption addresses
      tags:
        - Address
  /address/{customerId}/allowed-chains:
    get:
      description: >-
        Retrieves the list of blockchain networks that the customer is allowed
        to use.
      operationId: AddressController_getAllowedChains
      parameters:
        - name: customerId
          required: true
          in: path
          description: Customer ID (UUID)
          schema:
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
            type: string
      responses:
        '200':
          description: Allowed chains retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowedChains:
                    type: array
                    items:
                      type: string
                      enum:
                        - RIPPLE
                        - ETHEREUM
                        - POLYGON
                        - AVALANCHE
                    description: List of allowed blockchain networks
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Customer not accessible by this superclient
        '404':
          description: Customer not found
      security:
        - api-key: []
      summary: Get allowed blockchains
      tags:
        - Address
info:
  title: Schuman API
  description: API for Schuman's stablecoin platform.
  version: '1.0'
  contact: {}
tags: []
servers: []
components:
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
  schemas: {}
