LiquidSwap API

https://docs.liqd.ag/api/using-the-api
Admin
The LiquidSwap Aggregator API enables programmatic interaction with the protocol, offering endpoints...
Tokens:4,652
Snippets:19
Trust Score:6.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example HTTP GET Requests for Token Balances API

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-balances

Illustrates how to query the /tokens/balances endpoint using HTTP GET requests, showing examples with and without the 'limit' parameter.

```HTTP
GET https://api.liqd.ag/tokens/balances?wallet=0x123456789abcdef123456789abcdef123456789
GET https://api.liqd.ag/tokens/balances?wallet=0x123456789abcdef123456789abcdef123456789&limit=10
```

--------------------------------

### Example API Request for Direct Token Swap

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/route-finding

This example demonstrates how to construct a GET request to the /route endpoint for a direct swap. It specifies the input and output token addresses along with the amount of the input token.

```HTTP
GET https://api.liqd.ag/route?tokenA=0x47bb061C0204Af921F43DC73C7D7768d2672DdEE&tokenB=0xF26A8ab118f4C46A2D3C0C5cF4bf446008efBf8c&amountIn=1
```

--------------------------------

### Example HTTP GET Request to Find Pools

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/find-pools

An example of an HTTP GET request to the /pools endpoint, demonstrating how to pass 'tokenA' and 'tokenB' addresses as query parameters to find relevant liquidity pools.

```HTTP
GET https://api.liqd.ag/pools?tokenA=0x47bb061C0204Af921F43DC73C7D7768d2672DdEE&tokenB=0xF26A8ab118f4C46A2D3C0C5cF4bf446008efBf8c
```

--------------------------------

### Example API Response for Route Finding

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/route-finding

This JSON example shows a typical successful response from the /route endpoint. It details the best path found, estimated output, price impact, and a breakdown of each hop's allocations across different routers, along with token information.

```JSON
{
  "success": true,
  "data": {
    "bestPath": {
      "path": ["0x47bb061C0204Af921F43DC73C7D7768d2672DdEE", "0xIntermediate", "0xF26A8ab118f4C46A2D3C0C5cF4bf446008efBf8c"],
      "estimatedAmountOut": "1.05",
      "amountIn": "1",
      "priceImpact": "0.3%",
      "hop": [
        {
          "tokenIn": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
          "tokenOut": "0xIntermediate",
          "hopAmountIn": "1",
          "allocations": [
            {
              "tokenIn": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
              "tokenOut": "0xIntermediate",
              "routerIndex": 1,
              "fee": 0,
              "amountIn": "0.5",
              "stable": true,
              "routerName": "KittenSwap",
              "percentage": 50
            },
            {
              "tokenIn": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
              "tokenOut": "0xIntermediate",
              "routerIndex": 3,
              "fee": 500,
              "amountIn": "0.5",
              "stable": false,
              "routerName": "HyperSwapV3",
              "percentage": 50
            }
          ]
        },
        {
          "tokenIn": "0xIntermediate",
          "tokenOut": "0xF26A8ab118fC46A2D3C0C5cF4bf446008efBf8c",
          "hopAmountIn": "10.5",
          "allocations": [
            {
              "tokenIn": "0xIntermediate",
              "tokenOut": "0xF26A8ab118fC46A2D3C0C5cF4bf446008efBf8c",
              "routerIndex": 2,
              "fee": 0,
              "amountIn": "10.5",
              "stable": false,
              "routerName": "HyperSwapV2",
              "percentage": 100
            }
          ]
        }
      ],
      "tokenInfo": {
        "tokenIn": {
          "address": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
          "symbol": "TOKEN1",
          "decimals": 18
        },
        "tokenOut": {
          "address": "0xF26A8ab118fC46A2D3C0C5cF4bf446008efBf8c",
          "symbol": "TOKEN2",
          "decimals": 18
        },
        "intermediate": {
          "address": "0xIntermediate",
          "symbol": "INTER",
          "decimals": 18
        }
      }
    }
  }
}
```

--------------------------------

### Example API Request for Multi-Hop Token Swap

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/route-finding

This example illustrates a GET request to the /route endpoint that enables multi-hop routing. It includes the multiHop=true parameter to allow the API to find more complex paths for the token swap.

```HTTP
GET https://api.liqd.ag/route?tokenA=0x47bb061C0204Af921F43DC73C7D7768d2672DdEE&tokenB=0xF26A8ab118f4C46A2D3C0C5cF4bf446008efBf8c&amountIn=1&multiHop=true
```

--------------------------------

### Example API Requests for Token List Endpoint

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-list

