Get External User Purchases

Returns the purchases of a token made on external markets (by buyers outside the platform) that were recorded within a date range, newest first. Purchases still waiting for chain confirmation are left out. The list is not paginated: every matching purchase is returned and total is their count.

The range filters on when the platform recorded the purchase; created_at in the response is the time of the purchase on chain, which can be earlier. The token is not checked: an unknown token id returns an empty list.

Required permission: distribution:view-purchases

Request

GET /v2/distributions/tokens/{token_id}/purchases?start_date={start_date}&end_date={end_date}

Parameters

Name	Type	In	Description
token_id	string	path	Required. The token's id on the platform (24-character hex)
start_date	string	query	Required. Start of the range, inclusive. RFC 3339 / ISO 8601 with a time zone, e.g. 2025-01-01T00:00:00Z
end_date	string	query	Required. End of the range, inclusive. Same format as start_date

Headers

Name	Description
Authorization	Required. Bearer <access_token>

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 <access_token>'

Response

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

Response Fields

Field	Type	Description
data	array	The purchases in the range, newest first
data[].id	string	Purchase id
data[].quantity	integer	Number of tokens bought
data[].price	string	Unit price paid, a decimal string (see Amounts and Percentages)
data[].currency	object	Currency the price is in: symbol, decimal (integer) and contract address
data[].buyer_address	string	Buyer's wallet address
data[].seller_address	string	Seller's address
data[].market_id	string	Id of the external market the purchase was made on
data[].hash	string	Hash of the purchase transaction
data[].created_at	string	Time of the purchase on chain (ISO 8601)
total	integer	Number of purchases in data

Errors

Status	Code	Description
400	10015	start_date or end_date is missing — see details
400	10016	token_id is not a valid 24-character hex id
500	10000	start_date or end_date is not in RFC 3339 format (message invalid start_date format / invalid end_date format), or an unexpected server-side failure

See Errors for the error format and common codes.