Get Order History

API Description

Retrieves historical order data for a specific trader address. This endpoint provides comprehensive information about all past orders including filled and cancelled orders. Supports pagination and time range filtering.

HTTP Request

GET /v4/public/mm/order/history

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., BTC/USDC)
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 orders) and totalCount.

Parameter	Type	Description
data	object	Response data object
-> list	array	Array of order objects
-> totalCount	uint32	Total number of orders matching the query
-> list[].id	string	Order ID
-> list[].instrumentAddress	string	Instrument contract address
-> list[].expiry	uint32	Expiry timestamp (4294967295 for perpetual)
-> list[].placeTimestamp	uint64	Order placement timestamp (Unix timestamp in seconds)
-> list[].placeTxHash	string	Transaction hash of order placement
-> list[].size	string	Order size (absolute value)
-> list[].balance	string	Order balance (absolute value)
-> list[].takenSize	string	Filled size (absolute value)
-> list[].takenBalance	string	Filled balance (absolute value)
-> list[].orderPrice	string	Order price (in wei/smallest unit)
-> list[].feeRebate	string	Fee rebate amount
-> list[].type	uint32	Order type (0 = cancelled, 1 = filled)
-> list[].cancelTimestamp	uint64	Cancellation timestamp (0 if not cancelled)
-> list[].cancelTxHash	string	Cancellation transaction hash (empty if not cancelled)
-> list[].fillTimestamp	uint64	Fill timestamp (0 if not filled)
-> list[].fillTxHash	string	Fill transaction hash (empty if not filled)
-> 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	Order type string ("filled" or "cancelled")
-> list[].side	string	Order side ("long" or "short")
-> list[].tradeValue	string	Trade value (calculated from takenSize * orderPrice)

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/order/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/order/history?{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': 'BTC/USDC',  # 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/order/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/order/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": "1030041973102000070",
                "instrumentAddress": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
                "expiry": 4294967295,
                "placeTimestamp": 1765680175,
                "placeTxHash": "0x1a2e6497f3a3ef327c56ddd2636590936491221084fd88f59d05915d73104172",
                "size": "0.0002237015659122",
                "balance": "4.041065",
                "takenSize": "0.0002237015659122",
                "takenBalance": "4.031065",
                "orderPrice": "89404.8278949010963279",
                "feeRebate": "0",
                "type": 1,
                "cancelTimestamp": 0,
                "cancelTxHash": "",
                "fillTimestamp": 1765712212,
                "fillTxHash": "0xbb279c9171b6e423c44b2ff95016349e0f460b33d4bb3f014e8893b4d7a376a9",
                "symbol": "BTC/USDC",
                "baseToken": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "BTC",
                    "decimals": 18,
                    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
                    "price": 88808
                },
                "quoteToken": {
                    "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
                    "symbol": "USDC",
                    "decimals": 6,
                    "image": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694",
                    "price": 0.99998
                },
                "typeString": "filled",
                "side": "long",
                "tradeValue": "20.00000000020011477449576323381038"
            },
            {
                "id": "1030037809413000011",
                "instrumentAddress": "0x73ada1ea346cc3908f41cf67a040f0acd7808be0",
                "expiry": 4294967295,
                "placeTimestamp": 1763992563,
                "placeTxHash": "0xecc1dcd3536d04ff9d08b141f0c113c2f4d569cc99169c5afd53969318edf28f",
                "size": "0.0086697670422326",
                "balance": "75.201985",
                "takenSize": "0",
                "takenBalance": "0",
                "orderPrice": "85129.7985793148922166",
                "feeRebate": "0",
                "type": 0,
                "cancelTimestamp": 1764036818,
                "cancelTxHash": "0xfc77ccc065af9efa9948ed08729d9bf995ea1a8f100655742675b5043ddc7438",
                "fillTimestamp": 0,
                "fillTxHash": "",
                "symbol": "BTC/USDC",
                "baseToken": {
                    "address": "0x0000000000000000000000000000000000000000",
                    "symbol": "BTC",
                    "decimals": 18,
                    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
                    "price": 88808
                },
                "quoteToken": {
                    "address": "0x754704bc059f8c67012fed69bc8a327a5aafb603",
                    "symbol": "USDC",
                    "decimals": 6,
                    "image": "https://coin-images.coingecko.com/coins/images/6319/large/usdc.png?1696506694",
                    "price": 0.99998
                },
                "typeString": "cancelled",
                "side": "long",
                "tradeValue": "0"
            }
        ],
        "totalCount": 5
    },
    "msg": "",
    "code": 0,
    "requestId": "4e7b85b0-c3dd-4d52-84bc-8e35132001dd"
}

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

• Order types:

  • type: 0 = Cancelled order

  • type: 1 = Filled order

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

• Size and balance: All size and balance values are absolute values (positive)

• Taken fields: takenSize and takenBalance indicate how much of the order was filled

• Timestamps: All timestamps are Unix timestamps in seconds

• Transaction hashes: Empty string if the event hasn't occurred (e.g., cancelTxHash is empty for filled orders)

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

• Trade value: Calculated as takenSize * orderPrice (0 for cancelled orders)

• 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

• Rate limit: 120 requests per minute

• Success response has code: 0 (not 200)