Get External User Purchases

Returns external user purchases for a distribution token within a date range. Both start_date and end_date are required and must be in ISO 8601 format (2006-01-02T15:04:05Z07:00).

Request

GET /v2/distributions/tokens/{tokenID}/purchases

Parameters

Name	Type	In	Description
tokenID	string	path	Required. Distribution token ID
start_date	string	query	Required. Range start, ISO 8601
end_date	string	query	Required. Range end, ISO 8601

Headers

Name	Description
Authorization	Required. Bearer token for authentication

Example

curl --request GET \
  --url '{{baseUrl}}/v2/distributions/tokens/67d8774e903bfcbe7eb5d93e/purchases?start_date=2025-01-01T00:00:00Z&end_date=2025-12-31T23:59:59Z' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Response

{
  "data": [
    {
      "id": "69120e5fe5064fdeaef6f057",
      "quantity": 10,
      "price": 100.0,
      "currency": {
        "symbol": "USDT",
        "decimal": 6,
        "address": "0x073c0196e516a0e77b1c804d1825fb1bad23895d"
      },
      "buyer_address": "0x1111111111111111111111111111111111111111",
      "seller_address": "0x4A096E485281DE1B8bF11A511D39d5B128EF7C4b",
      "market_id": "67d76014d9c4853c097bcf9a",
      "hash": "0xabc123...",
      "created_at": "2025-06-01T12:34:56Z"
    }
  ],
  "total": 1
}

Response Fields

Field	Type	Description
data	array	List of external purchases
data[].id	string	Purchase ID
data[].quantity	integer	Purchased quantity
data[].price	number	Unit price
data[].currency	object	Currency {symbol, decimal, address}
data[].buyer_address	string	Buyer wallet address
data[].seller_address	string	Seller wallet address
data[].market_id	string	Market ID
data[].hash	string	On-chain transaction hash
data[].created_at	string	Purchase timestamp (ISO 8601)
total	integer	Total number of purchases in the range

Status Codes

Status Code	Description
200	Success
400	Bad Request - Missing tokenID, start_date, or end_date, or invalid date format
401	Unauthorized - Invalid or missing authentication token
500	Internal Server Error