API Documentation

Use this API to integrate the Hypertrade Aggregator on HyperEVM.

Base URL: https://core.ht.xyz/api/v1/trade

Authentication

Most endpoints do not require authentication. Endpoints that require a JWT are explicitly marked below.

Response Format

All endpoints return JSON responses. HTTP status codes are returned in the response headers.

All response fields use camelCase.

Examples:

token_in → tokenIn
amount_out → amountOut
created_at → createdAt

Swap statuses are returned as strings:

pending
processing
completed
cancelled
failed

Get Tokens

GET /tokens

Returns all available tokens as a map keyed by token address.

Request

This endpoint does not require any parameters.

Successful Response

{
  "tokens": {
    "0xb88339cb7199b77e23db6e890353e22632ba630f": {
      "symbol": "USDC",
      "name": "USDC",
      "address": "0xb88339cb7199b77e23db6e890353e22632ba630f",
      "decimals": 6,
      "logoURI": "https://assets.coingecko.com/coins/images/6319/standard/usdc.png",
      "coinId": "0xb88339cb7199b77e23db6e890353e22632ba630f_USDC",
      "price": "1.001753841",
      "type": "evm",
      "volumeUsd24": "0.000000"
    },
    "0x0d01dc56dcaaca66ad901c959b4011ec": {
      "symbol": "HYPE",
      "name": "Hyperliquid",
      "address": "0x0d01dc56dcaaca66ad901c959b4011ec",
      "decimals": 8,
      "logoURI": "https://coin-images.coingecko.com/coins/images/50882/small/hyperliquid.jpg",
      "coinId": "0x0d01dc56dcaaca66ad901c959b4011ec",
      "price": "36.229",
      "evmAddress": "0x0000000000000000000000000000000000000000",
      "coinIndex": 150,
      "coinTo": "0x54e00a5988577cb0b0c9ab0cb6ef7f4b",
      "type": "core",
      "volumeUsd24": "37753946.74"
    }
  }
}

Token Fields

Field

Type

Description

symbol

string

Token ticker.

name

string

Token name.

address

string

Token address. 42 characters for EVM tokens, 34 characters for Core tokens.

decimals

number

Token decimals.

logoURI

string

Token logo URL.

coinId

string

Internal token identifier.

price

string

Current USD price.

type

string

Token type: evm or core.

volumeUsd24

string

24h trading volume in USD.

priceDelta24

number

24h price change. EVM only.

evmAddress

string

Paired EVM address. Core only.

coinIndex

number

Core token index for spot send. Core only.

coinTo

string

Core token pair filter. Core only.

Get Quote

GET /quote

Returns a swap quote without creating a swap order.

Query Parameters

Parameter

Type

Required

Description

src

string

Yes

Source token address.

dst

string

Yes

Destination token address.

amount

string

Yes

Input token amount in the smallest token unit.

slippage

number

Yes

Maximum slippage tolerance. Allowed range: 0.01 to 20.

referrerAddress

string

Referrer wallet address for fee sharing.

fee

number

Integrator fee amount, specified in basis points (bps), to be charged from the swap by the caller.

includeHyperCore

boolean

Enables Hyperliquid Core routing. Default: false.

onlyOurDex

boolean

Routes only through Hypertrade DEX. Default: false.

receiver

string

Yes

Receiver is the wallet address that should receive the output tokens

Example Request

GET /api/v1/trade/quote?src=0x0000000000000000000000000000000000000000&dst=0xeb62eee3685fc5bb2b0d35c4c92609101426cdee&receiver=0x21f1cd2E4c1e50A684Ae75a76576c53b1A5D6876&amount=1000000000000000000&slippage=0.3

Successful Response

{
  "srcToken": {
    "symbol": "WHYPE",
    "name": "Wrapped HYPE",
    "address": "0x0000000000000000000000000000000000000000",
    "decimals": 18,
    "logoURI": "https://example.com/whype.png"
  },
  "dstToken": {
    "symbol": "USDC",
    "name": "USD Coin",
    "address": "0xeb62eee3685fc5bb2b0d35c4c92609101426cdee",
    "decimals": 6,
    "logoURI": "https://example.com/usdc.png"
  },
  "toAmount": "25.123456",
  "protocols": [
    {
      "inputTokenAddress": "0x000...000",
      "outputTokenAddress": "0xeb6...dee",
      "splits": [
        {
          "dex": "HyperSwap",
          "portion": 1.0,
          "fee": 3000,
          "poolAddress": "0x..."
        }
      ]
    }
  ],
  "gas": 0,
  "action": "evm",
  "routeCore": {
    "path": [],
    "pathIndexes": []
  },
  "economy": "0.5",
  "fee": "0.25"
}

Error Response

{
  "error": "src and dst tokens must be different",
  "statusCode": 400
}

Possible Errors

