# Introduction

Welcome to the Monday **Perpetual Trading** API documentation. This comprehensive guide will help you integrate with Monday's perpetual futures (perp) trading platform and access market data, trading functionality, and account management features.

> **Note:** This documentation covers the **Perpetual (Perp) API** only. It provides endpoints for perpetual futures trading, including order management, position handling, margin adjustments, and funding rate queries. Spot trading API documentation is maintained separately.

## What is Monday Perp API?

The Monday Perp API is a RESTful interface for perpetual futures trading that allows developers to:

* Access real-time and historical market data (instruments, orderbook, kline, tickers, funding)
* Manage API keys and One-Click Trade (1CT)
* Execute orders (market, limit, cancel, batch-cancel, fill) and close or adjust positions
* Prepare and submit approve transactions required before trading
* Query account balance, deposit/withdraw, and transaction history
* View open orders, order history, and trade (execution) history
* Manage liquidity positions and view liquidity history

## Key Features

### Real-time Market Data

* **Server Time**: Get synchronized server time
* **Instruments Info**: Retrieve trading instrument specifications
* **Kline Data**: Access candlestick chart data for technical analysis
* **Orderbook**: View real-time order book depth
* **Tickers**: Get 24-hour price statistics
* **Funding Rate History**: Track funding rate changes over time

### Account Management

* **Account Balance**: Check account balances and assets
* **Transaction History**: View deposit and withdrawal records
* **Position Management**: Monitor open positions and margin levels

### API Key Management

* **Create API Key**: Generate your first `apiKey` and `apiSecret` with wallet signature
* **List API Keys**: View existing API keys for the current wallet
* **Update API Key**: Adjust API key permissions and labels
* **Delete API Key**: Remove an API key you no longer need

### Trading Operations

* **Order Building**: Create market and limit orders with the required signing flow
* **Order Management**: Place, view, cancel, and batch-cancel orders
* **Order History**: Access historical order data
* **Trade Execution**: View detailed trade execution information
* **Margin Transfers**: Add or remove margin from positions
* **Approve Flow**: Prepare and submit approve transactions before trading

### Liquidity Provision

* **Liquidity Positions**: View active liquidity positions
* **Liquidity History**: Track liquidity addition and removal operations

## Getting Started

### 1. Create Your First API Key

To use the Monday API, you need to:

1. Create an account on the Monday platform
2. Call [Create API Key](https://developers.monday.trade/api-keys/create_apikey) to generate your first `apiKey` and `apiSecret`
3. Store the returned `apiSecret` securely because it is shown only once
4. Use those credentials in the [Quick Start Guide](https://developers.monday.trade/quick_start)

### 2. Read the Quick Start Guide

Before diving into the API, we recommend reading the [Quick Start Guide](https://developers.monday.trade/quick_start) which covers:

* Authentication setup
* Generating signatures
* Making your first API call
* Error handling
* Best practices

### 3. Explore the API

* Review the [Summary](https://github.com/MondayTrade/monday-gitbook/blob/main/perp/SUMMARY.md) for a complete list of available endpoints
* Check [Error Codes](https://developers.monday.trade/reference/error_codes) for error handling
* Reference [Enums](https://developers.monday.trade/reference/enums) for available values and types

## Base URL

All API requests should be made to:

```
https://api.monday.trade
```

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

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

## Authentication

All API endpoints require authentication using:

* **API Key** (`X-Api-Key`): Your public API key
* **Secret Key**: Your private secret key (used for signature generation)
* **Signature** (`X-Api-Sign`): HMAC-SHA256 signature with Base64 encoding
* **Timestamp** (`X-Api-Ts`): Request timestamp in milliseconds
* **Chain ID** (`X-Chain-Id`): Current chain identifier

The signature is generated using the format: `timestamp + method + request_path + body`

Detailed authentication instructions and code examples can be found in the [Quick Start Guide](https://developers.monday.trade/quick_start).

## Response Format

All API responses follow a standard format:

```json
{
    "code": 200,
    "msg": "",
    "data": {},
    "requestId": "bbf4fa1a-0f41-449f-8d9c-44fdceae0bf7"
}
```

### Success Response

```json
{
    "code": 200,
    "msg": "",
    "data": {
        // Response data here
    },
    "requestId": "bbf4fa1a-0f41-449f-8d9c-44fdceae0bf7"
}
```

### Error Response

```json
{
    "code": 400,
    "msg": "Error message here",
    "data": {},
    "requestId": "bbf4fa1a-0f41-449f-8d9c-44fdceae0bf7"
}
```

## Rate Limits

* **Rate Limit**: 120 requests per minute per API key
* **Rate limit headers**: Monitor your rate limit status via response headers
* **Best Practice**: Implement exponential backoff for retry logic

## Error Handling

### HTTP Status Codes

* **200**: Success
* **400**: Bad Request - Invalid parameters
* **401**: Unauthorized - Invalid API credentials
* **403**: Forbidden - Insufficient permissions
* **429**: Too Many Requests - Rate limit exceeded
* **500**: Internal Server Error

For detailed error codes and handling strategies, refer to [Error Codes Documentation](https://developers.monday.trade/reference/error_codes).

## Data Types

### String

Most text fields (symbols, addresses, etc.) are returned as strings.

### Number

Numeric values can be integers or decimals. Large numbers may be returned as strings to prevent precision loss.

### Timestamp

Timestamps are returned in milliseconds since Unix epoch.

### Address

Blockchain addresses (contract addresses, wallet addresses) are returned as hexadecimal strings.

## Security Best Practices

1. **Keep API Credentials Secure**
   * Never share your API Key or Secret Key
   * Don't commit API credentials to version control
   * Rotate API keys regularly
2. **Use HTTPS Only**
   * All API requests must use HTTPS
   * Never make API calls over HTTP
3. **Implement Proper Error Handling**
   * Handle all error responses gracefully
   * Implement retry logic with exponential backoff
   * Log errors for debugging
4. **Monitor Rate Limits**
   * Track your request rate
   * Implement rate limiting on your side
   * Avoid unnecessary API calls
5. **Validate Inputs**
   * Validate all parameters before making requests
   * Check data types and ranges
   * Use appropriate enums from the documentation

## Code Examples

The API documentation includes code examples in multiple languages:

* **cURL**: For command-line testing
* **JavaScript (Fetch)**: For web applications
* **Python (requests)**: For Python applications

You can find language-specific examples in each API endpoint documentation.

## Support and Resources

### Documentation

* [Quick Start Guide](https://developers.monday.trade/quick_start) - Get started quickly
* [Summary](https://github.com/MondayTrade/monday-gitbook/blob/main/perp/SUMMARY.md) - Complete endpoint reference
* [Error Codes](https://developers.monday.trade/reference/error_codes) - Error handling guide
* [Enums](https://developers.monday.trade/reference/enums) - Available values and types

### Getting Help

For API support and questions, please contact:

* Email: \[support email]
* Documentation: \[documentation URL]
* Community: \[community forum URL]

## Version Information

* **Current Version**: v4
* **Base URL**: <https://api.monday.trade/v4/public>
* **API Format**: RESTful
* **Data Format**: JSON

## Next Steps

1. Read the [Quick Start Guide](https://developers.monday.trade/quick_start)
2. Browse the [Summary](https://github.com/MondayTrade/monday-gitbook/blob/main/perp/SUMMARY.md)
3. Explore specific endpoint documentation
4. Implement error handling
5. Start building your integration

## Changelog

### Version 5

* Updated response format
* Added blockInfo to responses
* Improved error handling
* Enhanced documentation

***

Happy coding with Monday API!