view

Overview

Execute a Move view function without submitting a transaction, consuming gas, or requiring a signature. View functions are read-only operations that run in the Move VM and return computed results. They are the most efficient way to query on-chain state that requires computation, such as calculated balances, prices, permissions, or derived values.

Only functions explicitly marked view can be called through this endpoint. The target function must actually be marked as view. A regular public function is not enough on its own.

Endpoint

POST /v1/view

Code Examples

Common View Function Patterns

Balance and Token Queries

JSON

// Check coin balance
{ "function": "0x1::coin::balance", "type_arguments": ["0x1::aptos_coin::AptosCoin"], "arguments": ["0x1"] }

// Check if registered for a coin
{ "function": "0x1::coin::is_account_registered", "type_arguments": ["0x1::aptos_coin::AptosCoin"], "arguments": ["0x1"] }

// Get coin decimals
{ "function": "0x1::coin::decimals", "type_arguments": ["0x1::aptos_coin::AptosCoin"], "arguments": [] }

// Get coin name
{ "function": "0x1::coin::name", "type_arguments": ["0x1::aptos_coin::AptosCoin"], "arguments": [] }

// Get coin supply
{ "function": "0x1::coin::supply", "type_arguments": ["0x1::aptos_coin::AptosCoin"], "arguments": [] }

Account and System Queries

JSON

// Check if account exists
{ "function": "0x1::account::exists_at", "type_arguments": [], "arguments": ["0x1"] }

// Read a view that is explicitly marked `view`
{ "function": "0x1::account::exists_at", "type_arguments": [], "arguments": ["0x1"] }

Use Cases

Balance Queries: Check account balances for any fungible token without transaction overhead or gas costs. Ideal for wallet UIs, portfolio trackers, and balance verification.
State Inspection: Read computed contract state like pool prices, lending rates, or staking rewards that require on-chain calculation rather than simple resource reads.
Validation Checks: Verify conditions before transaction submission (sufficient balance, correct permissions, valid parameters) to prevent failed transactions and wasted gas.
UI Data Fetching: Power application UIs with real-time blockchain data. View functions are fast enough for user-facing queries without needing a dedicated indexer.
Price Feeds: Query DEX pool prices, oracle data, or computed exchange rates for display, trading logic, or arbitrage detection.
Permission Checks: Verify user roles, capabilities, or access control before allowing operations in your application.

Best Practices

Function Visibility: Only functions explicitly marked with the #[view] attribute can be called via this endpoint. Entry functions and ordinary public fun functions that are not declared as view functions cannot be used here, even if they only read state.

Gas-Free Execution: View functions do not consume gas or require signatures, making them ideal for frequent, high-volume queries from frontends and monitoring systems.

Type Arguments: Provide full type paths including generics. For example, use 0x1::aptos_coin::AptosCoin rather than just AptosCoin. Type arguments correspond to the generic parameters in the function signature.

Argument Encoding: Arguments are passed as JSON values and automatically BCS-encoded by the API. Large integers (u64 and above) must be passed as strings to avoid JSON precision loss.

Caching: View function results reflect the state at the current (or specified) ledger version. Cache based on how frequently the underlying state changes -- token balances change with every transfer, while protocol parameters may change infrequently.

Ledger Version: Use the ledger_version query parameter to query historical state. This enables time-travel queries and consistent multi-call snapshots when all calls use the same version.

Error Handling: View functions that call abort in the Move VM return a 500 error. Check for this when querying functions that have assertion checks (such as querying a balance for a non-existent coin store).

Performance Considerations

View functions execute directly in the Move VM without consensus or state commitment overhead. Response times are typically 20-100ms depending on function complexity.

Simple reads (balance, existence check): 20-50ms
Moderate computation (price calculation, aggregate queries): 50-100ms
Complex computations (multi-step simulations): 100-200ms

View functions are significantly faster than full transaction simulation for read operations. For frequently accessed data, implement client-side caching with TTLs based on block time (approximately 4 seconds on mainnet).

For batch queries, make concurrent requests rather than sequential calls. View functions are stateless and can safely run in parallel without ordering concerns.

/v1/accounts/{address}/resource/{resource_type} - Direct resource read (no computation)
/v1/accounts/{address}/resources - List all resources under an account
/v1/accounts/{address}/modules - Discover available view functions via ABI
/v1/transactions/simulate - Simulate a full transaction with state changes

On this page