Get Liquidity History

API Description

Retrieves liquidity operation history (additions and removals) for a specific address on a given chain. This endpoint provides detailed information about all liquidity operations including price ranges, liquidity amounts, fees earned, and token information for each operation.

HTTP Request

GET /v4/public/mm/liquidity/history

Request Parameters

Parameter	Type	Required	Description
chainId	uint64	Yes	Chain ID (e.g., 143 for Monad mainnet)
address	string	Yes	Trader wallet address (EVM address format)
page	uint32	No	Page number (default: 1)
size	uint32	No	Page size (default: 50, max: 200)
symbol	string	No	Trading pair symbol (e.g., BTC/USDC)
startTime	int64	No	Start time in Unix timestamp (seconds)
endTime	int64	No	End time in Unix timestamp (seconds)

Response Parameters

Parameter	Type	Description
list	array	Array of liquidity operation records
-> id	string	Operation record ID
-> instrumentAddress	string	Contract address of the instrument
-> expiry	number	Expiry timestamp (4294967295 for perpetual)
-> timestamp	number	Operation timestamp (Unix timestamp in seconds)
-> txHash	string	Transaction hash on the blockchain
-> type	number	Operation type (0: add, 1: remove)
-> typeString	string	Operation type as string ("add", "remove")
-> lowerTick	number	Lower tick of the price range
-> upperTick	number	Upper tick of the price range
-> lowerPrice	string	Lower price of the range
-> upperPrice	string	Upper price of the range
-> fairPrice	string	Fair price at the time of operation
-> amount	string	Liquidity amount
-> feeEarned	string	Fees earned from this liquidity position
-> symbol	string	Trading pair symbol (e.g., BTC/USDC)
-> baseToken	object	Base token information
-> -> address	string	Token contract address
-> -> symbol	string	Token symbol (e.g., BTC)
-> -> decimals	number	Token decimal places
-> -> image	string	Token image URL
-> -> price	number	Current token price
-> quoteToken	object	Quote token information
-> -> address	string	Token contract address
-> -> symbol	string	Token symbol (e.g., USDC)
-> -> decimals	number	Token decimal places
-> -> image	string	Token image URL
-> -> price	number	Current token price
totalCount	number	Total number of liquidity operation records

Request Example

Python (requests)

Note: This endpoint requires API authentication. See Quick Start Guide for signature generation details.

import hmac
import hashlib
import base64
import json
import requests
from datetime import datetime, timezone
from urllib.parse import urlencode

def generate_mm_signature(secret_key, timestamp, method, request_path, body="", content_type=""):
    """Generate API signature"""
    message = timestamp + method.upper() + request_path
    if body and method.upper() in ["POST", "PUT", "PATCH"]:
        if content_type and "application/json" in content_type.lower():
            data = json.loads(body)
            body = json.dumps(data, sort_keys=True, separators=(',', ':'))
        message += body
    
    mac = hmac.new(
        secret_key.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    )
    return base64.b64encode(mac.digest()).decode('utf-8')

# Generate timestamp
timestamp = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')

# Build request path with sorted query parameters
params = {
    'chainId': 143,
    'address': '0xb0b81c2c7686c63acae28f9778ca8fa80f0c004b',
    'page': 1,
    'size': 50
}
# Sort parameters alphabetically for signature
sorted_params = sorted(params.items())
query_string = urlencode(sorted_params)
request_path = f"/v4/public/mm/liquidity/history?{query_string}"

# Generate signature
signature = generate_mm_signature(secret_key, timestamp, "GET", request_path)

# Make request
headers = {
    "X-ACCESS-KEY": api_key,
    "X-ACCESS-SIGN": signature,
    "X-ACCESS-TIMESTAMP": timestamp,
    "X-ACCESS-PASSPHRASE": passphrase,
}

url = f"https://api.monday.trade/v4/public/mm/liquidity/history?{urlencode(params)}"
response = requests.get(url, headers=headers)
result = response.json()
print(json.dumps(result, indent=2))

Response Example

Success Response

{
    "data": {
        "list": [
            {
                "id": "1030038105581000042",
                "instrumentAddress": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
                "expiry": 4294967295,
                "timestamp": 1764155795,
                "txHash": "0x905c18b1c10671e7ca5119768e447e3b5c790b5984aa941756dc2da009648663",
                "type": 1,
                "lowerTick": 112750,
                "upperTick": 114700,
                "lowerPrice": "78781.7214449692074685",
                "upperPrice": "95743.358166580887684",
                "fairPrice": "86967.3590581160950041",
                "amount": "90",
                "feeEarned": "0",
                "symbol": "BTC/USDC",
                "baseToken": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "BTC",
                    "decimals": 18,
                    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
                    "price": 89052
                },
                "quoteToken": {
                    "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
                    "symbol": "USDC",
                    "decimals": 6,
                    "image": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694",
                    "price": 0.999977
                },
                "typeString": "remove"
            },
            {
                "id": "1030038105557000031",
                "instrumentAddress": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
                "expiry": 4294967295,
                "timestamp": 1764155786,
                "txHash": "0x75f562f3a37470f0adc46761c0b3b4cb949312edea02ef54625e20c07fe72971",
                "type": 0,
                "lowerTick": 112750,
                "upperTick": 114700,
                "lowerPrice": "78781.7214449692074685",
                "upperPrice": "95743.358166580887684",
                "fairPrice": "86967.3590581160950041",
                "amount": "90",
                "feeEarned": "0",
                "symbol": "BTC/USDC",
                "baseToken": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "BTC",
                    "decimals": 18,
                    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
                    "price": 89052
                },
                "quoteToken": {
                    "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
                    "symbol": "USDC",
                    "decimals": 6,
                    "image": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694",
                    "price": 0.999977
                },
                "typeString": "add"
            }
        ],
        "totalCount": 20
    },
    "msg": "",
    "code": 0,
    "requestId": "06cfb07f-3630-4337-b65b-0747b2759711"
}

Error Response

{
    "code": 400,
    "msg": "Request parameter error",
    "data": {},
    "requestId": "bbf4fa1a-0f41-449f-8d9c-44fdceae0bf7"
}

Notes

• This endpoint requires API authentication (see Quick Start Guide)

• Both chainId and address parameters are required

• The address must be a valid EVM address format

• Returns liquidity operation history (additions and removals) for the specified address

• Supports pagination with page and size parameters

• Default page size is 50, maximum is 200

• type: 0 for add liquidity, 1 for remove liquidity

• typeString: "add" or "remove" as string

• timestamp: Unix timestamp in seconds

• lowerTick and upperTick: Tick values defining the price range

• lowerPrice and upperPrice: Actual price values for the liquidity range

• fairPrice: Fair price at the time of the operation

• amount: Liquidity amount added or removed

• feeEarned: Fees earned from this liquidity position

• expiry: 4294967295 indicates a perpetual contract

• baseToken and quoteToken: Token information including symbol, decimals, image, and current price

• Optional symbol parameter can filter results by trading pair

• Optional startTime and endTime parameters can filter by time range

• totalCount: Total number of liquidity operation records (useful for pagination)

• Rate limit: 120 requests per minute

• Success response has code: 0 (not 200)