Get Tokens By User

Search and paginate tokens visible to the caller.

Endpoint

POST /v2/users/tokens/search

How the Response Is Built

For every token in the page the handler overlays the latest token_histories value and metric snapshot onto the token document before serialising — the same overlay used by Get Token By User. Blockchain-pending updates therefore stay invisible to user-facing reads until the chain settles and a contract_confirm history row lands.

Headers

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

Request Body

{
  "page": 1,
  "per_page": 10,
  "node_id": "665ae536a6392b75cfd40352"
}

Field	Type	Required	Description
page	integer	Yes	1-indexed page number. Validates >= 1.
per_page	integer	Yes	Page size. Validates >= 1 and <= 100.
node_id	string	No	Restrict results to a single node.

Response

{
  "data": [ /* array of token objects, same shape as Get Token By User */ ],
  "total": 1,
  "page": 1,
  "per_page": 10
}

The pagination is a flat envelope (total, page, per_page) — there is no nested pagination object. The element shape inside data[] is the same DTO documented in Get Token By User.

Example

curl -X POST "\{\{baseUrl\}\}/v2/users/tokens/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}" \
  -d '{
    "page": 1,
    "per_page": 10,
    "node_id": "665ae536a6392b75cfd40352"
  }'

Response (abridged)

{
  "data": [
    {
      "id": "68aeb272d9336c619ce249f6",
      "name": "Sample Token",
      "token_name": "Sample",
      "token_symbol": "STK",
      "status": 3,
      "value": {
        "token_price": { "amount": 1.12, "decimal": 6, "symbol": "VUSD", "address": "0xf2d9..." },
        "total_value": { "amount": 11200, "decimal": 6, "symbol": "VUSD", "address": "0xf2d9..." },
        "salable_percentage": 100,
        "salable_value": { "amount": 11200, "decimal": 6, "symbol": "VUSD", "address": "0xf2d9..." },
        "max_supply": 10000,
        "listed_supply": 9000,
        "sold_supply": 15
      },
      "metric": { /* see Get Token By User */ },
      "created_at": "2026-02-04T12:14:56.893Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 10
}

Earlier docs were inaccurate

Earlier revisions of this page documented a flat value / value_symbol / total_supply shape and a nested pagination: {current_page, total_pages} envelope. Neither matches the actual handler — the production response uses the nested-objects value block and the flat pagination envelope shown above.

Error Responses

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

Status	Cause
400	Invalid pagination (page < 1, per_page outside [1,100]).
401	Missing / invalid bearer token.
403	Caller node does not have access to the requested node's tokens.
404	No tokens matched the request.
500	Internal server error.