the 'src' parameter cannot be empty
the 'dst' parameter cannot be empty
the 'amount' parameter cannot be empty
the 'slippage' parameter cannot be empty
slippage must be >= 0.01 && <= 20
token_from not found
token_to not found
token_from and token_to must be different
amount must be > 0
swap path not found
core swap must have minimum value of $15
core swap must have maximum value of $500000

Create Swap

GET /swap

Creates a swap order and returns transaction data for signing.

Query Parameters

Parameter

Type

Required

Description

src

string

Yes

Source token address.

dst

string

Yes

Destination token address.

amount

string

Yes

Input token amount in the smallest token unit.

slippage

number

Yes

Maximum slippage tolerance. Allowed range: 0.01 to 20.

from

string

Yes

Sender wallet address.

receiver

string

Recipient wallet address. Default: zero address.

referrerAddress

string

Referrer wallet address for fee sharing.

fee

number

Integration fee in basis points.

includeHyperCore

boolean

Enables Hyperliquid Core routing. Default: false.

onlyOurDex

boolean

Routes only through Hypertrade DEX. Default: false.

integrator_id

string

Name of the API integrator, who uses API.

Example Request

GET /api/v1/trade/swap?src=0x0000000000000000000000000000000000000000&dst=0xeb62eee3685fc5bb2b0d35c4c92609101426cdee&amount=1000000000000000000&slippage=0.3&from=0x82Cbe7fCeEdBB2efa107Afc91184937De0d703c3

Successful Response

{
  "srcToken": {
    "symbol": "WHYPE",
    "name": "Wrapped HYPE",
    "address": "0x0000000000000000000000000000000000000000",
    "decimals": 18,
    "logoURI": "https://example.com/whype.png"
  },
  "dstToken": {
    "symbol": "USDC",
    "name": "USD Coin",
    "address": "0xeb62eee3685fc5bb2b0d35c4c92609101426cdee",
    "decimals": 6,
    "logoURI": "https://example.com/usdc.png"
  },
  "toAmount": "25.123456",
  "tx": {
    "from": "0x82cbe7fceedbb2efa107afc91184937de0d703c3",
    "to": "0xe4609ab5F4c268C42BA470FbCBB9b9aBF895f1a5",
    "data": "0xabc123...calldata",
    "value": "1000000000000000000",
    "gas": 0
  },
  "protocols": [],
  "action": "evm",
  "routeCore": {
    "path": [],
    "pathIndexes": []
  },
  "swap": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "wallet": "0x82cbe7fceedbb2efa107afc91184937de0d703c3",
    "recipient": "0x0000000000000000000000000000000000000000",
    "tokenIn": "0x0000000000000000000000000000000000000000",
    "tokenOut": "0xeb62eee3685fc5bb2b0d35c4c92609101426cdee",
    "amountIn": "1000000000000000000",
    "amountOut": "25.123456",
    "status": "pending",
    "usdAmount": "25.12",
    "feeGas": "0.01",
    "depositEvmTxHash": "",
    "depositCoreTxHash": "",
    "slippage": 0.3,
    "integrationFeeAddress": "0x0000000000000000000000000000000000000000",
    "integrationFeeBps": 0,
    "route": "evm",
    "onlyOurDex": 0,
    "createdAt": "2026-04-06T12:00:00Z",
    "updatedAt": "2026-04-06T12:00:00Z"
  }
}

Swap Flow

Call GET /swap with the required parameters.
Receive the tx object in the response.
Sign the transaction using tx.to, tx.data, and tx.value.
Submit the signed transaction to the blockchain.
The backend tracks the swap status automatically.
Poll GET /swap/status?id=...&wallet=... to retrieve the latest swap status.

Swap Statuses

Status

Description

pending

Waiting for the user transaction.

processing

Transaction confirmed, backend is processing the swap.

completed

Swap completed successfully.

cancelled

Swap was cancelled.

failed

Swap failed.

Additional Errors

All /quote errors may also be returned here.

In addition, this endpoint may return:

the limit of undeposited maximum open swap orders has been exceeded

Get Swap Status

GET /swap/status

Returns swap details by swap ID.

Query Parameters

Parameter

Type

Required

Description

id

string

Yes

Swap UUID.

wallet

string

Yes

User wallet address.

Example Request

GET /api/v1/trade/swap/status?id=550e8400-e29b-41d4-a716-446655440000&wallet=0x82Cbe7fCeEdBB2efa107Afc91184937De0d703c3

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "wallet": "0x82cbe7fceedbb2efa107afc91184937de0d703c3",
  "recipient": "0x0000000000000000000000000000000000000000",
  "tokenIn": "0x0000000000000000000000000000000000000000",
  "tokenOut": "0xeb62eee3685fc5bb2b0d35c4c92609101426cdee",
  "amountIn": "1000000000000000000",
  "amountOut": "25.123456",
  "status": "completed",
  "usdAmount": "25.12",
  "feeGas": "0.01",
  "depositEvmTxHash": "0xabc123...",
  "depositCoreTxHash": "",
  "slippage": 0.3,
  "integrationFeeAddress": "0x0000000000000000000000000000000000000000",
  "integrationFeeBps": 0,
  "route": "evm",
  "onlyOurDex": 0,
  "createdAt": "2026-04-06T12:00:00Z",
  "updatedAt": "2026-04-06T12:01:00Z"
}

