Documentation - Notus API

This endpoint creates liquidity for a swap liquidity pool through an Enso bundle: the swaps and the deposit are chained on-chain, so the deposit consumes the exact runtime swap outputs instead of worst-case estimates. Platform fees and gas fees are always charged in `tokenIn`.

Authorization

x-api-key

x-api-key<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

liquidityProvider?"UNISWAP_V3"

Optional provider for entering a liquidity pool. If not provided, Uniswap v3 will be used.

Value in

"UNISWAP_V3"

walletAddress*string

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

toAddress*string

The address (in hexadecimal format) receiving the token that represents the provided liquidity.

chainId*number

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
X Layer Mainnet: 196
Robinhood Chain: 4663

transactionFeePercent?number

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

Range0 <= value <= 99.99

Default0

gasFeePaymentMethod*string

Defines how the gas fee will be paid: "ADD_TO_AMOUNT" charges it on top of amountIn (the wallet must hold amountIn + fees + gas), while "DEDUCT_FROM_AMOUNT" subtracts it from amountIn before providing liquidity. On this route, platform fees and gas fees are always charged in tokenIn.

Value in

"ADD_TO_AMOUNT"
"DEDUCT_FROM_AMOUNT"

tokenIn*string

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

amountIn*string

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

token0*string

The address (in hexadecimal format) of one of the tokens of the pool.

token1*string

The address (in hexadecimal format) of the other token of the pool.

poolFeePercent*number

Defines the fee earned by providing liquidity. Lower values are recommended for more stable tokens, while higher values are better suited for volatile assets. The values allowed depend on the provider, so check the provider docs too to know which fee tiers are allowed.

Range0.01 <= value <= 100

minPrice*number

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

maxPrice*number

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

Range0 <= value <= 99

Default0.5

extraFee?

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?

Custom metadata for the entity. Key-value pairs with string values. Max 1KB size.

destinationToken?string

Optional, cross-chain only. Which of the pool pair the bridge should deliver, on chainIdOut. Supplying it enables a second route for the entry — the destination side runs as one atomic batch instead of a bundle — used automatically when the primary route cannot be quoted. Without it, only the primary route is attempted.

chainIdOut?number

The blockchain network of the pool, when different from chainId. The entry is then bridged inside the same bundle and the position is minted on this chain — still one signature, with tokenIn, platform fees and gas all staying on chainId. Only routes with a configured bridge lane are accepted; token0/token1 must be addresses on this chain.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/liquidity/enso" \  -H "Content-Type: application/json" \  -d '{    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",    "toAddress": "0x1337133713371337133713371337133713371337",    "chainId": 42161,    "gasFeePaymentMethod": "ADD_TO_AMOUNT",    "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",    "amountIn": "1.2",    "token0": "0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f",    "token1": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",    "poolFeePercent": 1,    "minPrice": 83475.12,    "maxPrice": 102300.5  }'

{  "operation": {    "metadata": {      "key": "value"    },    "userOperationHash": "0x2aac7a66d5331454eafc9b981be3596ad08a40dad24883e3b9c4a5362cd7f7e1",    "revertReason": {      "decoded": "ERC-20 insufficient balance. Address 0xf12534a4939c7fbda50f893774a9525265fe1a9a has 120. The operation requested 200.",      "raw": "0xe450d38c000000000000000000000000f12534a4939c7fbda50f893774a9525265fe1a9a0000000000000000000000000000000000000000000000068155a43676e0000000000000000000000000000000000000000000000000000ad78ebc5ac6200000",      "utf8": "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000�%4�����\u000f�7t�RRe�\u001a�\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0006�U�6v�\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\n׎�Z� \u0000\u0000"    },    "authorization": {      "chainId": 42161,      "address": "0xd6cedde84be40893d153be9d467cd6ad37875b28",      "nonce": 10,      "hash": "0x777811ae5d51875409b9978ddc1b40a9da1bbe9570040bdd7c5f186d70ceceba"    },    "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"  }}

Create Swap Liquidity (Enso)

Authorization

Request Body

Response Body

200application/json

400application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`