Notus API
Liquidity pools

Add Liquidity via Swap

This endpoint adds liquidity to an existing position by swapping a single input token into the two pool tokens and increasing the position.

POST
/api/v1/liquidity/add

Authorization

x-api-key<token>

In: header

Request Body

walletAddressstring

The wallet address (in hexadecimal format) that will provide the liquidity.

Match^0x[a-fA-F0-9]{40}$
chainIdnumber

The blockchain network where the liquidity will be provided. Supported EVM chains:

  • Arbitrum One: 42161
  • Avalanche: 43114
  • Base: 8453
  • BNB Smart Chain: 56
  • Ethereum: 1
  • Gnosis: 100
  • OP Mainnet: 10
  • Polygon: 137
transactionFeePercent?number

Percentage fee applied to the transaction (e.g., 5 for 5%).

Default0
Range0 <= value <= 99.99
payGasFeeTokenstring

The token address (in hexadecimal format) used to pay the transaction fee.

Match^0x[a-fA-F0-9]{40}$
gasFeePaymentMethodstring

Defines how the fee will be paid: "ADD_TO_AMOUNT" adds it to the input amount, while "DEDUCT_FROM_AMOUNT" subtracts it from the input amount.

Value in"ADD_TO_AMOUNT" | "DEDUCT_FROM_AMOUNT"
tokenInstring

The address (in hexadecimal format) of the token being swapped from.

Match^0x[a-fA-F0-9]{40}$
amountInstring

The amount of token being swapped from, expressed as a decimal string.

tokenIdstring

The NFT token ID of the existing liquidity position to add liquidity to.

minPricenumber

Minimum price the liquidity will be active. If the price goes below this, the liquidity won't be active and will generate no revenues. This will allow to concentrate the liquidity to a price range, thus enhancing the gains. Price is always p = token1 / token0

Range0 <= value
maxPricenumber

Maximum price the liquidity will be active. If the price goes above this, the liquidity won't be active and will generate no revenues. This will allow to concentrate the liquidity to a price range, thus enhancing the gains. Price is always p = token1 / token0

Range0 <= value
slippage?number

Optional parameter controlling the maximum deviation allowed of the expected price of a trade and the actual price at which the trade is executed, with a minimum value of 0.5 and a maximum value of 99, default is 0.5, where 1 unit equals 1%.

Default0.5
Range0.5 <= value <= 99
extraFee?object

Optional extra fee that can be charged in addition to the transaction fee (configured in the dashboard or via transactionFeePercent). This extra fee is deducted from the input token and sent to the specified toAddress, allowing you to define a custom recipient for this additional charge.

metadata?object

Empty Object

Response Body

curl -X POST "https://api.notuslabs.xyz/api/v1/liquidity/add" \  -H "Content-Type: application/json" \  -d '{    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",    "chainId": 42161,    "payGasFeeToken": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",    "gasFeePaymentMethod": "ADD_TO_AMOUNT",    "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",    "amountIn": "1.2",    "tokenId": "123456",    "minPrice": 83475.12,    "maxPrice": 102300.5  }'
{
  "operation": {
    "metadata": {
      "key": "value"
    },
    "userOperationHash": "0x2aac7a66d5331454eafc9b981be3596ad08a40dad24883e3b9c4a5362cd7f7e1",
    "tokenIn": {
      "name": "Wrapped Bitcoin",
      "symbol": "WBTC",
      "decimals": 18,
      "address": "0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f",
      "logoURL": "https://assets.notus.team/wbtc.png"
    },
    "amountIn": "7239.2",
    "tokenInAmountForToken0": "3619.6",
    "tokenInAmountForToken1": "3619.6",
    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
    "expiresAt": "2025-10-26T13:27:49.542Z",
    "amounts": "7239.2",
    "fees": [
      {
        "amount": "100.5",
        "token": "0x1234567890123456789012345678901234567890",
        "toAddress": "0x1234567890123456789012345678901234567890",
        "type": "NOTUS",
        "percentage": "2"
      }
    ],
    "estimatedGasFees": {
      "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
      "maxGasFeeToken": "12.345",
      "gasFeeTokenAmount": "12.345",
      "gasFeeTokenAmountUSD": "0.321",
      "maxGasFeeNative": "string"
    },
    "chain": 42161,
    "liquidityProvider": "UNISWAP_V3",
    "nftAddress": "0xc36442b4a4522e871399cd717abdd847ab11fe88",
    "estimatedApr": "18.42"
  }
}
{
  "statusCode": 400,
  "id": "NOT_AUTHORIZED_TOKENS",
  "message": ""
}
{
  "statusCode": 403,
  "id": "UNAVAILABLE_COMPUTE_UNITS",
  "message": "The project doesn't have enough compute units to perform this action. Please upgrade your plan."
}
{
  "statusCode": 404,
  "id": "ACCOUNT_ABSTRACTION_ADDRESS_NOT_REGISTERED_WITH_PROJECT",
  "message": "The requested wallet \"0x6e397ddf51d9f15dbe0414538e7529f51f2e5464\" is not registered with the project"
}

Change Liquidity POST

Change the amount of liquidity provided in a liquidity pool

Collect fees from liquidity POST

Collects the fees received by the liquidity NFT. This will both create a user operation to be executed and will show how much will be collected, so you can choose if you really want to collect it or not. Always collects the full amount.