Demonstrates various ways to query the /tokens API endpoint using GET requests. Examples include a basic request, limiting results, searching by token symbol, requesting only addresses, and combining limit and search parameters.

```HTTP
GET https://api.liqd.ag/tokens
GET https://api.liqd.ag/tokens?limit=10
GET https://api.liqd.ag/tokens?search=HYPE
GET https://api.liqd.ag/tokens?metadata=false
GET https://api.liqd.ag/tokens?limit=5&search=USD
```

--------------------------------

### Example JSON Response for Token Balances API

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-balances

Shows the expected JSON structure returned by the /tokens/balances endpoint, including success status, wallet address, an array of token details (name, symbol, balance, decimals), and counts.

```JSON
{
  "success": true,
  "data": {
    "wallet": "0x123456789abcdef123456789abcdef123456789",
    "tokens": [
      {
        "token": "Native HYPE",
        "balance": "1000000000000000000",
        "name": "HYPE",
        "symbol": "HYPE",
        "decimals": 18
      },
      {
        "token": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
        "balance": "500000000000000000",
        "name": "Token One",
        "symbol": "TOKEN1",
        "decimals": 18
      }
    ],
    "count": 2,
    "limitedCount": 2
  }
}
```

--------------------------------

### API Endpoint and Parameters for Token Balances

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-balances

Details the GET endpoint for retrieving token balances, including required and optional parameters for the request.

```APIDOC
Endpoint: GET /tokens/balances
Parameters:
  wallet:
    Type: address
    Description: Address of the wallet to check balances for
    Required: Yes
  limit:
    Type: number
    Description: Maximum number of tokens to return
    Required: No
```

--------------------------------

### API Endpoint and Parameters for Route Finding

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/route-finding

This section defines the GET /route API endpoint, outlining all available parameters such as input/output tokens, amounts, multi-hop options, and DEX exclusions. It specifies data types, descriptions, and whether each parameter is required for a successful request.

```APIDOC
Endpoint: GET /route
Description: Calculates the optimal swap route between two tokens.

Parameters:
  - Name: tokenA
    Type: address
    Description: Address of the input token
    Required: Yes
  - Name: tokenB
    Type: address
    Description: Address of the output token
    Required: Yes
  - Name: amountIn
    Type: number
    Description: Amount of input token (human readable, e.g., 1.5)
    Required: No*
  - Name: amountOut
    Type: number
    Description: Desired output amount (for reverse routing)
    Required: No*
  - Name: multiHop
    Type: boolean
    Description: Set to "true" to enable multi-hop routing
    Required: No
  - Name: excludeDexes
    Type: string
    Description: Comma-separated list of router indices to exclude
    Required: No

*Note: You must provide either amountIn OR amountOut, but not both.
```

--------------------------------

### Execute Multi-Hop Swap using Liqd.ag API (JavaScript/ethers.js)

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/interacting-with-the-smart-contract

This example demonstrates how to integrate with the Liqd.ag API to retrieve optimal multi-hop swap routes and then execute the swap on-chain. It covers setting up an ethers.js provider and wallet, calling the Liqd.ag route API, parsing the response, formatting transaction data for the MultiHopRouter contract, and handling both native token (HYPE) and ERC-20 token inputs, including ERC-20 approvals.

```JavaScript
const { ethers } = require('ethers');
const axios = require('axios');

// Constants
const RPC_URL = 'https://rpc.hyperliquid.xyz/evm';
const ROUTER_ADDRESS = '0x744489ee3d540777a66f2cf297479745e0852f7a';
const PRIVATE_KEY = 'your-private-key';
const NATIVE_TOKEN = '0x000000000000000000000000000000000000dEaD'; // NATIVE_HYPE address

// MultiHopRouter ABI (just the executeMultiHopSwap function)
const ROUTER_ABI = [
  "function executeMultiHopSwap(address[] calldata tokens, uint256 amountIn, uint256 minAmountOut, tuple(address tokenIn, address tokenOut, uint8 routerIndex, uint24 fee, uint256 amountIn, bool stable)[][] calldata hopSwaps) external payable returns (uint256 totalAmountOut)"
];

// Function to get route from API
async function getRoute(tokenA, tokenB, amountIn) {
  try {
    const response = await axios.get(
      `https://api.liqd.ag/route?tokenA=${tokenA}&tokenB=${tokenB}&amountIn=${amountIn}&multiHop=true`
    );
    return response.data;
  } catch (error) {
    console.error('Error fetching route:', error.message);
    throw error;
  }
}

