Quick Start Guide

Overview

This guide provides a comprehensive overview of how to use the Monday API endpoints. It covers the essential steps from authentication to making your first API call.

Important: All API endpoints require authentication.

Prerequisites

Before you begin, ensure you have:

• A Monday account

• API credentials:

  • API Key: Your public API key

  • Secret Key: Your private secret key (keep this secure!)

  • Passphrase: Required for API authentication

• Basic understanding of REST APIs

• Your preferred programming language environment set up (Python recommended for API examples)

Authentication

All API endpoints (prefixed with /v4/public/mm/) require authentication using HMAC-SHA256 signature authentication.

API Authentication

API endpoints (prefixed with /v4/public/mm/) use HMAC-SHA256 signature authentication.

Required Headers

X-ACCESS-KEY: [your_api_key]
X-ACCESS-SIGN: [signature]
X-ACCESS-TIMESTAMP: [timestamp]
X-ACCESS-PASSPHRASE: [your_passphrase]

Signature Generation

The signature is generated using HMAC-SHA256 and Base64 encoding:

Message Format:

message = timestamp + method + request_path + body

Signature Calculation:

signature = base64(hmac_sha256(message, secret_key))

Python Implementation Example

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

def compute_signature(message, secret_key):
    """Compute HMAC-SHA256 signature"""
    mac = hmac.new(
        secret_key.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    )
    return base64.b64encode(mac.digest()).decode('utf-8')

def sort_query_string(query_string):
    """Sort query parameters alphabetically (for GET requests)"""
    if not query_string:
        return ""
    params = parse_qs(query_string, keep_blank_values=True)
    sorted_params = []
    for key in sorted(params.keys()):
        for value in params[key]:
            sorted_params.append(f"{key}={value}")
    return "&".join(sorted_params)

def sort_json_keys(json_str):
    """Sort JSON keys alphabetically (for POST JSON requests)"""
    if not json_str:
        return ""
    try:
        data = json.loads(json_str)
        return json.dumps(data, sort_keys=True, separators=(',', ':'))
    except json.JSONDecodeError:
        return json_str

def build_message(timestamp, method, request_path, body="", content_type=""):
    """Build signature message"""
    method = method.upper()
    
    # Handle GET request query parameters
    if method == "GET" and "?" in request_path:
        path, query = request_path.split("?", 1)
        sorted_query = sort_query_string(query)
        request_path = f"{path}?{sorted_query}"
    
    # Handle POST request JSON body
    if method in ["POST", "PUT", "PATCH"] and body:
        if content_type and "application/json" in content_type.lower():
            body = sort_json_keys(body)
    
    return timestamp + method + request_path + body

def generate_mm_signature(secret_key, timestamp, method, request_path, body="", content_type=""):
    """Generate API signature"""
    message = build_message(timestamp, method, request_path, body, content_type)
    return compute_signature(message, secret_key)

Important Notes for API

1. Timestamp Format: Use ISO 8601 UTC format (e.g., 2020-12-08T09:08:57.715Z)

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

2. Time Window: Requests are valid within 30 seconds of the timestamp

3. GET Requests: Query parameters must be sorted alphabetically by key

   • Example: symbol=BTCUSDT&side=buy&amount=0.001 → amount=0.001&side=buy&symbol=BTCUSDT

4. POST Requests:

   • JSON body keys must be sorted alphabetically

   • Use compact JSON format (no spaces): json.dumps(data, sort_keys=True, separators=(',', ':'))

   • Form body: No sorting required, maintain original order

Base URL

All API requests should be made to:

https://api.monday.trade

API endpoints use the path prefix /v4/public/mm/, so the full URL format is:

https://api.monday.trade/v4/public/mm/{endpoint}

Important: When generating signatures, use the full path including /v4/public/mm/ (e.g., /v4/public/mm/serverTime).

Step-by-Step Examples

API Examples

Step 1: Get Server Time (API)

First, synchronize with the server time:

import hmac
import hashlib
import base64
import json
import requests
from datetime import datetime, timezone

def generate_mm_signature(secret_key, timestamp, method, request_path, body="", content_type=""):
    """Generate API signature"""
    # Build message: timestamp + method + request_path + body
    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():
            # Sort JSON keys
            data = json.loads(body)
            body = json.dumps(data, sort_keys=True, separators=(',', ':'))
        message += body
    
    # Compute HMAC-SHA256 signature
    mac = hmac.new(
        secret_key.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    )
    return base64.b64encode(mac.digest()).decode('utf-8')

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

# Generate signature
request_path = "/v4/public/mm/serverTime"
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,
}

response = requests.get("https://api.monday.trade/v4/public/mm/serverTime", headers=headers)
data = response.json()
print("Server time:", data)

Step 2: Get Orderbook (API)

