TypeScript SDK: View and Query
Purpose
Guide read-only access to chain data in @aptos-labs/ts-sdk : view functions, balance, account info, resources, and modules.
ALWAYS
-
Use aptos.getBalance({ accountAddress }) for APT balance – not deprecated getAccountCoinAmount / getAccountAPTAmount .
-
Use aptos.view() for Move view functions – pass function , functionArguments , and optional typeArguments .
-
Use bigint for u128/u256 view return values – cast result[0] to BigInt(...) when the Move function returns u128/u256.
-
Pass address as string or AccountAddress – SDK accepts AccountAddressInput (string or AccountAddress ).
NEVER
-
Do not use deprecated getAccountCoinAmount or getAccountAPTAmount – use getBalance() .
-
Do not use number for u128/u256 – precision loss; use bigint .
-
Do not assume view returns are always strings – types vary (number, bigint, string, boolean, array).
getBalance (APT)
const balance = await aptos.getBalance({
accountAddress: account.accountAddress
});
// balance is bigint in octas (1 APT = 100_000_000 octas)
const apt = balance / 100_000_000n;
const remainder = balance % 100_000_000n;
console.log(${apt}.${remainder.toString().padStart(8, "0")} APT);
getAccountInfo
const accountInfo = await aptos.getAccountInfo({ accountAddress: "0x1" }); // accountInfo: { sequence_number, authentication_key, ... }
view() – Move view functions
// No type arguments
const result = await aptos.view({
payload: {
function: ${MODULE_ADDRESS}::counter::get_count,
functionArguments: [accountAddress]
}
});
const count = Number(result[0]);
// With type arguments (e.g. coin type) const balanceResult = await aptos.view({ payload: { function: "0x1::coin::balance", typeArguments: ["0x1::aptos_coin::AptosCoin"], functionArguments: [accountAddress] } }); const coinBalance = BigInt(balanceResult[0] as string);
// Multiple return values
// Move: public fun get_listing(addr): (address, u64, bool)
const [seller, price, isActive] = await aptos.view({
payload: {
function: ${MODULE_ADDRESS}::marketplace::get_listing,
functionArguments: [listingAddress]
}
});
const listing = {
seller: seller as string,
price: BigInt(price as string),
isActive: isActive as boolean
};
getAccountResources
const resources = await aptos.getAccountResources({
accountAddress: account.accountAddress
});
// resources: Array<MoveResource>
const counterResource = resources.find((r) => r.type === ${MODULE_ADDRESS}::counter::Counter);
getAccountResource (single type)
const resource = await aptos.getAccountResource({
accountAddress: account.accountAddress,
resourceType: ${MODULE_ADDRESS}::counter::Counter
});
// resource.data has the struct fields
const value = (resource?.data as { value: number })?.value;
getAccountModules
const modules = await aptos.getAccountModules({ accountAddress: modulePublisherAddress }); // modules: MoveModuleBytecode[] (ABI, bytecode)
getModule (single module by name)
const module = await aptos.getModule({ accountAddress: modulePublisherAddress, moduleName: "counter" });
Pagination (resources / modules)
Use cursor-based options when available:
const { resources, cursor } = await aptos.getAccountResourcesPage({ accountAddress: account.accountAddress, options: { limit: 10, cursor: nextCursor } });
Type handling for view results
Move return type TypeScript Example
u8..u64 number or bigint Number(result[0]) or BigInt(result[0])
u128, u256 bigint BigInt(result[0] as string)
address string result[0] as string
bool boolean result[0] as boolean
vector array result[0] as T[]
Common mistakes
Mistake Correct approach
Using getAccountCoinAmount Use aptos.getBalance({ accountAddress })
Using number for u128 Use BigInt(result[0] as string)
Forgetting typeArguments for generic view Add typeArguments: [coinType] when Move function is generic
References
-
SDK: src/internal/view.ts , src/api/account.ts , balance/getBalance in internal
-
Pattern: TYPESCRIPT_SDK.md
-
Related: ts-sdk-client, ts-sdk-types, use-ts-sdk