// Main function to execute a multi-hop swap
async function executeMultiHopSwap(tokenA, tokenB, amountIn) {
  try {
    // Setup provider and wallet
    const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
    const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
    const router = new ethers.Contract(ROUTER_ADDRESS, ROUTER_ABI, wallet);

    // Get route from API
    const routeData = await getRoute(tokenA, tokenB, amountIn);

    if (!routeData || !routeData.data || !routeData.data.bestPath) {
      throw new Error('Invalid route data returned from API');
    }

    // Extract path information
    const bestPath = routeData.data.bestPath;
    const tokenInfo = routeData.data.tokenInfo;

    // Format data for contract call
    let tokens = [];
    let hopSwaps = [];

    // Process the path
    if (bestPath.hop.length > 0) {
      // Build the token path array
      tokens = [bestPath.hop[0].tokenIn];
      for (let i = 0; i < bestPath.hop.length; i++) {
        tokens.push(bestPath.hop[i].tokenOut);
      }

      // Process each hop
      for (let i = 0; i < bestPath.hop.length; i++) {
        const hopData = bestPath.hop[i];
        const swapsForHop = [];

        // Get the appropriate decimals for this hop's input token
        const tokenInDecimals = i === 0
          ? tokenInfo.tokenIn.decimals
          : tokenInfo.intermediate.decimals;

        // Process each allocation in this hop
        for (const allocation of hopData.allocations) {
          swapsForHop.push({
            tokenIn: allocation.tokenIn,
            tokenOut: allocation.tokenOut,
            routerIndex: parseInt(allocation.routerIndex) || 0,
            fee: parseInt(allocation.fee) || 0,
            amountIn: ethers.utils.parseUnits(allocation.amountIn, tokenInDecimals).toString(),
            stable: allocation.stable || false
          });
        }

        hopSwaps.push(swapsForHop);
      }
    }

    // Calculate minAmountOut with 1% slippage tolerance
    const expectedOut = ethers.utils.parseUnits(bestPath.amountOut, tokenInfo.tokenOut.decimals);
    const minAmountOut = expectedOut.mul(99).div(100); // 1% slippage tolerance

    // Prepare transaction parameters
    const parsedAmountIn = ethers.utils.parseUnits(amountIn, tokenInfo.tokenIn.decimals);

    // Check if native token is used
    const isNativeToken = tokenInfo.tokenIn.address.toLowerCase() === NATIVE_TOKEN.toLowerCase();

    let tx;
    // Handle transaction based on token type
    if (isNativeToken) {
      // For native token (HYPE), send the amount as value
      tx = await router.executeMultiHopSwap(
        tokens,
        0,  // This value is ignored when sending native tokens
        minAmountOut,
        hopSwaps,
        {
          gasLimit: 2000000,
          value: parsedAmountIn // Send the native token amount as transaction value
        }
      );
    } else {
      // For ERC-20 tokens
      // Approve first
      const tokenContract = new ethers.Contract(
        tokenInfo.tokenIn.address,
        ['function approve(address spender, uint256 amount) returns (bool)'],
        wallet
      );

      const approveTx = await tokenContract.approve(ROUTER_ADDRESS, parsedAmountIn);
      await approveTx.wait();

      // Execute the swap with ERC-20 token
      tx = await router.executeMultiHopSwap(
        tokens,
        parsedAmountIn, // For ERC-20, pass the actual amount
        minAmountOut,
        hopSwaps,
        {
          gasLimit: 2000000,
          value: 0 // No value needed for ERC-20 swaps
        }
      );
    }

    const receipt = await tx.wait();
    return receipt;
  } catch (error) {
    console.error('Error executing multi-hop swap:', error);
    throw error;
  }
}
```

--------------------------------

### Example JSON Response for Find Pools API

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/find-pools

A sample JSON response returned by the /pools endpoint, illustrating the structure of the data for successful queries. It includes an array of pool objects, each detailing pool address, paired token, router index, fee, stability, protocol, pair name, and price.

```JSON
{
  "success": true,
  "data": [
    {
      "poolAddress": "0x...",
      "pairedToken": "0x...",
      "routerIndex": 1,
      "fee": 0,
      "stable": true,
      "protocol": "KittenSwap",
      "pair": "WETH/USDC",
      "price": "1845.32"
    },
    {
      "poolAddress": "0x...",
      "pairedToken": "0x...",
      "routerIndex": 3,
      "fee": 500,
      "stable": false,
      "protocol": "HyperSwapV3",
      "pair": "WETH/USDC",
      "price": "1842.75"
    }
  ]
}
```

--------------------------------

### Example API Response: Token List (Addresses Only)

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-list

Shows the simplified JSON structure returned by the /tokens API endpoint when only addresses are requested (i.e., metadata=false). The response contains a list of token addresses, along with pagination and service status information.

```JSON
{
  "success": true,
  "data": {
    "addresses": [
      "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
      "0xF26A8ab118f4C46A2D3C0C5cF4bf446008efBf8c"
    ],
    "count": 2,
    "limitedCount": 2,
    "searchApplied": false,
    "limitApplied": false,
    "serviceStatus": "running",
    "lastProcessedBlock": "12345678"
  }
}
```

--------------------------------

### API: Get All Tracked Tokens Endpoint Definition

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-list

Documents the GET /tokens API endpoint for retrieving a list of all tracked tokens. It specifies the endpoint, lists available parameters (search, limit, metadata) with their types, descriptions, and required status, and notes the default sorting order.

```APIDOC
Endpoint: GET /tokens
Description: Returns a list of all tracked tokens with their metadata.
Parameters:
  - Name: search
    Type: string
    Description: Filter tokens by address, name, or symbol
    Required: No
  - Name: limit
    Type: number
    Description: Maximum number of tokens to return
    Required: No
  - Name: metadata
    Type: boolean
    Description: When "false", returns only addresses
    Required: No
