accounts_resource

Overview

Fetch a specific resource stored under an account by its full Move type string. Resources are the primary state-storage mechanism in Move -- every token balance, NFT collection, staking position, and application-specific datum is stored as a typed resource under an account address. This endpoint provides direct, type-safe access to individual resources.

Endpoint

GET /v1/accounts/{address}/resource/{resource_type}

Aptos-Specific Notes

Resource types follow the format address::module::StructName<TypeArgs>.
Generic types must include full type parameters, such as 0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>.
The resource type string must be URL-encoded when it contains special characters like <, >, or ::.

Common Resource Types

Resource Type	Description
`0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>`	APT token balance
`0x1::account::Account`	Account metadata (sequence number, authentication key)
`0x1::staking_contract::StakingGroupContainer`	Staking positions
`0x1::token::TokenStore`	Legacy token (NFT) storage
`0x4::collection::Collection`	Digital Asset (NFT) collection
`0x1::coin::CoinInfo<0x1::aptos_coin::AptosCoin>`	APT coin metadata (decimals, name, symbol)
`0x1::stake::StakePool`	Validator stake pool info
`0x1::dkg::DKGState`	Distributed key generation state

Code Examples

Use Cases

Balance Checking: Read CoinStore resources to check token balances for any fungible asset (APT, USDC, custom tokens) before initiating transfers or swaps.
State Inspection: Read application-specific resources to check contract state without executing transactions -- useful for displaying DeFi positions, staking info, or governance data in UIs.
Historical State Queries: Use the ledger_version parameter to read resource state at any historical point, enabling time-series analysis and state reconstruction.
Event Handle Discovery: Extract event handle creation numbers from resource fields to set up event monitoring via the events endpoints.
Pre-Transaction Validation: Check resource existence and values before building transactions. For example, verify a CoinStore exists before attempting a transfer to avoid unnecessary gas costs.
Protocol Monitoring: Monitor key protocol resources (treasury balances, governance parameters, oracle prices) for dashboards and alerting systems.

Best Practices

URL Encoding: Resource types containing < and > (generics) must be URL-encoded. Use %3C for < and %3E for >. Most HTTP libraries handle this automatically.

Type Precision: The resource type must match exactly as stored on-chain, including the full address prefix. coin::CoinStore will not work; use 0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>.

Version Pinning: When reading multiple related resources that must be consistent (such as balance and allowance), pass the same ledger_version to all requests to get an atomic snapshot.

404 Handling: A 404 for a CoinStore means the account has never held that token (the store has not been created), not that the balance is zero. Distinguish between "not registered" and "zero balance" in your application logic.

Large Resources: Some resources (like tables or large vectors) can be very large. If you only need a specific field, consider using the view endpoint to call a view function that returns just the data you need.

Numeric Values: All large numbers (balances, timestamps, IDs) are returned as strings to avoid JavaScript precision loss. Parse with BigInt or appropriate large-number libraries.

Performance Considerations

Single resource lookups are highly optimized, completing in 30-80ms. The response size depends on the resource structure: simple resources like Account return under 1KB, while complex resources with large vectors or nested structs can be 10-100KB.

For applications that need multiple resources from the same account, it may be more efficient to use GET /v1/accounts/{address}/resources to fetch all resources in a single request, then filter client-side. However, for accounts with many resources (like 0x1), targeted single-resource queries are faster.

Historical queries (with ledger_version) may be slightly slower than current-state queries if the node needs to read from archived storage.

/v1/accounts/{address}/resources - Get all resources under an account
/v1/accounts/{address}/module/{module_name} - Get module ABI to discover resource types
/v1/view - Call view functions for computed resource data
/v1/tables/{handle}/item - Read individual table entries within resources

On this page