API documentations

Native Gradient APIs used to fetch real-time platform data.

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Error Response:

{
  "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:

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

Error Response:

{
  "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

Filter by order type: buy or sell

executionType

string

Filter by execution type: limit or market

page

number

Page number for pagination (default: 1)

limit

number

Number of results per page (default: 10)

Example Request:

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

Response:

{
  "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:

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

Response:

{
  "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:

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

Response:

{
  "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:

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

Response:

{
  "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

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

Error Response

{
  "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

// 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

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

# 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

PreviousConclusion NextOverview

Last updated 3 months ago

hashtagGradient Orderbook API Reference

hashtagRate Limiting

hashtagRate Limit Response

hashtagHealth Check Endpoints

hashtagGet Server Status

hashtagGet Health Status

hashtagGet Socket.IO Health

hashtagSystem Status Endpoints

hashtagGet Retry Statistics

hashtagGet RPC Monitor Status

hashtagOrder Endpoints

hashtagGet Active Orders

hashtagGet Order by ID

hashtagToken Endpoints

hashtagGet Token Information

hashtagGet Token Reserves

hashtagResponse Format

hashtagSuccess Response

hashtagError Response

hashtagError Handling

hashtagCode Examples

hashtagJavaScript/TypeScript

hashtagPython

hashtagcURL

hashtagSecurity Features

hashtagSupport

Gradient Orderbook API Reference

Rate Limiting

Rate Limit Response

Health Check Endpoints

Get Server Status

Get Health Status

Get Socket.IO Health

System Status Endpoints

Get Retry Statistics

Get RPC Monitor Status

Order Endpoints

Get Active Orders

Get Order by ID

Token Endpoints

Get Token Information

Get Token Reserves

Response Format

Success Response

Error Response

Error Handling

Code Examples

JavaScript/TypeScript

Python

cURL

Security Features

Support