Note: Tokens are always sorted by 24-hour transfer count in descending order (highest first).
```

--------------------------------

### Example API Response: Token List with Metadata

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/token-list

Illustrates the JSON structure returned by the /tokens API endpoint when metadata is requested. It shows a successful response containing an array of token objects, each with address, name, symbol, decimals, and 24-hour transfer count, along with pagination and service status information.

```JSON
{
  "success": true,
  "data": {
    "tokens": [
      {
        "address": "0x47bb061C0204Af921F43DC73C7D7768d2672DdEE",
        "name": "Token One",
        "symbol": "TOKEN1",
        "decimals": 18,
        "transfers24h": 1250
      },
      {
        "address": "0xF26A8ab118f4C46A2D3C0C5cF4bf446008efBf8c",
        "name": "Token Two",
        "symbol": "TOKEN2",
        "decimals": 18,
        "transfers24h": 950
      }
    ],
    "count": 2,
    "limitedCount": 2,
    "searchApplied": false,
    "limitApplied": false,
    "serviceStatus": "running",
    "lastProcessedBlock": "12345678"
  }
}
```

--------------------------------

### LiquidSwap API Base URL

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api

The base URL for all LiquidSwap Aggregator API endpoints. All subsequent API calls should be prefixed with this URL.

```APIDOC
https://api.liqd.ag
```

--------------------------------

### API Endpoint and Parameters for Find Pools

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/find-pools

Defines the HTTP method, endpoint path, and the required and optional parameters for querying liquidity pools. Parameters include token addresses and an optional list of DEXes to exclude.

```APIDOC
Endpoint: GET /pools
Parameters:
  Name: tokenA
    Type: address
    Description: Address of the first token
    Required: Yes
  Name: tokenB
    Type: address
    Description: Address of the second token
    Required: Yes
  Name: excludeDexes
    Type: string
    Description: Comma-separated list of router indices to exclude
    Required: No
```

--------------------------------

### LiquidSwap API Base URL

Source: https://docs.liqd.ag/api/using-the-api/api

The base URL for all LiquidSwap Aggregator API endpoints. All API requests should be prefixed with this URL.

```APIDOC
https://api.liqd.ag
```

--------------------------------

### MultiHopRouter executeMultiHopSwap Function Signature and Parameters

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/interacting-with-the-smart-contract

The function signature and detailed parameters for the `executeMultiHopSwap` function of the `MultiHopRouter` smart contract. This function is used to perform multi-hop swaps. Note that when swapping native HYPE, the `amountIn` parameter is ignored, and `msg.value` is used instead.

```APIDOC
function executeMultiHopSwap(
    address[] calldata tokens,
    uint256 amountIn,
    uint256 minAmountOut,
    Swap[][] calldata hopSwaps
) external payable returns (uint256 totalAmountOut)

Parameters:
  tokens: address[] - Array of token addresses in the swap path (including intermediates)
  amountIn: uint256 - Amount of input tokens (for ERC-20 tokens only)
  minAmountOut: uint256 - Minimum acceptable output amount (slippage protection)
  hopSwaps: Swap[][] - 2D array of Swap structs, where each inner array is a hop
```

--------------------------------

### LiquidSwap MultiHopRouter Contract Address

Source: https://docs.liqd.ag/api/using-the-api/api/using-the-api/interacting-with-the-smart-contract

The deployed address of the `MultiHopRouter` smart contract on the blockchain, which facilitates multi-hop swaps.

```Solidity
0x744489ee3d540777a66f2cf297479745e0852f7a
```
Tokens:
Raw