Get Token History

Returns one page of a token's history, newest first. Each row is a snapshot of the token's value, metric and meta (images and documents) at one change. User-facing token reads show the latest row, so the history is what investors see:

an off-chain change (Update Token or Update Token Metric without a transaction) writes a row at once, with change_reason: "offchain_update";
an on-chain change writes its row only when its transaction settles, with change_reason: "contract_confirm". Until then investors keep seeing the previous row.

Required permission: token:transactions:view

Request

GET /v2/admin/tokens/{token_id}/history?page=1&per_page=20

Parameters

Name	Type	In	Description
`token_id`	string	path	Required. Token id.
`page`	integer	query	Required. Page number, starting at 1.
`per_page`	integer	query	Required. Page size, 1 to 100.
`start_date`	string	query	Optional. Keep rows created at or after this time (RFC 3339, e.g. `2025-01-01T00:00:00Z`).
`end_date`	string	query	Optional. Keep rows created at or before this time (RFC 3339).
`changed_by`	string	query	Optional. Keep rows written by this supervisor.

Headers

Name	Description
`Authorization`	Required. `Bearer <access_token>`

Example

curl --request GET \
  --url '{{baseUrl}}/v2/admin/tokens/67d8774e903bfcbe7eb5d93e/history?page=1&per_page=20&start_date=2025-01-01T00:00:00Z&end_date=2025-12-31T23:59:59Z' \
  --header 'Authorization: Bearer <access_token>'

Response

{
  "data": [
    {
      "id": "698619c3309c93aca937c695",
      "token_id": "67d8774e903bfcbe7eb5d93e",
      "node_id": "67d6c447f47ff3adafda700d",
      "changed_by": "665b372f3a72d7d0791596ba",
      "change_type": "full_snapshot",
      "change_reason": "offchain_update",
      "value": {
        "token_price": {
          "id": "68fe8c129367fd414b227c7a",
          "amount": "9.6",
          "decimal": 6,
          "symbol": "USDT",
          "address": "0x073c0196e516a0e77b1c804d1825fb1bad23895d"
        },
        "max_supply": 1000,
        "total_value": {
          "id": "68fe8c129367fd414b227c7a",
          "amount": "12000",
          "decimal": 6,
          "symbol": "USDT",
          "address": "0x073c0196e516a0e77b1c804d1825fb1bad23895d"
        },
        "salable_percentage": "80",
        "salable_value": {
          "id": "68fe8c129367fd414b227c7a",
          "amount": "9600",
          "decimal": 6,
          "symbol": "USDT",
          "address": "0x073c0196e516a0e77b1c804d1825fb1bad23895d"
        },
        "purchased_supply": 0,
        "listed_supply": 800,
        "sold_supply": 200,
        "total_fee_supply": 30
      },
      "metric": {
        "term_duration_in_months": 12,
        "min_purchase_quantity": 1,
        "max_purchase_quantity": 100,
        "min_tokens_required_for_rental_income": 10,
        "rental_income": {
          "id": "68fe8c129367fd414b227c7a",
          "amount": "100",
          "decimal": 6,
          "symbol": "USDT",
          "address": "0x073c0196e516a0e77b1c804d1825fb1bad23895d"
        },
        "rental_payment_period_in_days": 30,
        "rental_payment_start_date": "2025-04-01T00:00:00Z",
        "listing_date": "2025-03-18T09:12:44.512Z",
        "expiration_date": null
      },
      "meta": {
        "images": [
          {
            "id": "67d8774e903bfcbe7eb5d93f",
            "url": "https://cdn.example.com/dev/token/67d8774e903bfcbe7eb5d93e/images/9e6e15fc-57ea-4de9-a2e1-9ee945908ce1.png",
            "is_default": true,
            "hash": "4b7e9f0c2d1a8e6b5c3f7a9d0e2b4c6a8f1d3e5b7c9a0f2e4d6b8a1c3e5f7a9b",
            "created_at": "2025-03-17T19:26:06.905Z"
          }
        ],
        "documents": [
          {
            "id": "67d8774e903bfcbe7eb5d940",
            "name": "prospectus.pdf",
            "url": "https://bucket.s3.amazonaws.com/dev/token/67d8774e903bfcbe7eb5d93e/documents/0d295c7d-fff2-40fc-a184-3119c14ef61a.pdf?X-Amz-Expires=900&X-Amz-Signature=...",
            "type": 1,
            "hash": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
            "created_at": "2025-03-17T19:26:06.905Z"
          }
        ]
      },
      "created_at": "2025-03-20T16:41:39.864Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Response Fields

Field	Type	Description
`data[].id`	string	History row id.
`data[].token_id`	string	Token id.
`data[].node_id`	string	Node of the token.
`data[].changed_by`	string	Supervisor who made the change. Absent when no supervisor did (an API client or a settlement).
`data[].change_type`	string	What the row holds, see `change_type` Enum.
`data[].change_reason`	string	Why it was written, see `change_reason` Enum.
`data[].value`	object	The token's `value` at that change: the fields of Get Token plus `total_fee_supply` (tokens reserved for fees).
`data[].metric`	object	The token's `metric` at that change, as in Get Token plus `expiration_date` (string \| null). Absent when the token had no metric.
`data[].meta`	object	Images and documents at that change. Absent when not recorded. Each image has `id`, `url`, `is_default`, `hash`, `created_at` and, once removed, `deleted_at`; each document has `id`, `name`, `url`, `type`, `hash`, `created_at` and, once removed, `deleted_at`.
`data[].created_at`	string	When the change was recorded (RFC 3339).
`total`	integer	Number of matching rows.
`page`	integer	Page number sent in the request.
`per_page`	integer	Page size sent in the request.

meta.documents[].url is a signed link that opens the document for 15 minutes and is minted on every read; do not store it. A document whose record points at another store is returned as recorded, and a document of an external token is signed by the owner installation it came from.

`change_type` Enum

Value	Meaning
`full_snapshot`	`value`, `metric` and `meta` are all recorded. Off-chain updates and settled on-chain updates write this type.
`value_update`	The row records a value change.
`metric_update`	The row records a metric change.

`change_reason` Enum

Value	Meaning
`offchain_update`	An off-chain update, written when the call returned.
`contract_confirm`	An on-chain update, written when its transaction settled.
`manual_update`	A manual change made outside the update endpoints.
`market_adjustment`	A market re-pricing.
`system_update`	A system write (maintenance or migration).

Errors

Status	Code	Description
400	`10015`	Validation failed (`page` or `per_page` missing or out of range, a date not in RFC 3339) — see `details`
400	`10016`	`token_id` or `changed_by` is not a valid id
400	`10001`	Token not found (token domain `5`)
403	`10005`	The caller's node does not cover the token's node (node domain `2`)

See Errors for the error format and common codes.

Request​

Parameters​

Headers​

Example​

Response​

Response Fields​

change_type Enum​

change_reason Enum​

Errors​