API Endpoints

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 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
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.

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):

[
  {
    "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):
```
{
  "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):

{
  "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<object>): An array of preview quotes, typically returning the top 2 based on the preference.
- quoteId (string): A unique identifier for the quote, to be used in the /api/v1/swap endpoint.
- provider (string): The name of the liquidity provider (‘hyperswap’).
- toAmount (string): The estimated amount of destination token received (in wei).
- estimatedTime (number): Estimated time in seconds for the swap to complete.
- fees (Array<object>, optional): Details about any fees associated with the swap.
- type (string, optional): Specific type of swap (e.g., ‘standard’ for hyperswapshift).
- chainId (string | number): The chain ID for the quote.
- isPreview (boolean): Always true for these preview quotes.
bestQuote (object): The best quote from the quotes array based on the preference.
providerErrors (object, optional): An object containing errors from individual liquidity providers if any failed to return quotes.
isPreview (boolean): Always true.
message (string): A descriptive message indicating that these are preview quotes.

Error Responses:
- 400 Bad Request:
  - { "message": "fromChain, toChain, fromToken, toToken, fromAmount, fromAddress, and preference are required" }
  - { "message": "preference must be either \"fastest\" or \"lowest_cost\"" }
  - { "message": "Invalid fromToken or toToken", "details": { "fromTokenValid": false, "toTokenValid": true } }
  - { "message": "No routes available for this token pair", "error": "ROUTE_NOT_SUPPORTED" }
- 503 Service Unavailable: { "message": "Service temporarily unavailable" } (e.g., if TokenService initialization fails).
- 500 Internal Server Error: { "message": "Failed to generate quotes. Please try again.", "error": "An unknown error occurred" }
Notes:
- Quotes are cached internally for a short period for later retrieval during the swap process.
- The fromAmount must be provided in the smallest unit (wei) of the fromToken.

3. Initiate Swap

POST /api/v1/swap

Description: Initiates a token swap based on a previously generated quote. This endpoint interacts with the chosen liquidity provider (hyperswap or hyperswapshift) to create the actual transaction or shift.
Authentication: Required.
Request Body (JSON):
- Common Fields:
  { "provider": "hyperswap", "settleAddress": "0xYourSettleWalletAddress", "refundAddress": "0xYourRefundWalletAddress", "clientId": "YourClientIdentifier", "preference": "fastest", "settleMemo": "OptionalSettleMemo", "refundMemo": "OptionalRefundMemo" }
  - provider ('hyperswap'): The liquidity provider to use. (See “Provider” section for available values).
  - settleAddress (string): The address where the swapped tokens should be sent.
  - refundAddress (string, optional): The address for refunds in case of issues. This is crucial for hyperswapshift swaps.
  - clientId (string): A unique identifier for your client application.
  - preference ('fastest' | 'lowest_cost', optional): The preference used for the original quote.
  - settleMemo (string, optional): Memo or tag for the settle address (e.g., for exchanges that require it).
  - refundMemo (string, optional): Memo or tag for the refund address.
- For provider: 'hyperswap' (additional fields):
  { "fromChain": 1, "toChain": 56, "fromToken": "0x0000000000000000000000000000000000000000", "toToken": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "fromAmount": "1000000000000000000", "fromAddress": "0xYourFromWalletAddress", "toAddress": "0xYourToWalletAddress" }
  - These fields are used to generate a fresh quote from hyperswap at the time of swap initiation.
- For provider: 'hyperswapshift' (additional fields):
  { "quoteId": "unique-quote-id-from-quote-endpoint" }
  - quoteId (string): The quoteId obtained from the /api/v1/quote endpoint.
Response (JSON):
- For hyperswap Swaps (provider: 'hyperswap'):
  { "message": "Swap initiated successfully", "transactionId": "internal-transaction-id-123", "provider": "hyperswap", "requiresSigning": true, "transactionRequest": { "to": "0xContractAddressForSwap", "data": "0x...", "value": "0x0", "from": "0xYourFromWalletAddress", "gasPrice": "0x...", "gasLimit": "0x...", "chainId": 1, "type": "evm" }, "chainId": 1 }
  - transactionRequest (object): Details for the transaction that needs to be signed by the user’s wallet.
    - type (string): Indicates the chain type (‘evm’, ‘solana’, or ‘bitcoin’).
    - For EVM: to, data, value, from, gasPrice, gasLimit, chainId.
    - For Solana: data.
    - For Bitcoin: to, data, value.
  - chainId (string | number): The chain ID where the transaction needs to be signed.
  - requiresSigning (boolean): Always true for hyperswap, indicating the user must sign the transaction.
- For hyperswapshift Swaps (provider: 'hyperswapshift'):
  { "message": "Swap initiated successfully", "transactionId": "internal-transaction-id-456", "provider": "hyperswapshift", "requiresSigning": false, "shiftId": "hyperswapshift-shift-id-abc", "depositAddress": "bc1q...", "depositMemo": "optional-memo", "expiresAt": "2025-06-22T18:00:00.000Z", "type": "hyperswapshift-deposit" }
  - shiftId (string): hyperswapshift’s unique ID for the shift.
  - depositAddress (string): The address where the user needs to deposit the fromToken.
  - depositMemo (string, optional): Memo for the deposit address, if required by the destination.
  - expiresAt (string): ISO timestamp when the deposit address expires.
  - type (string): Typically ‘hyperswapshift-deposit’.
  - requiresSigning (boolean): Always false for hyperswapshift, as it involves a deposit rather than a direct signature.
Error Responses:
- 400 Bad Request:
  - { "message": "provider, settleAddress, and clientId are required" }
  - { "message": "Missing required fields for hyperswap swap" }
  - { "message": "quoteId is required for hyperswapshift swaps" }
  - { "message": "Quote not found or expired. Please generate a new quote." }
  - { "message": "The generated hyperswap quote is not valid for execution" }
  - { "message": "The cached hyperswapshift quote is no longer valid for execution" }
  - { "message": "Unsupported provider" }
- 500 Internal Server Error: { "message": "Failed to execute swap", "error": "An unknown error occurred" }
Notes:
- For hyperswap, the refundAddress might be overridden by environment variables for specific chain types (e.g., Solana, Bitcoin, EVM) to ensure proper handling.
- A Transaction record is created in the internal database to track the swap’s lifecycle.

4. Get Transaction Status

GET /api/v1/status/{transactionId}

Description: Retrieves the current status of a previously initiated swap transaction using its internal transactionId. This endpoint polls the respective liquidity provider for the latest status and updates the internal database.
Path Parameters:
- transactionId (string): The unique ID of the transaction, generated by the /api/v1/swap endpoint.
Response (JSON): Returns a Transaction object from the internal database.

API Documentation

​Features of the API

​API Endpoints # Hyperswap API Endpoints Documentation

​Base URL

​Authentication

​Available Values and Data Sources

​Chain IDs (chainId)

​Token Addresses (fromToken, toToken)

​Preference (preference)

​Transaction Statuses (status)

​API Endpoints

​1. Get All Assets

​2. Get Preview Quotes

​3. Initiate Swap

​4. Get Transaction Status

Features of the API

API Endpoints # Hyperswap API Endpoints Documentation

Base URL

Authentication

Available Values and Data Sources

Chain IDs (`chainId`)

Token Addresses (`fromToken`, `toToken`)

Preference (`preference`)

Transaction Statuses (`status`)

API Endpoints

1. Get All Assets

2. Get Preview Quotes

3. Initiate Swap

4. Get Transaction Status