> For the complete documentation index, see [llms.txt](https://docs.gradient.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gradient.trade/gradient-api/api-documentations.md).

# API documentations

## Gradient Orderbook API Reference

**Base URL:** `https://api.gradient.trade`

This is the complete API reference for the Gradient Orderbook API. All endpoints are rate-limited to **60 requests per minute** (1 request per second) based on IP address.

***

### Rate Limiting

All endpoints have a global rate limit of **60 requests per minute** (1 request per second).

* Rate limits are based on **IP address**
* When rate limit is exceeded, the API returns a `429 Too Many Requests` status code
* Rate limit headers are included in responses:
  * `X-RateLimit-Limit`: Maximum number of requests allowed
  * `X-RateLimit-Remaining`: Number of requests remaining in the current window
  * `X-RateLimit-Reset`: Time when the rate limit resets

#### Rate Limit Response

```json
{
  "success": false,
  "message": "Too many requests from this IP, please try again later."
}
```

***

### Health Check Endpoints

#### Get Server Status

Check if the server is running.

**Endpoint:** `GET https://api.gradient.trade/`

**Rate Limit:** 60 requests per minute

**Response:**

```json
{
  "success": true,
  "message": "Server is running",
  "timestamp": "2025-11-09T20:47:52.783Z"
}
```

***

#### Get Health Status

Check server health status.

**Endpoint:** `GET https://api.gradient.trade/health`

**Rate Limit:** 60 requests per minute

**Response:**

```json
{
  "success": true,
  "message": "Server is healthy",
  "timestamp": "2025-11-09T20:47:52.783Z"
}
```

***

#### Get Socket.IO Health

Check Socket.IO service status.

**Endpoint:** `GET https://api.gradient.trade/socket-health`

**Rate Limit:** 60 requests per minute

**Response:**

```json
{
  "success": true,
  "message": "Socket.IO service is running",
  "timestamp": "2025-11-09T20:47:52.783Z"
}
```

***

### System Status Endpoints

#### Get Retry Statistics

Get blockchain retry statistics.

**Endpoint:** `GET https://api.gradient.trade/retry-stats`

**Rate Limit:** 60 requests per minute

**Response:**

```json
{
  "success": true,
  "data": {
    // Retry statistics object
  },
  "timestamp": "2025-11-09T20:47:52.783Z"
}
```

**Error Response:**

```json
{
  "success": false,
  "message": "Failed to get retry statistics",
  "error": "Error message"
}
```

***

#### Get RPC Monitor Status

Get RPC monitor status.

**Endpoint:** `GET https://api.gradient.trade/rpc-monitor`

**Rate Limit:** 60 requests per minute

**Response:**

```json
{
  "success": true,
  "data": {
    // RPC monitor status object
  },
  "timestamp": "2025-11-09T20:47:52.783Z"
}
```

**Error Response:**

```json
{
  "success": false,
  "message": "Failed to get RPC monitor status",
  "error": "Error message"
}
```

***

### Order Endpoints

#### Get Active Orders

Get active orders for a specific token with pagination and filtering.

**Endpoint:** `GET https://api.gradient.trade/api/order/active`

**Rate Limit:** 60 requests per minute

**Query Parameters:**

| Parameter       | Type   | Required | Description                                   |
| --------------- | ------ | -------- | --------------------------------------------- |
| `tokenAddress`  | string | Yes      | Ethereum token address                        |
| `orderType`     | string | No       | Filter by order type: `buy` or `sell`         |
| `executionType` | string | No       | Filter by execution type: `limit` or `market` |
| `page`          | number | No       | Page number for pagination (default: 1)       |
| `limit`         | number | No       | Number of results per page (default: 10)      |

**Example Request:**

```bash
curl "https://api.gradient.trade/api/order/active?tokenAddress=0x123...&orderType=buy&page=1&limit=20"
```

**Response:**

```json
{
  "success": true,
  "message": "Active orders retrieved successfully",
  "data": [
    {
      "id": "order-id",
      "owner": "0x...",
      "orderType": "buy",
      "executionType": "limit",
      "token": {
        "address": "0x...",
        "symbol": "TOKEN",
        "decimals": 18,
        "logoURI": "https://...",
        "name": "Token Name"
      },
      "amount": "1000.0",
      "filledAmount": "500.0",
      "remainingAmount": "500.0",
      "filledPercent": 50.0,
      "price": "0.001",
      "executionPrice": null,
      "executionUsdPrice": null,
      "ethAmount": "1.0",
      "ethRemainingAmount": "0.5",
      "ethFilledAmount": "0.5",
      "expirationTime": 1234567890,
      "expiresIn": "2d 5h",
      "status": "active",
      "createdAt": "2025-01-13T12:00:00.000Z",
      "updatedAt": "2025-01-13T12:00:00.000Z",
      "usdPrice": null,
      "createTransactionHash": "0x...",
      "cancelTransactionHash": null,
      "expireTransactionHash": null,
      "fulfillTransactionHash": null,
      "partialFulfillTransactionHashes": []
    }
  ],
  "aggregates": {
    "totalSellRemainingAmount": "1000000000000000000",
    "totalSellRemainingAmountFormatted": "1.0",
    "totalBuyRemainingAmount": "2000000000000000000",
    "totalBuyRemainingAmountFormatted": "2.0",
    "tokenDecimals": 18,
    "priceInEth": "0.001"
  },
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 20,
    "hasNextPage": true,
    "hasPrevPage": false,
    "limit": 20
  }
}
```

**Error Responses:**

* `400 Bad Request` - Missing or invalid token address
* `404 Not Found` - Token not found

***

#### Get Order by ID

Get a specific order by its ID.

**Endpoint:** `GET https://api.gradient.trade/api/order/{orderId}`

**Rate Limit:** 60 requests per minute

**Path Parameters:**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `orderId` | string | Yes      | The order ID |

**Example Request:**

```bash
curl "https://api.gradient.trade/api/order/0x123abc..."
```

**Response:**

```json
{
  "success": true,
  "message": "Order retrieved successfully",
  "data": {
    "id": "0x123abc...",
    "owner": "0x...",
    "orderType": "sell",
    "executionType": "limit",
    "token": {
      "address": "0x...",
      "symbol": "TOKEN",
      "decimals": 18,
      "logoURI": "https://...",
      "name": "Token Name"
    },
    "amount": "1000.0",
    "filledAmount": "1000.0",
    "remainingAmount": "0.0",
    "filledPercent": 100.0,
    "price": "0.001",
    "executionPrice": "0.001",
    "executionUsdPrice": 1.5,
    "ethAmount": "1.0",
    "ethRemainingAmount": "0.0",
    "ethFilledAmount": "1.0",
    "expirationTime": 1234567890,
    "expiresIn": "Expired",
    "status": "filled",
    "createdAt": "2025-01-13T12:00:00.000Z",
    "updatedAt": "2025-01-13T12:00:00.000Z",
    "usdPrice": null,
    "createTransactionHash": "0x...",
    "cancelTransactionHash": null,
    "expireTransactionHash": null,
    "fulfillTransactionHash": "0x...",
    "partialFulfillTransactionHashes": []
  }
}
```

**Error Responses:**

* `400 Bad Request` - Missing order ID
* `404 Not Found` - Order not found

***

### Token Endpoints

#### Get Token Information

Get comprehensive token information including price, volume, and market data.

**Endpoint:** `GET https://api.gradient.trade/api/token/info`

**Rate Limit:** 60 requests per minute

**Query Parameters:**

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `address` | string | Yes      | Ethereum token address |

**Example Request:**

```bash
curl "https://api.gradient.trade/api/token/info?address=0x123..."
```

**Response:**

```json
{
  "success": true,
  "data": {
    "name": "Token Name",
    "symbol": "TOKEN",
    "chainId": 1,
    "logoURI": "https://...",
    "decimals": 18,
    "pairAddress": "0x...",
    "buyTax": 0,
    "sellTax": 0,
    "usdPrice": 1.5,
    "priceChange": 5.2,
    "volume24h": 1000000.0,
    "buyVolumeUsd24h": 600000.0,
    "sellVolumeUsd24h": 400000.0,
    "buySellRatio24h": 1.5,
    "marketCap": 10000000.0
  }
}
```

**Response Fields:**

| Field              | Type   | Description                      |
| ------------------ | ------ | -------------------------------- |
| `name`             | string | Token name                       |
| `symbol`           | string | Token symbol                     |
| `chainId`          | number | Blockchain chain ID              |
| `logoURI`          | string | Token logo URL                   |
| `decimals`         | number | Token decimals                   |
| `pairAddress`      | string | Liquidity pair address           |
| `buyTax`           | number | Buy tax percentage               |
| `sellTax`          | number | Sell tax percentage              |
| `usdPrice`         | number | Current USD price                |
| `priceChange`      | number | 24h price change percentage      |
| `volume24h`        | number | 24-hour trading volume in USD    |
| `buyVolumeUsd24h`  | number | 24-hour buy volume in USD        |
| `sellVolumeUsd24h` | number | 24-hour sell volume in USD       |
| `buySellRatio24h`  | number | Buy/sell ratio for last 24 hours |
| `marketCap`        | number | Market capitalization in USD     |

**Error Responses:**

* `400 Bad Request` - Missing or invalid token address
* `404 Not Found` - Token not found or invalid address

**Note:** If the token is not in the database, the API will fetch it from the blockchain and save it automatically. For new tokens, `volume24h` will be 0.

***

#### Get Token Reserves

Get token reserves (ETH and token reserves) from the liquidity pool.

**Endpoint:** `GET https://api.gradient.trade/api/token/token-reserves`

**Rate Limit:** 60 requests per minute

**Query Parameters:**

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `address` | string | Yes      | Ethereum token address |

**Example Request:**

```bash
curl "https://api.gradient.trade/api/token/token-reserves?address=0x123..."
```

**Response:**

```json
{
  "success": true,
  "data": {
    "reserveETH": "1000000000000000000",
    "reserveToken": "2000000000000000000"
  }
}
```

**Response Fields:**

| Field          | Type   | Description                               |
| -------------- | ------ | ----------------------------------------- |
| `reserveETH`   | string | ETH reserve in wei (raw format)           |
| `reserveToken` | string | Token reserve in token units (raw format) |

**Error Responses:**

* `400 Bad Request` - Missing or invalid token address

***

### Response Format

All API responses follow a consistent format:

#### Success Response

```json
{
  "success": true,
  "message": "Optional success message",
  "data": {
    /* Response data */
  },
  "pagination": {
    /* Pagination info if applicable */
  }
}
```

#### Error Response

```json
{
  "success": false,
  "message": "Error message",
  "error": "Detailed error information"
}
```

***

### Error Handling

The API uses standard HTTP status codes:

* `200 OK` - Request successful
* `400 Bad Request` - Invalid request parameters
* `404 Not Found` - Resource not found
* `429 Too Many Requests` - Rate limit exceeded
* `500 Internal Server Error` - Server error

All errors are handled by a global error handler and return consistent error response format.

***

### Code Examples

#### JavaScript/TypeScript

```typescript
// Get active orders
const response = await fetch(
  'https://api.gradient.trade/api/order/active?tokenAddress=0x123...&page=1&limit=20',
);
const data = await response.json();

// Get token info
const tokenResponse = await fetch('https://api.gradient.trade/api/token/info?address=0x123...');
const tokenData = await tokenResponse.json();
```

#### Python

```python
import requests

# Get active orders
response = requests.get(
    'https://api.gradient.trade/api/order/active',
    params={
        'tokenAddress': '0x123...',
        'page': 1,
        'limit': 20
    }
)
data = response.json()

# Get token info
token_response = requests.get(
    'https://api.gradient.trade/api/token/info',
    params={'address': '0x123...'}
)
token_data = token_response.json()
```

#### cURL

```bash
# Get active orders
curl "https://api.gradient.trade/api/order/active?tokenAddress=0x123...&page=1&limit=20"

# Get token info
curl "https://api.gradient.trade/api/token/info?address=0x123..."

# Get order by ID
curl "https://api.gradient.trade/api/order/0x123abc..."
```

***

### Security Features

* **CSRF Protection** - All endpoints are protected against CSRF attacks
* **Helmet** - Security headers are set automatically
* **CORS** - Configurable CORS policy
* **Rate Limiting** - IP-based rate limiting on all endpoints
* **Input Validation** - All inputs are validated before processing

***

### Support

For API support and questions, please contact the Gradient team.

**API Base URL:** `https://api.gradient.trade`