OpenAPI Specification
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