Notus API
Liquidity pools

Rebalance a liquidity position with a new price range

Collects the entire position, swaps assets as needed, and mints a fresh Uniswap v3 position in the requested range.

POST
/api/v1/liquidity/rebalance

Authorization

x-api-key<token>

In: header

Request Body

liquidityProvider?string

Optional provider for the rebalance operation. Defaults to Uniswap v3 if omitted.

Value in"UNISWAP_V3"
walletAddressstring

Wallet that owns the liquidity position NFT.

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

Address that will own the new liquidity position NFT.

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

Target blockchain for the rebalance operation. Supported EVM chains:

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

NFT token ID representing the current liquidity position.

newPositionobject

New price range for the liquidity position after rebalance.

slippage?number

Maximum tolerated slippage for the underlying swaps (1 unit = 1%).

Default0.5
Range0.5 <= value <= 99
transactionFeePercent?number

Custom project fee percent to apply over the rebalance notional.

Default0
Range0 <= value <= 99.99
extraFee?object

Optional extra fee configuration that is charged once during rebalance.

metadata?object

Empty Object

Response Body

curl -X POST "https://api.notuslabs.xyz/api/v1/liquidity/rebalance" \  -H "Content-Type: application/json" \  -d '{    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",    "toAddress": "0x1337133713371337133713371337133713371337",    "chainId": 42161,    "tokenId": "1234567890",    "newPosition": {      "minPrice": 1200.12,      "maxPrice": 1800.34    }  }'
{
  "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"
}
{
  "statusCode": 500,
  "id": "BLOCKCHAIN_ERROR",
  "message": "We had a problem fetching the data from the blockchain. If the problem persists, contact our support."
}

List Liquidity Pools GET

List liquidity pools that exist on the blockchain. The pool can be in a broken state, like having nearly no liquidity. Use the data returned by this endpoint to asses if the pool is worth investing into. Choose the aggregation interval to control both granularity and time range: DAILY (last 30 days), WEEKLY (last 12 weeks), MONTHLY (last 12 months).

Withdraw Swap Liquidity POST

This endpoint withdraws liquidity from a pool, swaps the received tokens to a single output token, and sends to the specified address.