ts-sdk-view-and-query

Name: ts-sdk-view-and-query
Author: aptos-labs

19stars8forks

How to install ts-sdk-view-and-query?

aptos-labs/aptos-agent-skills/ts-sdk-view-and-query

$npx -y skills add aptos-labs/aptos-agent-skills --skill ts-sdk-view-and-query

Installs into the current project.

Summary

How to read on-chain data in @aptos-labs/ts-sdk: view(), getBalance(), getAccountInfo(), getAccountResources(), getAccountModules(), getResource(). Triggers on: 'aptos.view', 'getBalance', 'getAccountInfo', 'getAccountResources', 'SDK query', 'view function TypeScript'.

Files · 1

View on GitHub

SKILL.md

1	# TypeScript SDK: View and Query
2
3	## Purpose
4
5	Guide read-only access to chain data in `@aptos-labs/ts-sdk`: view functions, balance, account info, resources, and
6	modules.
7
8	## ALWAYS
9
10	1. Use `aptos.getBalance({ accountAddress })` for APT balance – not deprecated `getAccountCoinAmount` /
11	`getAccountAPTAmount`.
12	2. Use `aptos.view()` for Move view functions – pass `function`, `functionArguments`, and optional `typeArguments`.
13	3. Use `bigint` for u128/u256 view return values – cast `result[0]` to `BigInt(...)` when the Move function returns
14	u128/u256.
15	4. Pass address as string or AccountAddress – SDK accepts `AccountAddressInput` (string or `AccountAddress`).
16
17	## NEVER
18
19	1. Do not use deprecated `getAccountCoinAmount` or `getAccountAPTAmount` – use `getBalance()`.
20	2. Do not use `number` for u128/u256 – precision loss; use `bigint`.
21	3. Do not assume view returns are always strings – types vary (number, bigint, string, boolean, array).
22
23	---
24
25	## getBalance (APT)
26
27	```typescript
28	const balance = await aptos.getBalance({
29	accountAddress: account.accountAddress
30	});
31	// balance is bigint in octas (1 APT = 100_000_000 octas)
32	const apt = balance / 100_000_000n;
33	const remainder = balance % 100_000_000n;
34	console.log(`${apt}.${remainder.toString().padStart(8, "0")} APT`);
35	```
36
37	---
38
39	## getAccountInfo
40
41	```typescript
42	const accountInfo = await aptos.getAccountInfo({
43	accountAddress: "0x1"
44	});
45	// accountInfo: { sequence_number, authentication_key, ... }
46	```
47
48	---
49
50	## view() – Move view functions
51
52	```typescript
53	// No type arguments
54	const result = await aptos.view({
55	payload: {
56	function: `${MODULE_ADDRESS}::counter::get_count`,
57	functionArguments: [accountAddress]
58	}
59	});
60	const count = Number(result[0]);
61
62	// With type arguments (e.g. coin type)
63	const balanceResult = await aptos.view({
64	payload: {
65	function: "0x1::coin::balance",
66	typeArguments: ["0x1::aptos_coin::AptosCoin"],
67	functionArguments: [accountAddress]
68	}
69	});
70	const coinBalance = BigInt(balanceResult[0] as string);
71
72	// Multiple return values
73	// Move: public fun get_listing(addr): (address, u64, bool)
74	const [seller, price, isActive] = await aptos.view({
75	payload: {
76	function: `${MODULE_ADDRESS}::marketplace::get_listing`,
77	functionArguments: [listingAddress]
78	}
79	});
80	const listing = {
81	seller: seller as string,
82	price: BigInt(price as string),
83	isActive: isActive as boolean
84	};
85	```
86
87	---
88
89	## getAccountResources
90
91	```typescript
92	const resources = await aptos.getAccountResources({
93	accountAddress: account.accountAddress
94	});
95	// resources: Array<MoveResource>
96	const counterResource = resources.find((r) => r.type === `${MODULE_ADDRESS}::counter::Counter`);
97	```
98
99	---
100
101	## getAccountResource (single type)
102
103	```typescript
104	const resource = await aptos.getAccountResource({
105	accountAddress: account.accountAddress,
106	resourceType: `${MODULE_ADDRESS}::counter::Counter`
107	});
108	// resource.data has the struct fields
109	const value = (resource?.data as { value: number })?.value;
110	```
111
112	---
113
114	## getAccountModules
115
116	```typescript
117	const modules = await aptos.getAccountModules({
118	accountAddress: modulePublisherAddress
119	});
120	// modules: MoveModuleBytecode[] (ABI, bytecode)
121	```
122
123	---
124
125	## getModule (single module by name)
126
127	```typescript
128	const module = await aptos.getModule({
129	accountAddress: modulePublisherAddress,
130	moduleName: "counter"
131	});
132	```
133
134	---
135
136	## Pagination (resources / modules)
137
138	Use cursor-based options when available:
139
140	```typescript
141	const { resources, cursor } = await aptos.getAccountResourcesPage({
142	accountAddress: account.accountAddress,
143	options: { limit: 10, cursor: nextCursor }
144	});
145	```
146
147	---
148
149	## Type handling for view results
150
151	\| Move return type \| TypeScript \| Example \|
152	\| ---------------- \| ---------------- \| ------------------------------------------ \|
153	\| u8..u64 \| number or bigint \| `Number(result[0])` or `BigInt(result[0])` \|
154	\| u128, u256 \| bigint \| `BigInt(result[0] as string)` \|
155	\| address \| string \| `result[0] as string` \|
156	\| bool \| boolean \| `result[0] as boolean` \|
157	\| vector<T> \| array \| `result[0] as T[]` \|
158
159	---
160
161	## Common mistakes
162
163	\| Mistake \| Correct approach \|
164	\| ----------------------------------------- \| --------------------------------------------------

