> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperswap.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Endpoints
> Hyperswap AI will offer a powerful API for developers to integrate seamlessly, AI-powered crypto swaps into their applications.
The API is currently in testing phase. If you need early access please contact us.
Enterprise users of integrations can swap at the same rate as directly on the [HyperSwap.ai](http://hyperswap.ai) website; the 0.5% commission will not be added on top of API swaps.
### **Features of the API**
* **AI-Powered Smart Routing**: Finds the best liquidity pools for minimal slippage.
* **Multi-Chain Support**: Works across Ethereum, Solana, Bitcoin and other 72+ popular chains supporting more than 15000 assets across those chains.
* **Real-Time Exchange Rates**: Fetch live rates optimized by AI.
* **Swap Execution**: Initiate crypto swaps directly via API.
* **Transaction Monitoring**: Track swap status with webhooks.
## API Endpoints # Hyperswap API Endpoints Documentation
This document provides a comprehensive overview of the public API endpoints for Hyperswap, detailing their functionality, parameters, responses, and important considerations for integration.
## Base URL
All API endpoints are relative to the following base URL:
`https://api.hyperswap.ai`
## Authentication
All API endpoints require authentication using an API key.
* **API Key Issuance:** API keys are issued manually to clients.
* **Sign-Up:** To request an API key and become a client, please sign up at: [https://www.hyperswap.ai/partner-request](https://www.hyperswap.ai/partner-request)
* **Usage:** Once you have an API key, include it in the `Authorization` header of your requests as a Bearer token:
`Authorization: Bearer YOUR_API_KEY`
## Available Values and Data Sources
This section explains how to obtain the dynamic values required for certain API parameters and lists fixed possible values for others.
### Chain IDs (`chainId`)
Chain IDs represent different blockchains supported by Hyperswap.
* **Source:** These can be obtained by calling the `/api/v1/assets` endpoint. Each `StandardizedAsset` object in the response includes a `chainId` field.
* **Format:** Chain IDs can be numerical (for EVM chains) or string identifiers (for non-EVM chains).
* **Examples:**
* **EVM Chains (Numerical):** `1` (Ethereum), `56` (BNB Chain), `137` (Polygon), `42161` (Arbitrum One), `10` (Optimism), `8453` (Base), `43114` (Avalanche), `25` (Cronos), `324` (ZkSync Era), `59144` (Linea).
* **Non-EVM Chains (String Identifiers/Internal Mappings):** `'1151111081099710'` (Solana), `'20000000000001'` (Bitcoin), `'9270000000000000'` (Sui), `'TRON'` (Tron), `'TON'` (TON), `'APTOS'` (Aptos), `'ALGORAND'` (Algorand), `'BITTENSOR'` (Bittensor), `'CARDANO'` (Cardano), `'CELESTIA'` (Celestia), `'COSMOS'` (Cosmos), `'DASH'` (Dash), `'DOGE'` (Dogecoin), `'HEDERA'` (Hedera), `'ICP'` (Internet Computer), `'LITECOIN'` (Litecoin), `'MANTLE'` (Mantle), `'POLKADOT'` (Polkadot), `'RIPPLE'` (Ripple), `'RONIN'` (Ronin), `'STACKS'` (Stacks), `'STELLAR'` (Stellar), `'XEC'` (eCash), `'BCH'` (Bitcoin Cash), `'LIQUID'` (Liquid), `'HYPEREVM'` (Hyperevm), `'SONIC'` (Sonic), `'BLAST'` (Blast), `'SCROLL'` (Scroll), `'FETCH'` (Fetch).
* **Note:** The `chainName` and `chainLogoUrl` fields in the asset response can help identify the human-readable name and logo for each chain. For the most current list of supported chains, always query the `/api/v1/assets` endpoint.
### Token Addresses (`fromToken`, `toToken`)
Token addresses identify specific crypto assets on a given blockchain.
* **Source:** These are obtained by calling the `/api/v1/assets` endpoint. Each `StandardizedAsset` object includes an `address` field, which represents the token's contract address on its respective `chainId`.
* **Native Tokens:** For native blockchain tokens (e.g., ETH on Ethereum, BTC on Bitcoin, SOL on Solana, SUI on Sui), specific normalized addresses are used:
* **EVM Native:** `0x0000000000000000000000000000000000000000`
* **Bitcoin:** `'bitcoin'`
* **Solana:** `'11111111111111111111111111111111'`
* **Sui:** `'0x2::sui::SUI'`
* **Note:** The `symbol` and `name` fields in the asset response provide human-readable identifiers for the tokens.
### Preference (`preference`)
This parameter allows specifying the desired optimization for a quote.
* **Possible Values:**
* `'fastest'`: Prioritizes quotes with the quickest estimated completion time.
* `'lowest_cost'`: Prioritizes quotes with the lowest estimated fees.
### Transaction Statuses (`status`)
These are the possible states for a swap transaction.
* **Possible Values:**
* `PENDING`: The transaction has been initiated but is awaiting further action (e.g., user deposit for hyperswapshift, user signature for hyperswap).
* `IN_PROGRESS`: The swap is actively being processed by the liquidity provider.
* `COMPLETED`: The swap has successfully finished, and funds have been settled.
* `FAILED`: The swap encountered an unrecoverable error.
* `REFUNDED`: The swap failed, and funds have been returned to the refund address.
***
## API Endpoints
### 1. Get All Assets
`GET /api/v1/assets`
* **Description:** Fetches a comprehensive list of standardized crypto assets supported by the platform, aggregating data from hyperswap and hyperswapshift. This endpoint is essential for populating token selection interfaces and understanding available assets.
* **Query Parameters:**
* `chainId` (optional, `string | number`): Filters the returned assets to a specific blockchain.
* **`Response (JSON Array of StandardizedAsset objects):`**
```json theme={null}
[
{
"source": "hyperswap",
"name": "Wrapped Ether",
"symbol": "WETH",
"chainId": 1,
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"decimals": 18,
"logoUrl": "https://hyperswap.ai/tokenLogos/weth.svg",
"chainLogoUrl": "/icons/chains/ethereum.svg",
"chainName": "Ethereum",
"priceUsd": 3500.50,
"swappable": true,
"providerId": {
"hyperswap_provider": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
},
"priorityOrder": 4,
"isPriorityToken": true
},
{
"source": "hyperswap",
"name": "Bitcoin",
"symbol": "BTC",
"chainId": "20000000000001",
"address": "bitcoin",
"decimals": 8,
"logoUrl": "https://hyperswap.ai/assets/coins/btc.svg",
"chainLogoUrl": "/icons/chains/bitcoin.svg",
"chainName": "Bitcoin",
"priceUsd": null,
"swappable": true,
"providerId": {
"hyperswapshift": "btc-bitcoin"
},
"priorityOrder": 1,
"isPriorityToken": true
}
]
```
* `source` (`string`): The data source ('hyperswap').
* `name` (`string`): Full name of the asset.
* `symbol` (`string`): Symbol of the asset.
* `chainId` (`string | number`): The ID of the blockchain the asset belongs to.
* `address` (`string`): The contract address of the asset. For native tokens, specific normalized addresses are used (see "Token Addresses" section above).
* `decimals` (`number`): The number of decimal places for the asset.
* `logoUrl` (`string`): URL to the asset's logo.
* `chainLogoUrl` (`string`): URL to the logo of the chain the asset belongs to.
* `chainName` (`string`): Name of the chain the asset belongs to.
* `priceUsd` (`number`, optional): The price of the asset in USD.
* `swappable` (`boolean`): Indicates if the asset is swappable (always `true`).
* `providerId` (`object`): An object containing provider-specific IDs for the asset.
* `hyperswap` (`string`, optional): hyperswap identifier.
* `hyperswapshift` (`string`, optional): hyperswapshift identifier.
* `priorityOrder` (`number`, optional): A numerical order indicating the asset's priority (e.g., native tokens, stablecoins).
* `isPriorityToken` (`boolean`, optional): Indicates if the asset is a priority token.
* **Error Responses:**
* `500 Internal Server Error`: `{ "message": "Failed to fetch assets", "error": "An unknown error occurred" }`
* **Notes:**
* Responses are cached for 5 minutes to improve performance.
* The `chainId` parameter can accept various formats, which are normalized internally.
### 2. Get Preview Quotes
`POST /api/v1/quote`
* **Description:** Generates preview quotes for a token swap across different chains and tokens, aggregating results from various liquidity providers. These quotes are estimates and should be used for display purposes. A `quoteId` is returned for use in the `/api/v1/swap` endpoint.
* **Authentication:** Required.
* **Request Body (JSON):**
```json theme={null}
{
"fromChain": 1,
"toChain": 56,
"fromToken": "0x0000000000000000000000000000000000000000",
"toToken": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
"fromAmount": "1000000000000000000",
"fromAddress": "0xYourFromWalletAddress",
"toAddress": "0xYourToWalletAddress",
"fromDecimals": 18,
"toDecimals": 18,
"preference": "fastest"
}
```
* `fromChain` (`number`): The ID of the source blockchain. (See "Chain IDs" section for available values).
* `toChain` (`number`): The ID of the destination blockchain. (See "Chain IDs" section for available values).
* `fromToken` (`string`): The contract address of the source token. For native tokens, use the normalized address. (See "Token Addresses" section for available values).
* `toToken` (`string`): The contract address of the destination token. (See "Token Addresses" section for available values).
* `fromAmount` (`string`): The amount of the source token to swap, always in wei (the smallest unit of the token, e.g., for ETH, 1 ETH = 10^18 wei).
* `fromAddress` (`string`): The user's wallet address on the source chain.
* `toAddress` (`string`, optional): The user's wallet address on the destination chain. If not provided, the `fromAddress` might be used as a fallback by some providers, but it's best to explicitly provide it if known.
* `fromDecimals` (`number`): The number of decimals for the `fromToken`.
* `toDecimals` (`number`): The number of decimals for the `toToken`.
* `preference` (`'fastest' | 'lowest_cost'`): The user's preference for quote selection. (See "Preference" section for available values).
* **Response (JSON):**
```json theme={null}
{
"quotes": [
{
"quoteId": "unique-quote-id-1",
"provider": "hyperswap",
"actualProvider": "hyperswap",
"actualProviderLogo": "https://hyperswap.ai/logo.svg",
"toAmount": "9876543210987654321",
"estimatedTime": 60,
"fees": [
{
"type": "gas",
"amount": "21000",
"amountUsd": "5.00",
"asset": { /* ... asset details ... */ }
}
],
"type": "standard",
"chainId": 1,
"isPreview": true
},
{
"quoteId": "unique-quote-id-2",
"provider": "hyperswapshift",
"actualProvider": "hyperswapshift",
"actualProviderLogo": "https://hyperswap.ai/assets/logo.svg",
"toAmount": "9800000000000000000",
"estimatedTime": 120,
"fees": [],
"type": "standard",
"chainId": "20000000000001",
"isPreview": true
}
],
"bestQuote": {
"quoteId": "unique-quote-id-1",
"provider": "hyperswap",
"actualProvider": "hyperswap",
"actualProviderLogo": "https://hyperswap.ai/logo.svg",
"toAmount": "9876543210987654321",
"estimatedTime": 60,
"fees": [],
"type": "standard",
"chainId": 1,
"isPreview": true
},
"providerErrors": {},
"isPreview": true,
"message": "These are preview quotes. Final quotes will be generated at swap time with your actual wallet addresses."
}
```
* `quotes` (`Array