# 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

```json
{
  "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`  | No       | Referrer wallet address for fee sharing.                   |
| `fee`              | `number`  | No       | Integration fee in basis points.                           |
| `includeHyperCore` | `boolean` | No       | Enables Hyperliquid Core routing. Default: `false`.        |
| `onlyOurDex`       | `boolean` | No       | Routes only through Hypertrade DEX. Default: `false`.      |

### Example Request

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

### Successful Response

```json
{
  "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

```json
{
  "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`  | No       | Recipient wallet address. Default: zero address.           |
| `referrerAddress`  | `string`  | No       | Referrer wallet address for fee sharing.                   |
| `fee`              | `number`  | No       | Integration fee in basis points.                           |
| `includeHyperCore` | `boolean` | No       | Enables Hyperliquid Core routing. Default: `false`.        |
| `onlyOurDex`       | `boolean` | No       | Routes only through Hypertrade DEX. Default: `false`.      |

### Example Request

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

### Successful Response

```json
{
  "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",
    "feeOur": "0.25",
    "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

1. Call `GET /swap` with the required parameters.
2. Receive the `tx` object in the response.
3. Sign the transaction using `tx.to`, `tx.data`, and `tx.value`.
4. Submit the signed transaction to the blockchain.
5. The backend tracks the swap status automatically.
6. 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

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

### Successful Response

```json
{
  "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",
  "feeOur": "0.25",
  "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` | No       | Filter by swap status.                    |
| `offset`  | `number` | No       | Page number. Default: `1`.                |
| `size`    | `number` | No       | Page size. Default: `10`. Maximum: `100`. |

### Example Request

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

### Successful Response

```json
{
  "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

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

### Successful Response

```json
{
  "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ht.xyz/hypertrade-aggregator/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.