Get Trade History

API Description

Retrieves historical trade execution data for a specific trader address. This endpoint provides detailed information about all executed trades including fill prices, quantities, fees, and trade types. Supports pagination and time range filtering.

HTTP Request

GET /v4/public/mm/execution/list

Request Parameters

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

Response Parameters

The response contains a data object with list (array of trades) and totalCount.

Parameter	Type	Description
data	object	Response data object
-> list	array	Array of trade objects
-> totalCount	uint32	Total number of trades matching the query
-> list[].id	string	Trade ID
-> list[].instrumentAddress	string	Instrument contract address
-> list[].expiry	uint32	Expiry timestamp (4294967295 for perpetual)
-> list[].size	string	Trade size
-> list[].balance	string	Account balance after trade
-> list[].price	string	Execution price (in wei/smallest unit)
-> list[].tradeFee	string	Trade fee amount
-> list[].protocolFee	string	Protocol fee amount
-> list[].timestamp	uint64	Trade timestamp (Unix timestamp in seconds)
-> list[].txHash	string	Transaction hash of the trade
-> list[].type	string	Trade type ("Limit" or "Market")
-> list[].symbol	string	Trading pair symbol (e.g., BTC/USDC)
-> list[].baseToken	object	Base token information
-> list[].baseToken.address	string	Token contract address
-> list[].baseToken.symbol	string	Token symbol
-> list[].baseToken.decimals	number	Token decimals
-> list[].baseToken.image	string	Token image URL
-> list[].baseToken.price	number	Token price (USD)
-> list[].quoteToken	object	Quote token information
-> list[].quoteToken.address	string	Token contract address
-> list[].quoteToken.symbol	string	Token symbol
-> list[].quoteToken.decimals	number	Token decimals
-> list[].quoteToken.image	string	Token image URL
-> list[].quoteToken.price	number	Token price (USD)
-> list[].typeString	string	Trade type string ("Limit" or "Market")
-> list[].side	string	Trade side ("long" or "short")
-> list[].event	string	Trade event ("fill" or "trade")

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': '0x8bcef483f1c9226c192430b8f5191ee801601480',
    '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/execution/list?{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/execution/list?{urlencode(params)}"
response = requests.get(url, headers=headers)
result = response.json()
print(json.dumps(result, indent=2))

Example with optional parameters:

# Build request path with time range and symbol filter
params = {
    'chainId': 143,
    'address': '0x8bcef483f1c9226c192430b8f5191ee801601480',
    'symbol': 'BTCUSDC',  # Optional: filter by symbol
    'startTime': 1765680000,  # Optional: start time in seconds
    'endTime': 1765728000,    # Optional: end time in seconds
    '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/execution/list?{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/execution/list?{urlencode(params)}"
response = requests.get(url, headers=headers)
result = response.json()
print(json.dumps(result, indent=2))

Response Example

Success Response

{
    "data": {
        "list": [
            {
                "id": "1030041973102000070",
                "instrumentAddress": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
                "expiry": 4294967295,
                "size": "0.0002237015659122",
                "balance": "4.031065",
                "price": "89404.8278949010963279",
                "tradeFee": "0",
                "protocolFee": "0",
                "timestamp": 1765712212,
                "txHash": "0xbb279c9171b6e423c44b2ff95016349e0f460b33d4bb3f014e8893b4d7a376a9",
                "type": "Limit",
                "symbol": "BTC/USDC",
                "baseToken": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "BTC",
                    "decimals": 18,
                    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
                    "price": 88786
                },
                "quoteToken": {
                    "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
                    "symbol": "USDC",
                    "decimals": 6,
                    "image": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694",
                    "price": 0.999948
                },
                "typeString": "Limit",
                "side": "long",
                "event": "fill"
            },
            {
                "id": "1030041538910000005",
                "instrumentAddress": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
                "expiry": 4294967295,
                "size": "0.0004156546063404",
                "balance": "38.4036813508708502",
                "price": "92396.1814459193622862",
                "tradeFee": "0.0076807362701742",
                "protocolFee": "0",
                "timestamp": 1765537789,
                "txHash": "0xc5c2d427b1d64fa6069d47467eca43fa7c58b207afb6b6c1e2c50dcf310e240c",
                "type": "Market",
                "symbol": "BTC/USDC",
                "baseToken": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "BTC",
                    "decimals": 18,
                    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
                    "price": 88786
                },
                "quoteToken": {
                    "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
                    "symbol": "USDC",
                    "decimals": 6,
                    "image": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694",
                    "price": 0.999948
                },
                "typeString": "Market",
                "side": "long",
                "event": "trade"
            }
        ],
        "totalCount": 5
    },
    "msg": "",
    "code": 0,
    "requestId": "8ce2593e-b527-46d0-9046-4ec98c5528a3"
}

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)

• Required parameters: chainId, address, page, size

• Optional parameters: symbol, startTime, endTime

• Pagination: Uses page and size parameters (not cursor-based)

• Page size: Maximum 200 records per page (default: 50)

• Time format: startTime and endTime are Unix timestamps in seconds (not milliseconds)

• Default time range: If not specified, startTime defaults to 0 and endTime defaults to current time

• Trade types:

  • type: "Limit" = Limit order execution

  • type: "Market" = Market order execution

• Trade side: "long" or "short" (string)

• Trade event:

  • event: "fill" = Order fill (limit order filled)

  • event: "trade" = Direct trade (market order or immediate execution)

• Price format: All prices are returned as strings in wei/smallest unit format to preserve precision

• Size and balance: Trade size and balance after trade

• Fees:

  • tradeFee: Trading fee amount

  • protocolFee: Protocol fee amount (usually 0)

• Timestamp: Unix timestamp in seconds (not milliseconds)

• Token information: Includes base and quote token details with current prices

• Symbol format: Returns as "BTC/USDC" format (with slash separator)

• Expiry: 4294967295 indicates a perpetual contract

• Response structure: Returns data object with list array and totalCount

• Difference from Order History: This endpoint returns executed trades only, while Order History includes both filled and cancelled orders

• Rate limit: 120 requests per minute

• Success response has code: 0 (not 200)