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)

typescript

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

typescript

const accountInfo = await aptos.getAccountInfo({
  accountAddress: "0x1"
});
// accountInfo: { sequence_number, authentication_key, ... }

view() – Move view functions

typescript

// 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

typescript

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)

typescript

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

typescript

const modules = await aptos.getAccountModules({
  accountAddress: modulePublisherAddress
});
// modules: MoveModuleBytecode[] (ABI, bytecode)

getModule (single module by name)

typescript

const module = await aptos.getModule({
  accountAddress: modulePublisherAddress,
  moduleName: "counter"
});

Pagination (resources / modules)

Use cursor-based options when available:

typescript

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<T>	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

ts-sdk-view-and-query

NPX Install

SKILL.md Content

TypeScript SDK: View and Query

Purpose

ALWAYS

NEVER

getBalance (APT)

getAccountInfo

view() – Move view functions

getAccountResources

getAccountResource (single type)

getAccountModules

getModule (single module by name)

Pagination (resources / modules)

Type handling for view results

Common mistakes

References