# 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](/perp-trading-apis/api-keys/create_apikey.md) 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](/perp-trading-apis/quick_start.md)

### 2. Read the Quick Start Guide

Before diving into the API, we recommend reading the [Quick Start Guide](/perp-trading-apis/quick_start.md) 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](/perp-trading-apis/reference/error_codes.md) for error handling
* Reference [Enums](/perp-trading-apis/reference/enums.md) 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](/perp-trading-apis/quick_start.md).

## 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](/perp-trading-apis/reference/error_codes.md).

## 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](/perp-trading-apis/quick_start.md) - Get started quickly
* [Summary](https://github.com/MondayTrade/monday-gitbook/blob/main/perp/SUMMARY.md) - Complete endpoint reference
* [Error Codes](/perp-trading-apis/reference/error_codes.md) - Error handling guide
* [Enums](/perp-trading-apis/reference/enums.md) - 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](/perp-trading-apis/quick_start.md)
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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.monday.trade/perp-trading-apis/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.