Retrieve orderbook data:

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

# Build request path with sorted query parameters
# Note: Query parameters must be sorted alphabetically
request_path = "/v4/public/mm/orderBook?limit=100&symbol=BTCUSDT"  # limit comes before symbol alphabetically
signature = generate_mm_signature(secret_key, timestamp, "GET", request_path)

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

response = requests.get(
    "https://api.monday.trade/v4/public/mm/orderBook?symbol=BTCUSDT&limit=100",
    headers=headers
)
data = response.json()
print("Orderbook:", data)

Step 3: Get Account Balance (API)

Retrieve your account balance:

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

# Build request path
request_path = "/v4/public/mm/account/wallet-balance"
signature = generate_mm_signature(secret_key, timestamp, "GET", request_path)

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

response = requests.get("https://api.monday.trade/v4/public/mm/account/wallet-balance", headers=headers)
data = response.json()
print("Account balance:", data)

Step 4: POST Request Example (API)

Example of a POST request with JSON body:

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

# Build request path
request_path = "/v4/public/mm/orders"

# Prepare body (will be sorted by keys)
body_data = {
    "symbol": "BTCUSDT",
    "side": "buy",
    "amount": "0.001",
    "price": "50000"
}
body = json.dumps(body_data, sort_keys=True, separators=(',', ':'))

# Generate signature (body will be sorted)
signature = generate_mm_signature(secret_key, timestamp, "POST", request_path, body, "application/json")

headers = {
    "X-ACCESS-KEY": api_key,
    "X-ACCESS-SIGN": signature,
    "X-ACCESS-TIMESTAMP": timestamp,
    "X-ACCESS-PASSPHRASE": passphrase,
    "Content-Type": "application/json",
}

response = requests.post("https://api.monday.trade/v4/public/mm/orders", headers=headers, data=body)
data = response.json()
print("Order placed:", data)

Error Handling

Always implement proper error handling:

try {
    const response = await fetch(apiUrl, options);
    const data = await response.json();

    if (data.code !== 200) {
        console.error("API Error:", data.msg);
        return;
    }

    // Process successful response
    console.log("Success:", data.data);
} catch (error) {
    console.error("Request failed:", error);
}

Rate Limits

Be aware of rate limits:

• All Endpoints: 120 requests per minute

Implement rate limiting in your application to avoid hitting these limits.

Common Parameters

Category Types

• spot: Spot trading

• linear: Linear perpetual contracts

• inverse: Inverse perpetual contracts

• option: Options trading

Account Types

• UNIFIED: Unified trading account

• CONTRACT: Derivatives account

• SPOT: Spot trading account

Order Status

• New: New order

• PartiallyFilled: Partially filled

• Filled: Completely filled

• Cancelled: Cancelled

• Rejected: Rejected

Best Practices

1. Use HTTPS

Always use HTTPS for API requests to ensure data security.

2. Handle Timestamps

• Use server time for synchronization

• Include proper timestamp in requests

• Account for network latency

3. Implement Retry Logic

async function apiCallWithRetry(url, options, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await fetch(url, options);
            if (response.ok) {
                return await response.json();
            }
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
        }
    }
}

4. Validate Responses

Always validate API responses before processing:

function validateResponse(data) {
    if (!data || typeof data.code === "undefined") {
        throw new Error("Invalid response format");
    }

    if (data.code !== 200) {
        throw new Error(`API Error: ${data.msg}`);
    }

    return data.data;
}

5. Use Pagination

For endpoints that return large datasets, use pagination:

async function getAllData(endpoint, params = {}) {
    let allData = [];
    let cursor = null;

    do {
        const response = await fetch(
            `${endpoint}?${new URLSearchParams({
                ...params,
                limit: 50,
                ...(cursor && { cursor }),
            })}`
        );

        const data = await response.json();
        allData = allData.concat(data.data);
        cursor = data.data.nextPageCursor;
    } while (cursor);

    return allData;
}

Testing Your Setup

Test your API setup with this Python script:

import hmac
import hashlib
import base64
import json
import requests
from datetime import datetime, timezone

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')

