List All Trades Paginated

This endpoint allows users to list trades using an API KEY.

Authentication

ATTENTION: You Need an API Key Token to Access This Endpoint!

Click here to learn how to create an API Key Token → (API Key Token Guide

This endpoint requires an API KEY token. The token must be sent in the api-token header.

Example:

--header 'api-token: xxxxxxxxxx'

If the token is missing, the API will return:

{
    "statusCode": 401,
    "status": "error",
    "timestamp": "2025-03-04T14:11:39.814Z",
    "path": "/token/trades",
    "data": {
        "message": "ApiKey not provided",
        "error": "Unauthorized",
        "statusCode": 401
    }
}

If the token is invalid, the API will return:

{
    "statusCode": 401,
    "status": "error",
    "timestamp": "2025-03-04T14:12:17.651Z",
    "path": "/token/trades",
    "data": {
        "message": "Invalid token",
        "error": "Unauthorized",
        "statusCode": 401
    }
}

Endpoints

Retrieve a trade by ID

Method: GET
URL: /token/trades/:id Authentication: Required (API KEY Token) Description: Retrieves a specific trade by its ID.

Request Example

curl --location 'https://api.zaffex.com/token/trades/01JCRQVVZ793NPMASQHZR4361T' \
--header 'api-token: <your_token_here>'

Success Response (200)

{
    "id": "01JCRQVVZ793NPMASQHZR4361T",
    "userId": "01J16JVXPMZN04TTW9ZVPGSTWQ",
    "tenantId": "01HZDQXAXT4XHT9PCXSF0DY333",
    "status": "CANCELLED",
    "symbol": "BTCUSDT",
    "amount": 20,
    "createdAt": "2024-11-15T20:22:37.287Z"
}

Open a new trade

Method: POST
URL: /token/trades/open Authentication: Required (API KEY Token) Description: Opens a new trade with the provided parameters.

Request Example

curl -X POST "https://api.zaffex.com/token/trades/open" \
  -H "api-token: <your_token_here>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTCUSDT",
    "volume": 1.5,
    "direction": "BUY"
  }'

Success Response (200)

{
    "tradeId": "01JCRQVVZ793NPMASQHZR4361T",
    "status": "OPEN"
}

Retrieve all trades

Method: GET
URL: /token/trades?page=1&pageSize=10 Authentication: Required (API KEY Token) Description: Retrieves all trades associated with the authenticated user.

Request Example

curl --location 'https://api.zaffex.com/token/trades?page=1&pageSize=10' \
--header 'api-token: <your_token_here>'

Success Response (200)

{
    "currentPage": 1,
    "perPage": 10,
    "lastPage": 33,
    "nextPage": 2,
    "prevPage": 1,
    "pages": 33,
    "total": 10,
    "count": 329,
    "data": [
        {
            "id": "01JCRQVVZ793NPMASQHZR4361T",
            "symbol": "BTCUSDT",
            "userId": "01J16JVXPMZN04TTW9ZVPGSTWQ",
            "amount": 20,
            "status": "CANCELLED",
            "createdAt": "2024-11-15T20:22:37.287Z"
        }
    ]
}

Retrieve All trades by User ID

Method: GET
URL: /token/trades?page=1&pageSize=10&userId=:id Authentication: Required (API KEY Token) Description: Retrieves all trades a specific trader by its ID.

Request Example

curl --location 'https://api.zaffex.com/token/trades?page=1&pageSize=10' \
--header 'api-token: <your_token_here>'

Success Response (200)

{
    "currentPage": 1,
    "perPage": 10,
    "lastPage": 33,
    "nextPage": 2,
    "prevPage": 1,
    "pages": 33,
    "total": 10,
    "count": 329,
    "data": [
        {
            "id": "01JVT5NSZFBBGDJ3YMW38YGR07",
            "affiliateId": "01J16K0A77M3FH1DSARTZ2X060",
            "isDemo": true,
            "isInfluencer": false,
            "fromBot": false,
            "fromApiToken": false,
            "tenantId": "01HZDQXAXT4XHT9PCXSF0DY333",
            "wallets": [
                {
                    "id": "01JTS65VH178Y4YKW84Z4JNQC4",
                    "type": "DEMO",
                    "amount": 10,
                    "tradePercent": 100,
                    "balancePercent": 0.09982032341784787,
                    "balance": 10018
                }
            ],
            "totalWalletsBalancePercent": 0.09982032341784787,
            "symbolSlotName": "default",
            "extraId": "01JVT5NSCNJKQZSYK9TDQJSXZ8",
            "symbol": "ETHUSDT",
            "userId": "01JTS65TJVVMXQY2VW0VW0VAS2",
            "payout": 90,
            "amount": 10,
            "fromCopy": false,
            "botSynced": true,
            "copyCommissionRate": 0,
            "copyCommissionAmount": 0,
            "status": "COMPLETED",
            "direction": "BUY",
            "expirationType": "CANDLE_CLOSE",
            "closeType": "01:00",
            "requestTime": 1747856319000,
            "openTime": 1747856340000,
            "openPrice": 2499.8,
            "openPriceTime": 1747856319469,
            "pnl": 9,
            "closePrice": 2506.54,
            "closeTime": 1747856400000,
            "closePriceTime": 1747856400033,
            "attemptsToClose": 1,
            "result": "WON",
            "tenantFeeAmount": 0,
            "createdAt": "2025-05-21T19:38:40.495Z",
            "updatedAt": "2025-05-22T22:36:51.610Z"
        }
    ]
}

Possible Errors

Status Code	Message	Description
401	Unauthorized	Token is missing or invalid
500	Internal Server Error	Unexpected server error

Usage Example

To retrieve a trade by ID using curl:

curl -X GET "https://api.zaffex.com/token/trades/01JCRQVVZ793NPMASQHZR4361T" \
  -H "api-token: <your_token_here>"

To open a trade using TypeScript with fetch:

async function openTrade(apiKey: string, tradeData: any): Promise<void> {
  try {
    const response = await fetch("https://api.zaffex.com/token/trades/open", {
      method: "POST",
      headers: {
        "api-token": apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(tradeData)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log("Trade opened:", data);
  } catch (error) {
    console.error("Error opening trade:", error);
  }
}

// Usage example:
openTrade("<your_api_key_here>", { symbol: "BTCUSDT", volume: 1.5, direction: "BUY" });