feat: list wallet addresses sorted by balance

TICKET: COIN-3909

Author: bhavidhingra

examples/ts/list-wallet-addresses-by-balance.ts

@@ -0,0 +1,28 @@
+/**
+ * List addresses by sorted balances on a wallet.
+ *
+ * Copyright 2025, BitGo, Inc.  All Rights Reserved.
+ */
+import { BitGoAPI } from '@bitgo/sdk-api';
+import {Tapt} from "@bitgo/sdk-coin-apt";
+require('dotenv').config({ path: '../../.env' });
+
+const bitgo = new BitGoAPI({
+  accessToken: process.env.TESTNET_ACCESS_TOKEN,
+  env: 'test',
+});
+
+const coin = 'tapt';
+bitgo.register(coin, Tapt.createInstance);
+
+const walletId = '';
+
+async function main() {
+  const wallet = await bitgo.coin(coin).wallets().get({ id: walletId });
+  const addresses = await wallet.addressesByBalance({
+    token: 'tapt:usdt',
+  });
+  console.log(JSON.stringify(addresses.addresses));
+}
+
+main().catch((e) => console.error(e));

modules/sdk-core/src/bitgo/wallet/iWallet.ts

@@ -284,6 +284,7 @@ export interface WalletCoinSpecific {
 }
 
 export interface PaginationOptions {
+  page?: number;
   prevId?: string;
   limit?: number;
 }
@@ -418,6 +419,11 @@ export interface AddressesOptions extends PaginationOptions {
   pendingDeployment?: boolean;
 }
 
+export interface AddressesByBalanceOptions extends PaginationOptions {
+  token: string;
+  sort?: number;
+}
+
 export interface GetAddressOptions {
   address?: string;
   id?: string;

modules/sdk-core/src/bitgo/wallet/wallet.ts

@@ -37,6 +37,7 @@ import {
 } from '../utils';
 import {
   AccelerateTransactionOptions,
+  AddressesByBalanceOptions,
   AddressesOptions,
   BuildConsolidationTransactionOptions,
   BuildTokenEnablementOptions,
@@ -1132,6 +1133,38 @@ export class Wallet implements IWallet {
       .result();
   }
 
+  /**
+   * List the addresses sorted by balance for a given wallet
+   * @param params
+   * @returns {*}
+   */
+  async addressesByBalance(params: AddressesByBalanceOptions): Promise<any> {
+    const query: AddressesByBalanceOptions = {
+      token: params.token,
+    };
+    query.sort = params.sort ?? -1;
+    query.page = params.page ?? 1;
+    query.limit = params.limit ?? 500;
+
+    if (!_.isNumber(query.sort)) {
+      throw new Error('invalid sort argument, expecting number');
+    }
+    if (!_.isNumber(query.page)) {
+      throw new Error('invalid page argument, expecting number');
+    }
+    if (!_.isNumber(params.limit)) {
+      throw new Error('invalid limit argument, expecting number');
+    }
+    if (params.limit < 1 || params.limit > 500) {
+      throw new Error('limit argument must be between 1 and 500');
+    }
+
+    return this.bitgo
+      .get(this.baseCoin.url('/wallet/' + this._wallet.id + '/addresses/balances'))
+      .query(query)
+      .result();
+  }
+
   /**
    * Get a single wallet address by its id
    * @param params