Retrieve Trades

GET /api/v1/trades

Description

Retrieves a list of trades, allowing for detailed analysis based on search terms, date ranges, status, and other filtering criteria. This endpoint supports extensive filtering and sorting to provide tailored insights into business transactions.

Headers:

• tenantId (required): The tenant ID under which the trades are registered. This should be included as a header.
• userId (required): The user ID of the individual requesting the trade information. This should also be included as a header.
• countryCode (required): The country code where the trades are processed. This should be included as a header.

Query Parameters:

• tradeSearch (optional): A general search term to filter the trades.
• tradeDateRange (optional): Filters the trades by a specific date range. Format: start_date,end_date (e.g., 2020-11-12,2022-11-15).
• tradeStatuses (optional): Filters the trades by their current statuses. Available values: ACTIVE, CLOSED, DRAFT, TERMINATED.
• tradeByProductIds (optional): Filters the trades based on specific product IDs.
• tradeIds (optional): Filters the trades based on specific trade IDs.
• byStates (optional): Filters trades by states.
• byCities (optional): Filters trades by cities.
• byBusinessIds (optional): Filters trades by business IDs.
• order (optional): Specifies the order of the results. Available values: ASC, DESC.
• page (optional): Specifies the pagination page.
• limit (optional): Specifies the number of results per page.

Example Request:

curl -G "http://[base_url]/api/v1/trades" \
     -H "Authorization: Bearer [access_token]" \
     -H "tenantId: TEN123" \
     -H "userId: USR456" \
     -H "countryCode: US" \
     -d "tradeSearch=oil" \
     -d "tradeDateRange=2020-11-12,2022-11-15" \
     -d "tradeStatuses=ACTIVE" \
     -d "tradeByProductIds=123,124" \
     -d "tradeIds=1001,1002" \
     -d "byStates=California" \
     -d "byCities=San Francisco" \
     -d "byBusinessIds=BIZ123" \
     -d "order=ASC" \
     -d "page=1" \
     -d "limit=10"

Responses:

• 200 OK: Successfully retrieved the list of trades. The response includes detailed information about each trade that matches the specified criteria.

Example Response:

{
  "trades": [
    {
      "tradeId": "1001",
      "product": "Crude Oil",
      "quantity": 5000,
      "unitPrice": 50,
      "totalAmount": 250000,
      "status": "ACTIVE",
      "dateInitiated": "2021-01-01",
      "buyer": "Global Industries",
      "seller": "OilCorp",
      "tradeDetails": {
        "state": "California",
        "city": "San Francisco"
      }
    }
  ],
  "totalItems": 20,
  "totalPages": 2,
  "currentPage": 1
}

Error Responses:

• 400 Bad Request: Incorrect or incomplete query parameters.
• 404 Not Found: No trades found based on the provided criteria.
• 403 Forbidden: The user does not have permission to view the trade details.