People who liked this also viewed

6 picks

Type

ts-sdk-view-and-query

19stars8forks

View on GitHub

How to install ts-sdk-view-and-query?

aptos-labs/aptos-agent-skills/ts-sdk-view-and-query

$npx -y skills add aptos-labs/aptos-agent-skills --skill ts-sdk-view-and-query

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# TypeScript SDK: View and Query
2
3	## Purpose
4
5	Guide read-only access to chain data in `@aptos-labs/ts-sdk`: view functions, balance, account info, resources, and
6	modules.
7
8	## ALWAYS
9
10	1. Use `aptos.getBalance({ accountAddress })` for APT balance – not deprecated `getAccountCoinAmount` /
11	`getAccountAPTAmount`.
12	2. Use `aptos.view()` for Move view functions – pass `function`, `functionArguments`, and optional `typeArguments`.
13	3. Use `bigint` for u128/u256 view return values – cast `result[0]` to `BigInt(...)` when the Move function returns
14	u128/u256.
15	4. Pass address as string or AccountAddress – SDK accepts `AccountAddressInput` (string or `AccountAddress`).
16
17	## NEVER
18
19	1. Do not use deprecated `getAccountCoinAmount` or `getAccountAPTAmount` – use `getBalance()`.
20	2. Do not use `number` for u128/u256 – precision loss; use `bigint`.
21	3. Do not assume view returns are always strings – types vary (number, bigint, string, boolean, array).
22
23	---
24
25	## getBalance (APT)
26
27	```typescript
28	const balance = await aptos.getBalance({
29	accountAddress: account.accountAddress
30	});
31	// balance is bigint in octas (1 APT = 100_000_000 octas)
32	const apt = balance / 100_000_000n;
33	const remainder = balance % 100_000_000n;
34	console.log(`${apt}.${remainder.toString().padStart(8, "0")} APT`);
35	```
36
37	---
38
39	## getAccountInfo
40
41	```typescript
42	const accountInfo = await aptos.getAccountInfo({
43	accountAddress: "0x1"
44	});
45	// accountInfo: { sequence_number, authentication_key, ... }
46	```
47
48	---
49
50	## view() – Move view functions
51
52	```typescript
53	// No type arguments
54	const result = await aptos.view({
55	payload: {
56	function: `${MODULE_ADDRESS}::counter::get_count`,
57	functionArguments: [accountAddress]
58	}
59	});
60	const count = Number(result[0]);
61
62	// With type arguments (e.g. coin type)
63	const balanceResult = await aptos.view({
64	payload: {
65	function: "0x1::coin::balance",
66	typeArguments: ["0x1::aptos_coin::AptosCoin"],
67	functionArguments: [accountAddress]
68	}
69	});
70	const coinBalance = BigInt(balanceResult[0] as string);
71
72	// Multiple return values
73	// Move: public fun get_listing(addr): (address, u64, bool)
74	const [seller, price, isActive] = await aptos.view({
75	payload: {
76	function: `${MODULE_ADDRESS}::marketplace::get_listing`,
77	functionArguments: [listingAddress]
78	}
79	});
80	const listing = {
81	seller: seller as string,
82	price: BigInt(price as string),
83	isActive: isActive as boolean
84	};
85	```
86
87	---
88
89	## getAccountResources
90
91	```typescript
92	const resources = await aptos.getAccountResources({
93	accountAddress: account.accountAddress
94	});
95	// resources: Array<MoveResource>
96	const counterResource = resources.find((r) => r.type === `${MODULE_ADDRESS}::counter::Counter`);
97	```
98
99	---
100
101	## getAccountResource (single type)
102
103	```typescript
104	const resource = await aptos.getAccountResource({
105	accountAddress: account.accountAddress,
106	resourceType: `${MODULE_ADDRESS}::counter::Counter`
107	});
108	// resource.data has the struct fields
109	const value = (resource?.data as { value: number })?.value;
110	```
111
112	---
113
114	## getAccountModules
115
116	```typescript
117	const modules = await aptos.getAccountModules({
118	accountAddress: modulePublisherAddress
119	});
120	// modules: MoveModuleBytecode[] (ABI, bytecode)
121	```
122
123	---
124
125	## getModule (single module by name)
126
127	```typescript
128	const module = await aptos.getModule({
129	accountAddress: modulePublisherAddress,
130	moduleName: "counter"
131	});
132	```
133
134	---
135
136	## Pagination (resources / modules)
137
138	Use cursor-based options when available:
139
140	```typescript
141	const { resources, cursor } = await aptos.getAccountResourcesPage({
142	accountAddress: account.accountAddress,
143	options: { limit: 10, cursor: nextCursor }
144	});
145	```
146
147	---
148
149	## Type handling for view results
150
151	\| Move return type \| TypeScript \| Example \|
152	\| ---------------- \| ---------------- \| ------------------------------------------ \|
153	\| u8..u64 \| number or bigint \| `Number(result[0])` or `BigInt(result[0])` \|
154	\| u128, u256 \| bigint \| `BigInt(result[0] as string)` \|
155	\| address \| string \| `result[0] as string` \|
156	\| bool \| boolean \| `result[0] as boolean` \|
157	\| vector<T> \| array \| `result[0] as T[]` \|
158
159	---
160
161	## Common mistakes
162
163	\| Mistake \| Correct approach \|
164	\| ----------------------------------------- \| --------------------------------------------------

People who liked this also viewed

6 picks

Type