def test_mm_api_setup():
    """Test API setup"""
    try:
        # Test 1: Get server time
        timestamp = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
        request_path = "/v4/public/mm/serverTime"
        signature = generate_mm_signature(secret_key, timestamp, "GET", request_path)
        
        headers = {
            "X-ACCESS-KEY": api_key,
            "X-ACCESS-SIGN": signature,
            "X-ACCESS-TIMESTAMP": timestamp,
            "X-ACCESS-PASSPHRASE": passphrase,
        }
        
        response = requests.get("https://api.monday.trade/v4/public/mm/serverTime", headers=headers)
        time_data = response.json()
        print("✓ Server time:", time_data)
        
        # Test 2: Get orderbook
        timestamp = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
        request_path = "/v4/public/mm/orderBook?limit=50&symbol=BTCUSDT"  # Sorted: limit before symbol
        signature = generate_mm_signature(secret_key, timestamp, "GET", request_path)
        
        headers = {
            "X-ACCESS-KEY": api_key,
            "X-ACCESS-SIGN": signature,
            "X-ACCESS-TIMESTAMP": timestamp,
            "X-ACCESS-PASSPHRASE": passphrase,
        }
        
        response = requests.get(
            "https://api.monday.trade/v4/public/mm/orderBook?symbol=BTCUSDT&limit=50",
            headers=headers
        )
        orderbook_data = response.json()
        print("✓ Orderbook retrieved")
        
        # Test 3: Get account balance
        timestamp = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
        request_path = "/v4/public/mm/account/wallet-balance"
        signature = generate_mm_signature(secret_key, timestamp, "GET", request_path)
        
        headers = {
            "X-ACCESS-KEY": api_key,
            "X-ACCESS-SIGN": signature,
            "X-ACCESS-TIMESTAMP": timestamp,
            "X-ACCESS-PASSPHRASE": passphrase,
        }
        
        response = requests.get("https://api.monday.trade/v4/public/mm/account/wallet-balance", headers=headers)
        balance_data = response.json()
        print("✓ Account balance retrieved")
        
        print("✓ All tests passed!")
    except Exception as e:
        print(f"✗ Test failed: {e}")

# Run tests
if __name__ == "__main__":
    # Set your credentials
    api_key = "your-api-key"
    secret_key = "your-secret-key"
    passphrase = "your-passphrase"
    
    test_mm_api_setup()

API Endpoints

The API provides the following endpoints (all prefixed with /v4/public/mm/):

• /v4/public/mm/serverTime - Get server time

• /v4/public/mm/kline - Get kline/candlestick data

• /v4/public/mm/instruments-info - Get instrument information

• /v4/public/mm/tickers - Get ticker data

• /v4/public/mm/funding/history - Get funding rate history

• /v4/public/mm/orderBook - Get orderbook data

• /v4/public/mm/order/realTime - Get open orders

• /v4/public/mm/order/history - Get order history

• /v4/public/mm/execution/list - Get trade execution history

• /v4/public/mm/position/list - Get position information

• /v4/public/mm/liquidity/list - Get liquidity positions

• /v4/public/mm/liquidity/history - Get liquidity history

• /v4/public/mm/account/wallet-balance - Get account balance

• /v4/public/mm/account/transaction-history - Get transaction history

• /v4/public/mm/token/tokensWithAddress - Get tokens with addresses

• /v4/public/mm/token/coinsWithSymbol - Get coins with symbols

Next Steps

1. Set Up Authentication: Ensure your API credentials (API Key, Secret Key, and Passphrase) are properly configured

2. Test Basic Endpoints: Start with simple endpoints like /v4/public/mm/serverTime

3. Understand Signature Requirements:

   • GET requests: Sort query parameters alphabetically

   • POST requests: Sort JSON keys alphabetically

   • Use ISO 8601 UTC timestamp format

4. Explore Market Data: Access market data endpoints to understand available instruments

5. Check Account Status: Verify your account balance and permissions

6. Monitor Positions: Use position endpoints to track your current positions

7. Review Order History: Analyze your trading history and performance

8. Implement Trading Logic: Build your trading strategies using the API

Support

For additional help:

• Check the individual API documentation files

• Review error codes and messages

• Ensure your API keys have the correct permissions

• Verify your request format matches the documentation

Security Notes

• Never expose your API secret key or passphrase in client-side code

• Use environment variables for API credentials

• Implement proper access controls

• Monitor your API usage regularly

• Rotate your API keys periodically

• Keep your passphrase secure - it's required for API authentication

• Ensure timestamps are accurate - requests expire after 30 seconds for API

Troubleshooting

Common Issues with API

1. Signature Mismatch

   • Verify query parameters are sorted alphabetically for GET requests

   • Ensure JSON keys are sorted alphabetically for POST requests

   • Check timestamp format (must be ISO 8601 UTC)

   • Verify the message format: timestamp + method + request_path + body

2. Invalid Timestamp

   • Ensure your system clock is synchronized

   • Use UTC timezone for timestamps

   • Timestamp must be within 30 seconds of server time

   • Format: YYYY-MM-DDTHH:MM:SS[.ms]Z (e.g., 2020-12-08T09:08:57.715Z)

3. API Key Not Found

   • Verify your API key is correct

   • Check if the API key is active

   • Ensure you're using the correct base URL

4. Passphrase Mismatch

   • Verify your passphrase matches the one associated with your API key

   • Passphrase is case-sensitive