feat(NEB-461): support TRC20 token balances for inactive accounts

ulissesferreira · ulissesferreira · commit beea8e5bde75 · 2026-02-04T12:02:58.000Z
Add fallback TRC20 balance fetching for inactive Tron accounts using the
`/v1/accounts/{address}/trc20/balance` endpoint when the main account
info endpoint returns no data (inactive accounts that haven't paid the
1 TRX activation fee).

- Add `getTrc20BalancesByAddress()` method to TrongridApiClient
- Implement fallback logic in AssetsService for inactive accounts
- Add helper methods for zero-balance native assets and TRC20 extraction
- Add comprehensive unit tests for new functionality
diff --git a/packages/snap/CHANGELOG.md b/packages/snap/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Support fetching TRC20 token balances for inactive accounts using fallback endpoint ([#190](https://github.com/MetaMask/snap-tron-wallet/pull/190))
+
 ## [1.20.0]
 
 ### Added
diff --git a/packages/snap/snap.manifest.json b/packages/snap/snap.manifest.json
@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snap-tron-wallet.git"
   },
   "source": {
-    "shasum": "4ePTerkid6qLfLohShjnEntXl74FyR6QOKVMglucJdg=",
+    "shasum": "JhdOj9LvAjBQqH/ZCwM6V5aIKXXA+6mnWnfNTA7El5g=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",
diff --git a/packages/snap/src/clients/tron-http/TronHttpClient.ts b/packages/snap/src/clients/tron-http/TronHttpClient.ts
@@ -117,12 +117,14 @@ export class TronHttpClient {
   }
 
   /**
-   * Get account resources (Energy and Bandwidth)
+   * Get account resources (Energy and Bandwidth).
+   * For inactive accounts (not yet activated on-chain), returns an empty object `{}` with all resource values effectively being 0.
    *
    * @see https://developers.tron.network/reference/getaccountresource
-   * @param network - Network to query
-   * @param accountAddress - Account address in base58 format
-   * @returns Promise<AccountResources> - Account resources
+   * @param network - Network to query.
+   * @param accountAddress - Account address in base58 format.
+   * @returns Promise<AccountResources> - Account resources (energy, bandwidth, etc.).
+   * @throws Error - HTTP errors or configuration errors.
    */
   async getAccountResources(
     network: Network,
diff --git a/packages/snap/src/clients/trongrid/TrongridApiClient.test.ts b/packages/snap/src/clients/trongrid/TrongridApiClient.test.ts
@@ -0,0 +1,245 @@
+/* eslint-disable no-restricted-globals */
+/* eslint-disable @typescript-eslint/naming-convention */
+import { TrongridApiClient } from './TrongridApiClient';
+import type { Trc20Balance } from './types';
+import type { ICache } from '../../caching/ICache';
+import { Network } from '../../constants';
+import type { ConfigProvider } from '../../services/config';
+import type { Serializable } from '../../utils/serialization/types';
+import type { TronHttpClient } from '../tron-http/TronHttpClient';
+
+describe('TrongridApiClient', () => {
+  let client: TrongridApiClient;
+  let mockConfigProvider: ConfigProvider;
+  let mockTronHttpClient: jest.Mocked<TronHttpClient>;
+  let mockCache: jest.Mocked<ICache<Serializable>>;
+
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    mockConfigProvider = {
+      get: jest.fn().mockReturnValue({
+        trongridApi: {
+          baseUrls: {
+            [Network.Mainnet]: 'https://api.trongrid.io',
+            [Network.Nile]: 'https://nile.trongrid.io',
+            [Network.Shasta]: 'https://api.shasta.trongrid.io',
+          },
+        },
+      }),
+    } as unknown as ConfigProvider;
+
+    mockTronHttpClient = {
+      getAccountResources: jest.fn(),
+      getChainParameters: jest.fn(),
+      getNextMaintenanceTime: jest.fn(),
+    } as unknown as jest.Mocked<TronHttpClient>;
+
+    mockCache = {
+      get: jest.fn(),
+      set: jest.fn(),
+    } as unknown as jest.Mocked<ICache<Serializable>>;
+
+    client = new TrongridApiClient({
+      configProvider: mockConfigProvider,
+      tronHttpClient: mockTronHttpClient,
+      cache: mockCache,
+    });
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  describe('getTrc20BalancesByAddress', () => {
+    const mockAddress = 'TGJn1wnUYHJbvN88cynZbsAz2EMeZq73yx';
+
+    it('fetches and returns TRC20 balances for an address', async () => {
+      const mockTrc20Balances: Trc20Balance[] = [
+        { TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: '24249143' },
+        { TGPuQ7g7H8GsUEXhwvvJop4zCncurEh2ht: '88123456' },
+      ];
+
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: jest.fn().mockResolvedValueOnce({
+            data: mockTrc20Balances,
+            success: true,
+            meta: { at: 1770121997373, page_size: 4 },
+          }),
+        } as unknown as Response);
+
+      const result = await client.getTrc20BalancesByAddress(
+        Network.Mainnet,
+        mockAddress,
+      );
+
+      expect(result).toStrictEqual(mockTrc20Balances);
+      expect(global.fetch).toHaveBeenCalledWith(
+        `https://api.trongrid.io/v1/accounts/${mockAddress}/trc20/balance`,
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+          }),
+        }),
+      );
+    });
+
+    it('returns empty array when no TRC20 tokens are found', async () => {
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: jest.fn().mockResolvedValueOnce({
+            data: [],
+            success: true,
+            meta: { at: 1770121997373, page_size: 0 },
+          }),
+        } as unknown as Response);
+
+      const result = await client.getTrc20BalancesByAddress(
+        Network.Mainnet,
+        mockAddress,
+      );
+
+      expect(result).toStrictEqual([]);
+    });
+
+    it('returns empty array when data is undefined', async () => {
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: jest.fn().mockResolvedValueOnce({
+            success: true,
+            meta: { at: 1770121997373, page_size: 0 },
+          }),
+        } as unknown as Response);
+
+      const result = await client.getTrc20BalancesByAddress(
+        Network.Mainnet,
+        mockAddress,
+      );
+
+      expect(result).toStrictEqual([]);
+    });
+
+    it('throws error when network is not configured', async () => {
+      // Create a client with only mainnet configured
+      const limitedConfigProvider = {
+        get: jest.fn().mockReturnValue({
+          trongridApi: {
+            baseUrls: {
+              [Network.Mainnet]: 'https://api.trongrid.io',
+            },
+          },
+        }),
+      } as unknown as ConfigProvider;
+
+      const limitedClient = new TrongridApiClient({
+        configProvider: limitedConfigProvider,
+        tronHttpClient: mockTronHttpClient,
+        cache: mockCache,
+      });
+
+      await expect(
+        limitedClient.getTrc20BalancesByAddress(Network.Nile, mockAddress),
+      ).rejects.toThrow('No client configured for network: tron:3448148188');
+    });
+
+    it('throws error when HTTP request fails', async () => {
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 500,
+        } as unknown as Response);
+
+      await expect(
+        client.getTrc20BalancesByAddress(Network.Mainnet, mockAddress),
+      ).rejects.toThrow('HTTP error! status: 500');
+    });
+
+    it('throws error when API returns success: false', async () => {
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: jest.fn().mockResolvedValueOnce({
+            data: [],
+            success: false,
+            meta: { at: 1770121997373, page_size: 0 },
+          }),
+        } as unknown as Response);
+
+      await expect(
+        client.getTrc20BalancesByAddress(Network.Mainnet, mockAddress),
+      ).rejects.toThrow('API request failed');
+    });
+
+    it('works with different networks', async () => {
+      const mockTrc20Balances: Trc20Balance[] = [{ TTestToken123: '1000000' }];
+
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: jest.fn().mockResolvedValueOnce({
+            data: mockTrc20Balances,
+            success: true,
+            meta: { at: 1770121997373, page_size: 1 },
+          }),
+        } as unknown as Response);
+
+      const result = await client.getTrc20BalancesByAddress(
+        Network.Nile,
+        mockAddress,
+      );
+
+      expect(result).toStrictEqual(mockTrc20Balances);
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining('nile.trongrid.io'),
+        expect.any(Object),
+      );
+    });
+
+    it('validates TRC20 balance data structure', async () => {
+      // Valid structure: array of Record<string, string>
+      const validBalances: Trc20Balance[] = [
+        { TokenAddress1: '100' },
+        { TokenAddress2: '200' },
+      ];
+
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation()
+        .mockResolvedValueOnce({
+          ok: true,
+          json: jest.fn().mockResolvedValueOnce({
+            data: validBalances,
+            success: true,
+            meta: { at: 1770121997373, page_size: 2 },
+          }),
+        } as unknown as Response);
+
+      const result = await client.getTrc20BalancesByAddress(
+        Network.Mainnet,
+        mockAddress,
+      );
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toStrictEqual({ TokenAddress1: '100' });
+      expect(result[1]).toStrictEqual({ TokenAddress2: '200' });
+    });
+  });
+});
diff --git a/packages/snap/src/clients/trongrid/TrongridApiClient.ts b/packages/snap/src/clients/trongrid/TrongridApiClient.ts
@@ -2,12 +2,14 @@ import { assert } from '@metamask/superstruct';
 
 import {
   ContractTransactionInfoStruct,
+  Trc20BalanceStruct,
   TransactionInfoStruct,
   TronAccountStruct,
   TrongridApiMetaStruct,
 } from './structs';
 import type {
   ContractTransactionInfo,
+  Trc20Balance,
   TransactionInfo,
   TronAccount,
   TrongridApiResponse,
@@ -79,12 +81,15 @@ export class TrongridApiClient {
   }
 
   /**
-   * Get account information by address for a specific network. The returned data will also have assets information.
+   * Get account information by address for a specific network.
+   * The returned data includes TRX balance, TRC10 assets, and TRC20 token balances.
    *
    * @see https://developers.tron.network/reference/get-account-info-by-address
    * @param scope - The network to query (e.g., 'mainnet', 'shasta')
    * @param address - The TRON address to query
-   * @returns Promise<TronAccount> - Account data in camelCase
+   * @returns Promise<TronAccount> - Account data including balances.
+   * @throws Error - "Account not found or no data returned" for inactive accounts (accounts that haven't paid the 1 TRX activation fee don't exist on-chain).
+   * @throws Error - HTTP errors or API failures.
    */
   async getAccountInfoByAddress(
     scope: Network,
@@ -234,6 +239,57 @@ export class TrongridApiClient {
     return rawData.data;
   }
 
+  /**
+   * Get TRC20 token balances for an account address.
+   * This endpoint works for inactive accounts that haven't been activated yet.
+   *
+   * @see https://developers.tron.network/reference/get-trc20-token-holder-balances
+   * @param scope - The network to query (e.g., 'mainnet', 'shasta')
+   * @param address - The TRON address to query
+   * @returns Promise<Trc20Balance[]> - Array of TRC20 balances (contract address -> balance)
+   */
+  async getTrc20BalancesByAddress(
+    scope: Network,
+    address: string,
+  ): Promise<Trc20Balance[]> {
+    const client = this.#clients.get(scope);
+    if (!client) {
+      throw new Error(`No client configured for network: ${scope}`);
+    }
+
+    const { baseUrl, headers } = client;
+    const url = buildUrl({
+      baseUrl,
+      path: '/v1/accounts/{address}/trc20/balance',
+      pathParams: { address },
+    });
+
+    const response = await fetch(url, { headers });
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const rawData: TrongridApiResponse<Trc20Balance[]> = await response.json();
+
+    // Validate API response structure
+    if (typeof rawData.success !== 'boolean' || !rawData.success) {
+      throw new Error('API request failed');
+    }
+    assert(rawData.meta, TrongridApiMetaStruct);
+
+    if (!rawData.data) {
+      return [];
+    }
+
+    // Validate each TRC20 balance entry
+    for (const balance of rawData.data) {
+      assert(balance, Trc20BalanceStruct);
+    }
+
+    return rawData.data;
+  }
+
   /**
    * Get chain parameters for a specific network.
    * Results are cached until the next maintenance period (every ~6 hours).
diff --git a/packages/snap/src/clients/trongrid/structs.ts b/packages/snap/src/clients/trongrid/structs.ts
@@ -221,3 +221,22 @@ export const TrongridContractTransactionInfoResponseStruct = type({
   success: boolean(),
   meta: TrongridApiMetaStruct,
 });
+
+// --------------------------------------------------------------------------
+// TRC20 Balance Response Structs (for inactive account fallback)
+// --------------------------------------------------------------------------
+
+/**
+ * Struct for validating individual TRC20 balance entries.
+ * Each entry is a record mapping contract address to balance string.
+ */
+export const Trc20BalanceStruct = record(string(), string());
+
+/**
+ * Struct for validating the TRC20 balance API response.
+ */
+export const TrongridTrc20BalanceResponseStruct = type({
+  data: array(Trc20BalanceStruct),
+  success: boolean(),
+  meta: TrongridApiMetaStruct,
+});
diff --git a/packages/snap/src/clients/trongrid/types.ts b/packages/snap/src/clients/trongrid/types.ts
diff --git a/packages/snap/src/services/assets/AssetsService.test.ts b/packages/snap/src/services/assets/AssetsService.test.ts
diff --git a/packages/snap/src/services/assets/AssetsService.ts b/packages/snap/src/services/assets/AssetsService.ts
