openapi: 3.0.0
info:
  title: Hifi Account Wallet API
  version: 2.0.0
  description: API documentation for Hifi
servers:
- url: https://production.hifibridge.com
  description: Production server
- url: https://sandbox.hifibridge.com
  description: Sandbox server
security:
- bearerAuth: []
tags:
- name: Wallet
  description: Wallet endpoints
paths:
  /v2/users/{userId}/wallets/balance:
    get:
      summary: Retrieve wallet balance
      description: Get the latest balance of a user's wallet, including details like the blockchain network and currency.
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      - $ref: '#/components/parameters/ChainParameter'
      - $ref: '#/components/parameters/CryptoCurrencyParameter'
      responses:
        '200':
          $ref: '#/components/responses/WalletBalanceResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/users/{userId}/wallets/add:
    post:
      summary: Add wallets to a user
      description: Add wallets to a user
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      requestBody:
        $ref: '#/components/requestBodies/UserV2AddWalletsBody'
      responses:
        '200':
          $ref: '#/components/responses/UserV2ObjectResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/users/{userId}/wallets/external:
    get:
      summary: Get external wallets for a user
      description: Get external wallets for a user
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/ExternalWalletsObjectResponse'
    post:
      summary: Add external wallets to a user
      description: Add external wallets to a user
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      requestBody:
        $ref: '#/components/requestBodies/AddExternalWalletsBody'
      responses:
        '200':
          $ref: '#/components/responses/ExternalWalletObjectResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/users/{userId}/wallets/external/{externalWalletId}:
    get:
      summary: Get an external wallet
      description: Get an external wallet
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      - $ref: '#/components/parameters/ExternalWalletIdPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/ExternalWalletObjectResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/users/{userId}/wallets/deposits:
    get:
      summary: Get inbound deposits
      description: Get inbound deposits for a user's wallet
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      - $ref: '#/components/parameters/ChainParameter'
      - $ref: '#/components/parameters/CryptoCurrencyParameter'
      - $ref: '#/components/parameters/WalletDepositStatusParameter'
      - $ref: '#/components/parameters/CreatedAfterParameter'
      - $ref: '#/components/parameters/CreatedBeforeParameter'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/MinAmountParameter'
      responses:
        '200':
          $ref: '#/components/responses/WalletDepositsObjectResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/users/{userId}/wallets/deposits/{depositId}:
    get:
      summary: Get an inbound deposit
      description: Get an inbound deposit for a user's wallet
      tags:
      - Wallet
      parameters:
      - $ref: '#/components/parameters/UserIdPathParameter'
      - $ref: '#/components/parameters/DepositIdPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/WalletDepositObjectResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  parameters:
    CryptoCurrencyParameter:
      name: currency
      in: query
      schema:
        type: string
        enum:
        - usdc
        - usdt
        - usdHifi
      description: The type of currency to check the balance for. Currently, only usdc is supported.
      required: true
    WalletDepositStatusParameter:
      name: status
      in: query
      schema:
        type: string
        enum:
        - CONFIRMED
        - COMPLETED
      description: Status of the deposit, CONFIRMED indicates the deposit is found in the blockchain, COMPLETED indicates the deposit is completed and unlikely to be reverted.
      required: false
    LimitParameter:
      name: limit
      in: query
      schema:
        type: string
        minimum: 1
        maximum: 100
      description: default to 10, maximum to 100
      required: false
    ExternalWalletIdPathParameter:
      name: externalWalletId
      in: path
      schema:
        type: string
      description: ID of the external wallet
      required: true
    MinAmountParameter:
      name: minAmount
      in: query
      schema:
        type: number
      description: Minimum amount of the deposit, default is 0.01
      required: false
    CreatedBeforeParameter:
      name: createdBefore
      in: query
      schema:
        type: string
        format: date
      description: 'ISO format: YYYY-MM-DD'
      required: false
    UserIdPathParameter:
      name: userId
      in: path
      schema:
        type: string
      description: ID of the user
      required: true
    ChainParameter:
      name: chain
      in: query
      schema:
        type: string
        enum:
        - POLYGON
        - ETHEREUM
        - SOLANA
        - BASE
      description: The blockchain network to retrieve the wallet balance from.
      required: true
    DepositIdPathParameter:
      name: depositId
      in: path
      schema:
        type: string
      description: ID of the deposit
      required: true
    CreatedAfterParameter:
      name: createdAfter
      in: query
      schema:
        type: string
        format: date
      description: 'ISO format: YYYY-MM-DD'
      required: false
  schemas:
    IndividualUserV2Object:
      type: object
      title: User Object (Individual)
      properties:
        id:
          type: string
          format: uuid
          description: User ID
        createdAt:
          type: string
          format: date-time
          description: Data and time when the user was created
        type:
          type: string
        email:
          type: string
        name:
          type: string
        wallets:
          type: object
          properties:
            INDIVIDUAL:
              type: object
              properties:
                ETHEREUM:
                  $ref: '#/components/schemas/WalletAddressObject'
                POLYGON:
                  $ref: '#/components/schemas/WalletAddressObject'
    ExternalWalletObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        chain:
          type: string
          enum:
          - POLYGON
          - SOLANA
          - ETHEREUM
          - BASE
        name:
          type: string
        address:
          type: string
        referenceId:
          type: string
        active:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
    WalletBalanceObject:
      type: object
      properties:
        balance:
          type: string
          description: The raw balance of the wallet expressed in the smallest denomination of the token. This format is ideal for backend calculations, automation processes, or when precise, unrounded figures are necessary for smart contract interactions. For example, use this when calculating transaction fees or performing token transfer operations that require exact values.
        displayBalance:
          type: string
          description: The wallet balance formatted as a decimal string for display purposes, adjusted according to the token's decimal places to facilitate human readability. This format is best used in user interfaces where balances are displayed to end-users, such as in wallet apps or dashboards, where readability and familiarity are crucial. For instance, displaying an account balance on a user's home screen or summary page.
        tokenInfo:
          type: object
          description: Detailed information about the token.
          properties:
            tokenAddress:
              type: string
              description: Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.
            standard:
              type: string
              enum:
              - ERC20
              - ERC721
              - ERC1155
            name:
              type: string
              description: Blockchain name of the specified token.
            symbol:
              type: string
              description: Blockchain symbol of the specified token.
            decimals:
              type: integer
              description: Number of decimal places shown in the token amount.
    ExternalWalletsObject:
      type: object
      properties:
        count:
          type: integer
        externalWallets:
          type: array
          items:
            $ref: '#/components/schemas/ExternalWalletObject'
        nextCursor:
          type: string
          description: The `createdAt` timestamp of the last record in the current page. Pass this as `createdBefore` in the next request to retrieve the next page of results.
    InternalServerError:
      type: object
      properties:
        error:
          type: string
          example: Unexpected error happened
    AddExternalWallets:
      type: object
      properties:
        address:
          type: string
          description: The wallet address to add
        chain:
          type: string
          enum:
          - POLYGON
          - SOLANA
          - ETHEREUM
          - BASE
          description: The blockchain network for this wallet
        name:
          type: string
          description: Name for the wallet
        referenceId:
          type: string
          description: A custom reference ID for the wallet
      required:
      - address
      - chain
      - name
      - referenceId
    WalletAddressObject:
      type: object
      properties:
        address:
          type: string
          description: Wallet address
      required:
      - address
    BusinessUserV2Object:
      type: object
      title: User Object (Business)
      properties:
        id:
          type: string
          format: uuid
          description: User ID
        createdAt:
          type: string
          format: date-time
          description: Data and time when the user was created
        type:
          type: string
        email:
          type: string
        name:
          type: string
        wallets:
          type: object
          properties:
            INDIVIDUAL:
              type: object
              properties:
                ETHEREUM:
                  $ref: '#/components/schemas/WalletAddressObject'
                POLYGON:
                  $ref: '#/components/schemas/WalletAddressObject'
    WalletDepositsObject:
      type: object
      properties:
        count:
          type: integer
        deposits:
          type: array
          items:
            $ref: '#/components/schemas/WalletDepositObject'
        nextCursor:
          type: string
          description: The `createdAt` timestamp of the last record in the current page. Pass this as `createdBefore` in the next request to retrieve the next page of results.
    UserV2AddWallets:
      type: object
      properties:
        chains:
          type: array
          items:
            type: string
            description: The chains to create wallets for.
            enum:
            - POLYGON
            - SOLANA
            - ETHEREUM
            - BASE
      required:
      - chains
    Unauthorized:
      type: object
      properties:
        error:
          type: string
          example: Not authorized
    WalletDepositObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        wallet:
          type: object
          properties:
            id:
              type: string
              format: uuid
            address:
              type: string
            chain:
              type: string
              enum:
              - POLYGON
              - SOLANA
              - ETHEREUM
              - BASE
            walletType:
              type: string
              enum:
              - INDIVIDUAL
        transaction:
          type: object
          properties:
            transactionHash:
              type: string
            chain:
              type: string
              enum:
              - POLYGON
              - SOLANA
              - ETHEREUM
              - BASE
            currency:
              type: string
            status:
              type: string
              enum:
              - COMPLETED
              - CONFIRMED
            sourceAddress:
              type: string
            destinationAddress:
              type: string
            contractAddress:
              type: string
            amount:
              type: string
            unitAmount:
              type: string
  examples:
    WalletDepositObjectExample:
      summary: Wallet Deposit Object
      value:
        userId: f4c99c2f-ce05-4f61-8ed6-9064a5689197
        id: 2e084846-00d6-5e4c-806f-eac45e197108
        createdAt: '2025-06-25T15:47:16.983978+00:00'
        updatedAt: '2025-06-25T15:47:16.983978+00:00'
        wallet:
          id: 24b4917d-694e-4d81-ace8-9ba5261b6f4e
          address: '0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef'
          chain: POLYGON
          walletType: INDIVIDUAL
        transaction:
          transactionHash: '0xe5284c4cb35ae9b5eb0ae23b840032f320b87b63f8967ee9b67ee09dfe6a194a'
          chain: POLYGON
          currency: usdc
          status: COMPLETED
          sourceAddress: '0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef'
          destinationAddress: '0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef'
          contractAddress: '0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582'
          amount: '19'
          unitAmount: '19000000'
    UserObjectIndividualExample:
      summary: User Object (Individual)
      value:
        id: 4d93ab4f-3983-4ac0-8c97-54bbc0f287fa
        createdAt: '2025-09-24T19:12:20.541Z'
        type: individual
        email: john.doe@hifibridge.com
        name: John Doe
        wallets:
          INDIVIDUAL:
            ETHEREUM:
              address: '0x43B343Bb48E23F58406271131B71448fF95787AD'
            POLYGON:
              address: '0x43B343Bb48E23F58406271131B71448fF95787AD'
    UserObjectBusinessExample:
      summary: User Object (Business)
      value:
        id: 264484e0-979a-5fa3-9335-947f55e5999a
        createdAt: '2025-09-24T19:03:41.107Z'
        type: business
        email: admin@randombizz.com
        name: Random Bizz
        wallets:
          INDIVIDUAL:
            ETHEREUM:
              address: '0x2f78AEFA879819D7a5C9a87fE8BF5e7B961f5500'
            POLYGON:
              address: '0x2f78AEFA879819D7a5C9a87fE8BF5e7B961f5500'
    ExternalWalletObjectListExample:
      summary: External Wallet Object List
      value:
        count: 1
        externalWallets:
        - address: '0xFE5ea74612ba174BaF7FC4C45f05dB7fF73aBA21'
          chain: POLYGON
          name: my-wallet
          referenceId: my-wallet-reference-id
          createdAt: '2025-09-24T19:03:41.107Z'
        nextCursor: '2025-09-24T19:03:41.107Z'
    WalletBalanceObjectExample:
      summary: Wallet Balance Object
      value:
        balance: '0'
        displayBalance: '0'
        tokenInfo:
          tokenAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582'
          standard: ERC20
          name: USDC
          symbol: USDC
          decimals: 6
    ExternalWalletObjectExample:
      summary: External Wallet Object
      value:
        address: '0xFE5ea74612ba174BaF7FC4C45f05dB7fF73aBA21'
        chain: POLYGON
        name: my-wallet
        referenceId: my-wallet-reference-id
        createdAt: '2025-09-24T19:03:41.107Z'
    WalletDepositObjectListExample:
      summary: Wallet Deposit Object List
      value:
        count: 1
        records:
        - userId: f4c99c2f-ce05-4f61-8ed6-9064a5689197
          id: 2e084846-00d6-5e4c-806f-eac45e197108
          createdAt: '2025-06-25T15:47:16.983978+00:00'
          updatedAt: '2025-06-25T15:47:16.983978+00:00'
          wallet:
            id: 24b4917d-694e-4d81-ace8-9ba5261b6f4e
            address: '0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef'
            chain: POLYGON
            walletType: INDIVIDUAL
          transaction:
            transactionHash: '0xe5284c4cb35ae9b5eb0ae23b840032f320b87b63f8967ee9b67ee09dfe6a194a'
            chain: POLYGON
            currency: usdc
            status: COMPLETED
            sourceAddress: '0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef'
            destinationAddress: '0x0B95D270400BE4319EAFbfDD82F6C38B59ab54Ef'
            contractAddress: '0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582'
            amount: '19'
            unitAmount: '19000000'
        nextCursor: '2025-06-25T15:47:16.983978+00:00'
  responses:
    WalletDepositObjectResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletDepositObject'
          examples:
            WalletDepositObjectExample:
              $ref: '#/components/examples/WalletDepositObjectExample'
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    UserV2ObjectResponse:
      description: Success
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/IndividualUserV2Object'
            - $ref: '#/components/schemas/BusinessUserV2Object'
          examples:
            UserObjectIndividualExample:
              $ref: '#/components/examples/UserObjectIndividualExample'
            UserObjectBusinessExample:
              $ref: '#/components/examples/UserObjectBusinessExample'
    WalletDepositsObjectResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletDepositsObject'
          examples:
            WalletDepositObjectListExample:
              $ref: '#/components/examples/WalletDepositObjectListExample'
    ExternalWalletObjectResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalWalletObject'
          examples:
            ExternalWalletObjectExample:
              $ref: '#/components/examples/ExternalWalletObjectExample'
    WalletBalanceResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletBalanceObject'
          examples:
            WalletBalanceObjectExample:
              $ref: '#/components/examples/WalletBalanceObjectExample'
    ExternalWalletsObjectResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalWalletsObject'
          examples:
            ExternalWalletObjectListExample:
              $ref: '#/components/examples/ExternalWalletObjectListExample'
  requestBodies:
    AddExternalWalletsBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddExternalWallets'
    UserV2AddWalletsBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserV2AddWallets'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT