Get Token History by ID

Retrieves the history of changes for a specific token with pagination and filtering options.

Request

GET /v2/admin/tokens/{tokenID}/history

Parameters

Name	Type	In	Description
tokenID	string	path	Required. The ID of the token

Query Parameters

Name	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Items per page (default: 20)
start_date	string	No	Start date filter in ISO 8601 format (e.g., 2025-01-01T00:00:00Z)
end_date	string	No	End date filter in ISO 8601 format (e.g., 2025-12-31T23:59:59Z)
change_type	string	No	Filter by change type: value_update or metric_update
change_reason	string	No	Filter by change reason: manual_update, market_adjustment, or system_update
changed_by	string	No	Filter by the ID of the supervisor who made the change

Headers

Name	Description
Authorization	Required. Bearer token for authentication
Content-Type	Required. Must be application/json

Example

curl --location 'http://localhost:3453/v2/admin/tokens/6901599cbd0fb7ece2803764/history?page=1&per_page=20&start_date=2025-01-01T00%3A00%3A00Z&end_date=2025-12-31T23%3A59%3A59Z' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJRCI6IjhmMzEwOWExLTYyMmMtNDVhZC1hYjI4LTg0ODE5N2ZiMDYwYSIsImV4cGlyYXRpb24iOjE3NjMwNzg1MjQsInN1cGVydmlzb3JFbWFpbCI6InViZXJAYXBleC5jb20iLCJzdXBlcnZpc29ySUQiOiI2NjViMzcyZjNhNzJkN2QwNzkxNTk2YmEiLCJzdXBlcnZpc29yTm9kZUlEIjoiNjY1YWU1MzZhNjM5MmI3NWNmZDQwMzUyIiwic3VwZXJ2aXNvck5vZGVJbnRJRCI6MSwic3VwZXJ2aXNvck5vZGVQYXRoIjoiMSIsInN1cGVydmlzb3JSb2xlSUQiOiI2NjVhZTc5NjEwY2UyMTZkYmMzNWM5M2IiLCJzdXBlcnZpc29yUm9sZVByaW9yaXR5IjoxMDB9.5e1neSV0QQmYGIs42Z9qarTKY3pkSQWutDnl34xYg04'

Response

{
    "data": [
        {
            "id": "69015cb6bd0fb7ece2803767",
            "token_id": "6901599cbd0fb7ece2803764",
            "node_id": "6901350deb7ed8c1c38de4e9",
            "changed_by": "665b372f3a72d7d0791596ba",
            "change_type": "metric_update",
            "change_reason": "manual_update",
            "metric_change": {
                "term_duration_in_months": 10,
                "min_purchase_quantity": 1,
                "max_purchase_quantity": 10,
                "min_tokens_required_for_rental_income": 1,
                "rental_income": 12,
                "rental_income_currency_token_id": "",
                "rental_payment_period_in_days": 15
            },
            "created_at": "2025-10-29T00:15:50.99Z"
        }
    ],
    "total": 1,
    "page": 1,
    "per_page": 20
}

Response Fields

Field	Type	Description
data	array	List of token history records
data[].id	string	Unique identifier for the history record
data[].token_id	string	ID of the token
data[].node_id	string	ID of the associated node
data[].changed_by	string	ID of the supervisor who made the change
data[].change_type	string	Type of change: value_update or metric_update
data[].change_reason	string	Reason for the change: manual_update, market_adjustment, or system_update
data[].value_change	object | null	Value change data (present when change_type is value_update)
data[].metric_change	object | null	Metric change data (present when change_type is metric_update)
data[].created_at	string	ISO 8601 timestamp when the change was made
total	integer	Total number of history records
page	integer	Current page number
per_page	integer	Number of items per page

Value Change Data Fields

Field	Type	Description
total_value	object	Total value information (price object)
token_price	object	Token price information (price object)
salable_percentage	number	Percentage of tokens that are salable
listed_supply	integer	Number of tokens listed

Metric Change Data Fields

Field	Type	Description
term_duration_in_months	integer | null	Duration of the token term in months
min_purchase_quantity	integer	Minimum purchase quantity
max_purchase_quantity	integer	Maximum purchase quantity
min_tokens_required_for_rental_income	integer	Minimum tokens required for rental income
rental_income	number	Rental income amount
rental_income_currency_token_id	string	Currency token ID for rental income
rental_payment_period_in_days	integer	Rental payment period in days

Change Types

Value	Description
value_update	Update to token value/price information
metric_update	Update to token metrics (rental income, purchase limits, etc.)

Change Reasons

Value	Description
manual_update	Manual update by a supervisor
market_adjustment	Automatic adjustment based on market conditions
system_update	System-generated update

Status Codes

Status Code	Description
200	Success - Token history retrieved successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Token ID does not exist
500	Internal Server Error