Possible Errors

id is required
wallet is required
invalid swap ID format
swap not found

Get Swap History

GET /swap/history

Returns paginated swap history.

Authentication required: Authorization: Bearer <token>

Query Parameters

Parameter

Type

Required

Description

status

number

Filter by swap status.

offset

number

Page number. Default: 1.

size

number

Page size. Default: 10. Maximum: 100.

Example Request

GET /api/v1/trade/swap/history?status=5&offset=1&size=10
Authorization: Bearer <jwt_token>

Successful Response

{
  "swaps": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "wallet": "0x82cbe7fceedbb2efa107afc91184937de0d703c3",
      "tokenIn": "0x0000000000000000000000000000000000000000",
      "tokenOut": "0xeb62eee3685fc5bb2b0d35c4c92609101426cdee",
      "amountIn": "1000000000000000000",
      "amountOut": "25.123456",
      "status": "completed",
      "route": "evm",
      "createdAt": "2026-04-06T12:00:00Z",
      "updatedAt": "2026-04-06T12:01:00Z"
    }
  ],
  "totalCount": 42
}

Possible Errors

Unauthorized, invalid or expired token
page must be greater than 0
size should be between 1 and 100

Cancel Swap

GET /swap/cancel

Cancels a pending swap.

Only swaps in the initial pending state can be cancelled.

Query Parameters

Parameter

Type

Required

Description

id

string

Yes

Swap UUID.

wallet

string

Yes

User wallet address.

Example Request

GET /api/v1/trade/swap/cancel?id=550e8400-e29b-41d4-a716-446655440000&wallet=0x82Cbe7fCeEdBB2efa107Afc91184937De0d703c3

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "wallet": "0x82cbe7fceedbb2efa107afc91184937de0d703c3",
  "status": "cancelled",
  "createdAt": "2026-04-06T12:00:00Z",
  "updatedAt": "2026-04-06T12:05:00Z"
}

Possible Errors

id is required
wallet is required
invalid swap ID format
swap not found
swap status must be undeposited(0)

Migration Guide

If you are migrating from the previous API version, use the following endpoint mapping.

`POST /getSwapInfo` → `GET /quote`

Changes:

inputTokenAddress → src
outputTokenAddress → dst
inputAmount → amount
feeAddress → referrerAddress
feeBps → fee
enableHyperCore → includeHyperCore

`POST /swap` → `GET /swap`

Changes:

same parameter renames as above
userAddress → from
recipientAddress → receiver

`GET /getTokens` → `GET /tokens`

Changes:

response changed from array to tokens map
fields renamed to camelCase

`GET /getSwapById?id=...&wallet=...` → `GET /swap/status?id=...&wallet=...`

Changes:

response fields renamed to camelCase

`GET /getSwapHistory?status=...` → `GET /swap/history?status=...`

Changes:

response fields renamed to camelCase
total_count → totalCount

`GET /closeSwapById?id=...&wallet=...` → `GET /swap/cancel?id=...&wallet=...`

Changes:

response fields renamed to camelCase

PreviousAPI NextAggregator Fees

Last updated 2 days ago

Authentication

Response Format

Get Tokens

Request

Successful Response

Token Fields

Get Quote

Query Parameters

Example Request

Successful Response

Error Response

Possible Errors

Create Swap

Query Parameters

Example Request

Successful Response

Swap Flow

Swap Statuses

Additional Errors

Get Swap Status

Query Parameters

Example Request

Successful Response

Possible Errors

Get Swap History

Query Parameters

Example Request

Successful Response

Possible Errors

Cancel Swap

Query Parameters

Example Request

Successful Response

Possible Errors

Migration Guide

POST /getSwapInfo → GET /quote

POST /swap → GET /swap

GET /getTokens → GET /tokens

GET /getSwapById?id=...&wallet=... → GET /swap/status?id=...&wallet=...

GET /getSwapHistory?status=... → GET /swap/history?status=...

GET /closeSwapById?id=...&wallet=... → GET /swap/cancel?id=...&wallet=...

`POST /getSwapInfo` → `GET /quote`

`POST /swap` → `GET /swap`

`GET /getTokens` → `GET /tokens`

`GET /getSwapById?id=...&wallet=...` → `GET /swap/status?id=...&wallet=...`

`GET /getSwapHistory?status=...` → `GET /swap/history?status=...`

`GET /closeSwapById?id=...&wallet=...` → `GET /swap/cancel?id=...&wallet=...`