Documentation - Notus API

Adds liquidity to a position that lives on a different chain than the funds, in a single signature. The user signs one operation on `chainId`; the bridge delivers `destinationToken` on `chainIdOut` and, in the same destination transaction, splits it at the position range ratio and grows the position. The destination side is atomic: if any part of it fails, nothing settles and the deposit is refunded on `chainId`. 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.

walletAddress*string

The wallet address (in hexadecimal format) that will provide the 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 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"

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.

tokenId*string

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

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.

chainIdOut*number

The blockchain network the position lives on. Must differ from chainId, and only routes with a configured bridge lane are accepted. 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

destinationToken*string

The address (in hexadecimal format), on chainIdOut, of the token bridged into the pool. Must be one of the pool pair, since the top-up spends it directly against the position: part is swapped into the other side at the position range ratio, and whatever is left over is returned to the wallet on chainIdOut.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/liquidity/add/cross-chain" \  -H "Content-Type: application/json" \  -d '{    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",    "chainId": 42161,    "gasFeePaymentMethod": "ADD_TO_AMOUNT",    "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",    "amountIn": "1.2",    "tokenId": "123456",    "chainIdOut": 42161,    "destinationToken": "0x55d398326f99059ff775485246999027b3197955"  }'

{  "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"  }}

Add Liquidity To An Existing Position On Another Chain

Authorization

Request Body

Response Body

200application/json

400application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`