/tvm/tokens endpoint (#286)

* add /tvm/tokens endpoint

* changeset

Author: YaroShkvorets

.changeset/whole-games-begin.md

@@ -0,0 +1,5 @@
+---
+"token-api": minor
+---
+
+Added /tvm/tokens metadata endpoint

src/routes/v1/tvm/index.ts

@@ -4,7 +4,7 @@ import dexes from './dexes/index.js';
 // import holders from './holders/index.js';
 import pools from './pools/index.js';
 import swaps from './swaps/index.js';
-// import tokens from './tokens/index.js';
+import tokens from './tokens/index.js';
 import transfers from './transfers/index.js';
 
 const router = new Hono();
@@ -14,7 +14,7 @@ router.route('/dexes', dexes);
 // router.route('/holders', holders);
 router.route('/pools', pools);
 router.route('/swaps', swaps);
-// router.route('/tokens', tokens);
+router.route('/tokens', tokens);
 router.route('/transfers', transfers);
 
 export default router;

src/routes/v1/tvm/tokens/tvm.ts

@@ -3,61 +3,45 @@ import { describeRoute, resolver, validator } from 'hono-openapi';
 import { z } from 'zod';
 import { config } from '../../../../config.js';
 import { handleUsageQueryError, makeUsageQueryJson } from '../../../../handleQuery.js';
-import { injectIcons } from '../../../../inject/icon.js';
-import { injectSymbol } from '../../../../inject/symbol.js';
 import { sqlQueries } from '../../../../sql/index.js';
 import {
     apiUsageResponseSchema,
     createQuerySchema,
     dateTimeSchema,
-    evmContractSchema,
-    evmNetworkIdSchema,
+    tvmContractSchema,
+    tvmNetworkIdSchema,
 } from '../../../../types/zod.js';
 import { validatorHook, withErrorResponses } from '../../../../utils.js';
 
 const querySchema = createQuerySchema({
-    network: { schema: evmNetworkIdSchema },
-    contract: { schema: evmContractSchema },
+    network: { schema: tvmNetworkIdSchema },
+    contract: { schema: tvmContractSchema },
 });
 
 const responseSchema = apiUsageResponseSchema.extend({
     data: z.array(
         z.object({
-            // -- block --
             last_update: dateTimeSchema,
             last_update_block_num: z.number(),
             last_update_timestamp: z.number(),
 
-            // -- contract --
-            contract: evmContractSchema,
+            contract: tvmContractSchema,
+            decimals: z.number().nullable(),
 
-            // -- contract --
             name: z.string().nullable(),
             symbol: z.string().nullable(),
-            decimals: z.number().nullable(),
-
-            // -- token --
-            circulating_supply: z.number(),
-            total_supply: z.number(),
-            holders: z.number(),
-
-            // -- chain --
-            network: evmNetworkIdSchema,
 
-            // -- icon --
-            icon: z.object({
-                web3icon: z.string(),
-            }),
+            network: z.string(),
         })
     ),
 });
 
 const openapi = describeRoute(
     withErrorResponses({
         summary: 'Token Metadata',
-        description: 'Returns ERC-20 token metadata including supply and holder count.',
+        description: 'Provides TVM token contract metadata.',
 
-        tags: ['EVM Tokens'],
+        tags: ['TVM Tokens'],
         security: [{ bearerAuth: [] }],
         responses: {
             200: {
@@ -70,20 +54,14 @@ const openapi = describeRoute(
                                 value: {
                                     data: [
                                         {
-                                            last_update: '2025-10-16 09:24:47',
-                                            last_update_block_num: 23589316,
-                                            last_update_timestamp: 1760606687,
-                                            contract: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
-                                            name: 'Wrapped Ether',
-                                            symbol: 'WETH',
-                                            decimals: 18,
-                                            circulating_supply: 2335108.0877502915,
-                                            total_supply: 2335107.8841477665,
-                                            holders: 3014993,
-                                            network: 'mainnet',
-                                            icon: {
-                                                web3icon: 'ETH',
-                                            },
+                                            last_update: '2025-11-05 14:57:51',
+                                            last_update_block_num: 77231165,
+                                            last_update_timestamp: 1762354671,
+                                            contract: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+                                            decimals: 6,
+                                            name: 'Tether USD',
+                                            symbol: 'USDT',
+                                            network: 'tron',
                                         },
                                     ],
                                 },
@@ -110,10 +88,7 @@ route.get('/', openapi, validator('query', querySchema, validatorHook), async (c
 
     const response = await makeUsageQueryJson(c, [query], params, {
         database: dbConfig.database,
-        clickhouse_settings: { query_cache_ttl: config.cacheDurations[1] },
     });
-    injectSymbol(response, params.network, true);
-    injectIcons(response);
     return handleUsageQueryError(c, response);
 });
 

src/sql/tokens_for_contract/tvm.sql

@@ -0,0 +1,31 @@
+WITH filtered_contract AS (
+    SELECT
+        timestamp AS last_update,
+        block_num AS last_update_block_num,
+        log_address AS contract
+    FROM trc20_transfer
+    WHERE log_address = {contract:String}
+    ORDER BY timestamp DESC
+    LIMIT 1
+),
+metadata AS
+(
+    SELECT
+        contract,
+        if(empty(name), NULL, name) AS name,
+        if(empty(symbol), NULL, symbol) AS symbol,
+        decimals
+    FROM metadata
+    WHERE contract = {contract:String}
+)
+SELECT
+    last_update,
+    last_update_block_num,
+    toUnixTimestamp(last_update) AS last_update_timestamp,
+    toString(fc.contract) AS contract,
+    decimals,
+    name,
+    symbol,
+    {network:String} AS network
+FROM filtered_contract AS fc
+LEFT JOIN metadata USING contract