openapi: 3.0.0
info:
  title: Hifi Account Token Swap 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: Token Swap
  description: Token Swap endpoints
paths:
  /v2/wallets/swaps:
    post:
      summary: Create a swap
      description: 'Create a swap request to exchange one cryptocurrency for another within the same chain.

        '
      tags:
      - Token Swap
      requestBody:
        $ref: '#/components/requestBodies/CreateWalletSwapBody'
      responses:
        '200':
          $ref: '#/components/responses/WalletSwapResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    get:
      summary: List all swaps
      description: 'Returns a list of swaps associated with a user under your organization. The swaps are returned sorted by creation date, with the most recent swaps appearing first.

        '
      tags:
      - Token Swap
      parameters:
      - $ref: '#/components/parameters/UserIdOptionalParameter'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/CreatedBeforeParameter'
      - $ref: '#/components/parameters/CreatedAfterParameter'
      responses:
        '200':
          $ref: '#/components/responses/WalletSwapAllRecordsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/wallets/swaps/{swapId}:
    get:
      summary: Retrieve a swap
      description: 'Retrieve details of a specific swap by its ID.

        '
      tags:
      - Token Swap
      parameters:
      - $ref: '#/components/parameters/SwapTransferIDPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/WalletSwapResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/wallets/swaps/{swapId}/accept:
    post:
      summary: Accept a swap
      description: 'Accept a swap request to execute the cryptocurrency exchange.

        '
      tags:
      - Token Swap
      parameters:
      - $ref: '#/components/parameters/SwapTransferIDPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/WalletSwapResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  schemas:
    WalletSwapDetailsObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: dc923cc1-d74b-58f6-9fe4-9e9c6eb8dc37
        requestId:
          type: string
          format: uuid
          example: 1ab3e6e0-4839-4dbe-89c3-b06d9645ae86
        status:
          type: string
          enum:
          - PENDING
          - COMPLETED
          - FAILED
          - CANCELLED
          example: COMPLETED
        createdAt:
          type: string
          format: date-time
          example: '2025-08-20T03:55:29.437108+00:00'
        updatedAt:
          type: string
          format: date-time
          example: '2025-08-20T04:08:10.837+00:00'
        source:
          $ref: '#/components/schemas/WalletSwapSourceObject'
        destination:
          $ref: '#/components/schemas/WalletSwapDestinationObject'
        error:
          type: string
          nullable: true
          example: null
        errorDetails:
          type: string
          nullable: true
          example: null
        quoteInformation:
          $ref: '#/components/schemas/WalletSwapQuoteInformationObject'
        billingInformation:
          $ref: '#/components/schemas/WalletSwapBillingInformationObject'
    WalletSwapAmountObject:
      type: object
      properties:
        amount:
          type: string
          example: '10'
        currency:
          type: string
          example: usdc
    WalletSwapFeeObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 2ca381ec-9498-52f5-9a27-d0e392b2626b
        amount:
          type: number
          example: 0.01
        currency:
          type: string
          example: USD
        type:
          type: string
          enum:
          - EXCHANGE_FEE
          - GAS_FEE
          example: EXCHANGE_FEE
        timing:
          type: string
          enum:
          - ON_INVOICE
          - ON_TRANSACTION
          example: ON_INVOICE
    WalletSwapDestinationObject:
      type: object
      properties:
        currency:
          type: string
          example: usdt
        userId:
          type: string
          format: uuid
          example: 05179f69-1988-4b46-a847-dd4eea0984d6
        externalWalletId:
          type: string
          format: uuid
          nullable: true
          example: null
        amount:
          type: number
          nullable: true
          example: null
        chain:
          type: string
          example: POLYGON
        walletAddress:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          example: '0xe5727a4B1d93A26D6A7Adfaae145EFa41ED7f204'
    InternalServerError:
      type: object
      properties:
        error:
          type: string
          example: Unexpected error happened
    WalletSwapBillingInformationObject:
      type: object
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/WalletSwapFeeObject'
    WalletSwapQuoteInformationObject:
      type: object
      properties:
        sendGross:
          $ref: '#/components/schemas/WalletSwapAmountObject'
        sendNet:
          $ref: '#/components/schemas/WalletSwapAmountObject'
        receiveGross:
          $ref: '#/components/schemas/WalletSwapAmountObject'
        receiveNet:
          $ref: '#/components/schemas/WalletSwapAmountObject'
        rate:
          type: string
          example: '1'
        expiresAt:
          type: string
          format: date-time
          example: '2025-08-20T03:55:59.539+00:00'
    WalletSwapAllRecordsObject:
      type: object
      properties:
        count:
          type: integer
          example: 1
        data:
          type: array
          items:
            $ref: '#/components/schemas/WalletSwapObject'
        nextCursor:
          type: string
          format: date-time
          example: '2025-08-20T04:08:10.837+00:00'
    WalletSwapObject:
      type: object
      properties:
        transferType:
          type: string
          example: WALLET.SWAP
        transferDetails:
          $ref: '#/components/schemas/WalletSwapDetailsObject'
    Unauthorized:
      type: object
      properties:
        error:
          type: string
          example: Not authorized
    CreateWalletSwap:
      type: object
      required:
      - requestId
      - source
      - destination
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique identifier for the swap request (recommend using uuid v4)
          example: 1ab3e6e0-4839-4dbe-89c3-b06d9645ae86
        source:
          type: object
          description: Source wallet information for the swap
          required:
          - userId
          - chain
          - currency
          properties:
            userId:
              type: string
              format: uuid
              description: User ID of the source wallet owner
              example: 05179f69-1988-4b46-a847-dd4eea0984d6
            chain:
              type: string
              enum:
              - POLYGON
              - ETHEREUM
              - SOLANA
              description: Blockchain network for the source wallet
              example: POLYGON
            currency:
              type: string
              enum:
              - usdc
              - usdt
              description: Source cryptocurrency to swap from
              example: usdt
            amount:
              type: string
              description: Amount to swap (either source.amount or destination.amount must be provided)
              example: '10000'
        destination:
          type: object
          description: Destination wallet information for the swap
          required:
          - chain
          - currency
          properties:
            userId:
              type: string
              format: uuid
              description: User ID of the destination wallet owner
              example: 05179f69-1988-4b46-a847-dd4eea0984d6
            externalWalletId:
              type: string
              format: uuid
              description: External wallet ID (Exclude with userId)
              example: 64fc4e9d-4839-4384-b4a0-0376af2c9b2e
            walletAddress:
              type: string
              pattern: ^0x[a-fA-F0-9]{40}$
              description: Wallet address (Exclude with userId)
              example: '0xE9cfBf1D690565579D823264170eE357f80e9A34'
            chain:
              type: string
              enum:
              - POLYGON
              - ETHEREUM
              - SOLANA
              description: Blockchain network for the destination wallet
              example: POLYGON
            currency:
              type: string
              enum:
              - usdc
              - usdt
              - usdg
              description: Destination cryptocurrency to swap to
              example: usdc
            amount:
              type: string
              description: Amount to receive (either source.amount or destination.amount must be provided)
              example: '10000'
    WalletSwapSourceObject:
      type: object
      properties:
        currency:
          type: string
          example: usdc
        amount:
          type: number
          example: 10
        chain:
          type: string
          example: POLYGON
        userId:
          type: string
          format: uuid
          example: 05179f69-1988-4b46-a847-dd4eea0984d6
  parameters:
    LimitParameter:
      name: limit
      in: query
      schema:
        type: string
        minimum: 1
        maximum: 100
      description: default to 10, maximum to 100
      required: false
    SwapTransferIDPathParameter:
      name: swapId
      in: path
      schema:
        type: string
      description: Swap transfer record ID.
      required: true
    UserIdOptionalParameter:
      name: userId
      in: query
      schema:
        type: string
      description: The user ID.
      required: false
    CreatedBeforeParameter:
      name: createdBefore
      in: query
      schema:
        type: string
        format: date
      description: 'ISO format: YYYY-MM-DD'
      required: false
    CreatedAfterParameter:
      name: createdAfter
      in: query
      schema:
        type: string
        format: date
      description: 'ISO format: YYYY-MM-DD'
      required: false
  responses:
    WalletSwapResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletSwapObject'
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    NotFoundResponse:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    WalletSwapAllRecordsResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletSwapAllRecordsObject'
  requestBodies:
    CreateWalletSwapBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateWalletSwap'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT