Get Token By User

Retrieve detailed information about a single token from the user-facing API.

Endpoint

GET /v2/users/tokens/{token_id}

How the Response Is Built

The handler does not read value and metric straight off the token document. It loads the token, then overlays the latest snapshot from token_histories:

1. Fetch the token document by ID.
2. Look up the most recent token_histories row for the token.
3. If found, overlay its value and metric onto the token before serialising.
4. Attach the latest rate-change windows (hourly / daily / weekly / monthly / quarterly).

This is what lets the admin context safely enqueue blockchain-pending updates: the tokens collection may already hold the speculative new value, but the user only sees it after the blockchain-confirm consumer writes a contract_confirm history row. Off-chain edits write the row synchronously and become visible on the very next read.

See Token History by ID for the snapshot shape and the change_reason enum.

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
token_id	string	Yes	The unique identifier of the token.

Response Schema

The response is the user-facing token DTO. The interesting blocks:

Field	Type	Description
id	string	Token ObjectID.
category_id	string	Category ObjectID.
node_id	string	Owning node ObjectID.
node_name	string	Owning node name.
created_by_id	string	Supervisor who created the token.
name / description	string	Display name and description.
token_name / token_symbol	string	On-chain token name and symbol.
origin	int32	0 = first_party, 1 = external (mirrors token.Origin).
standard	int32	ERC standard enum from token.Standard.
status	int32	Lifecycle status (none, not_listed, listed, passive, …).
is_mintable	boolean	Whether new supply can still be minted.
node_contract.diamond_address	string | null	Diamond proxy address of the owning node (when listed).
contract.address	string	Token contract address. Populated once the deploy has confirmed.
contract.tx_hash	string	Deploy transaction hash.
value	object	Overlayed from latest token_histories.value. See below.
metric	object | null	Overlayed from latest token_histories.metric. See below.
meta.images[]	array	{url, is_default}.
meta.documents[]	array	{id, name, url, type}.
distribution_token	object | null	Off-chain distribution-agent metadata.
hourly_rate_change / daily_rate_change / weekly_rate_change / monthly_rate_change / quarterly_rate_change	object | null	Rate-change windows computed from the history series.
created_at	string	ISO 8601 creation timestamp.

value Block

Field	Type	Description
token_price	{amount, decimal, symbol, address}	Price of a single token.
total_value	{amount, decimal, symbol, address}	token_price × max_supply.
salable_percentage	number	Percentage of supply that is salable.
salable_value	{amount, decimal, symbol, address}	total_value × salable_percentage / 100.
max_supply	integer	Cap on total supply.
listed_supply	integer	Supply currently listed for sale.
sold_supply	integer	Supply already sold.

metric Block

Field	Type	Description
term_duration_in_months	integer | null	Duration of the term.
min_purchase_quantity	integer	Minimum tokens per purchase.
max_purchase_quantity	integer	Maximum tokens per purchase.
min_tokens_required_for_rental_income	integer	Minimum holdings to qualify for rental income.
rental_income	{amount, decimal, symbol, address}	Income per payment period.
rental_payment_period_in_days	integer	Payment cadence in days.
rental_payment_start_date	string | null	When the first payment is due.
listing_date	string | null	When the token went live.

Example

Request

curl -X GET "\{\{baseUrl\}\}/v2/users/tokens/68aeb272d9336c619ce249f6" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}"

Response (abridged)

{
  "id": "68aeb272d9336c619ce249f6",
  "category_id": "667e9251ca818a2138ed4885",
  "origin": 0,
  "standard": 1,
  "node_id": "665ae536a6392b75cfd40352",
  "node_name": "Uber",
  "status": 3,
  "is_mintable": false,
  "name": "Sample Token",
  "description": "A sample token for demonstration purposes",
  "token_name": "Sample",
  "token_symbol": "STK",
  "node_contract": {
    "diamond_address": "0x730d22ae2267fc5b40520605868ddb48c29331a7"
  },
  "contract": {
    "address": "0x4ecde4...8387",
    "tx_hash": "0xab12..."
  },
  "value": {
    "token_price": {
      "amount": 1.12,
      "decimal": 6,
      "symbol": "VUSD",
      "address": "0xf2d90affe805280c004d0135343f2cbd7c96ce98"
    },
    "total_value": {
      "amount": 11200,
      "decimal": 6,
      "symbol": "VUSD",
      "address": "0xf2d90affe805280c004d0135343f2cbd7c96ce98"
    },
    "salable_percentage": 100,
    "salable_value": {
      "amount": 11200,
      "decimal": 6,
      "symbol": "VUSD",
      "address": "0xf2d90affe805280c004d0135343f2cbd7c96ce98"
    },
    "max_supply": 10000,
    "listed_supply": 9000,
    "sold_supply": 15
  },
  "metric": {
    "term_duration_in_months": 12,
    "min_purchase_quantity": 1,
    "max_purchase_quantity": 1000,
    "min_tokens_required_for_rental_income": 10,
    "rental_income": {
      "amount": 1,
      "decimal": 6,
      "symbol": "VUSD",
      "address": "0xf2d90affe805280c004d0135343f2cbd7c96ce98"
    },
    "rental_payment_period_in_days": 30,
    "rental_payment_start_date": "2026-03-06T12:17:20.996Z",
    "listing_date": "2026-02-04T12:17:20.996Z"
  },
  "meta": {
    "images": [{"url": "https://...", "is_default": true}],
    "documents": [{"id": "...", "name": "prospectus.pdf", "url": "https://...", "type": 1}]
  },
  "hourly_rate_change": null,
  "daily_rate_change": null,
  "weekly_rate_change": null,
  "monthly_rate_change": null,
  "quarterly_rate_change": null,
  "created_at": "2026-02-04T12:14:56.893Z"
}

Earlier docs were inaccurate

Earlier revisions of this page documented a flat shape (value: 1000, value_symbol: "USDT", total_supply, available_supply). The real DTO has been nested-objects-for-prices and value/metric snapshots since the token-history overlay landed; clients that consume the old shape will silently miss data. Update your parser to the schema above.

Error Responses

The integration returns its standard envelope ({code, domain, message}). Common cases:

Status	Cause
400	Invalid token ID format.
401	Missing / invalid bearer token.
403	Caller node does not have access to this token.
404	Token not found.
500	Internal server error.