tables_item

Overview

Read a single value from a Move state table by its key. Tables in Aptos are key-value stores used by smart contracts to store mappings, balances, configurations, and other structured data. This endpoint provides direct access to individual table entries without fetching the entire resource that contains the table.

Endpoint

POST /v1/tables/{table_handle}/item

Code Examples

Tip: The handle 0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca references the on-chain coin conversion map. The key shown here is the BCS-encoded metadata address for Aptos Coin, and the returned u128 value is the circulating supply in octas.

Discovering Table Handles

Table handles are not easily discoverable -- they are stored as fields within resources. Here is the typical discovery workflow:

Query the resource containing the table:

Bash

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

Find the table field in the response. Table fields have a handle property:

JSON

{
  "type": "0x1::coin::CoinInfo<0x1::aptos_coin::AptosCoin>",
  "data": {
    "supply": {
      "vec": [{
        "aggregator": {
          "vec": [{
            "handle": "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca",
            "key": "0x619dc29a..."
          }]
        }
      }]
    }
  }
}

Use the handle to query individual table items.

Use Cases

Token Supply Tracking: Query coin supply tables to retrieve current circulation, maximum supply, and minting statistics for any fungible asset.
Configuration Lookups: Access protocol configuration tables for fee parameters, interest rates, oracle addresses, and governance settings.
Mapping Queries: Retrieve values from key-value mappings stored in Move tables -- user balances, token ownership records, or application-specific data.
State Verification: Verify specific state values in smart contracts by directly querying table items rather than fetching and parsing entire resources.
Indexer Alternatives: For simple key-value lookups, table queries can be more efficient than setting up a GraphQL indexer or processing full resource data.
Analytics and Dashboards: Build analytics dashboards by querying statistical tables maintained by on-chain protocols.

Best Practices

Type Accuracy: Ensure key_type and value_type exactly match the table's Move type definitions. Even minor differences (such as u64 vs u128) cause deserialization errors.

Key Encoding: Keys must be properly formatted for their type. For addresses, use the full 0x-prefixed hex string. For struct keys, provide a JSON object matching the struct's field layout.

Handle Discovery: Table handles are opaque addresses that change when the table is recreated. Always discover handles dynamically from the containing resource rather than hardcoding them.

404 Handling: A 404 can mean either the table does not exist or the key does not exist in the table. Check the specific error code (table_not_found vs table_item_not_found) to distinguish these cases.

Ledger Version: Use the optional ledger_version query parameter to query tables at historical points in time. This enables time-series analysis, state reconstruction, and consistent cross-table reads.

Caching: Table values can change with every transaction that modifies them. Cache based on your knowledge of how frequently the specific key is updated -- protocol parameters change rarely, while user balances change with every transfer.

Performance Considerations

Table item queries use indexed Merkle tree lookups, typically completing in 50-150ms. Performance depends on key complexity and value size. Simple numeric keys and values are fastest.

Tables are implemented using a Jellyfish Merkle tree structure, providing O(log n) lookup time. Even tables with millions of entries respond quickly due to the logarithmic access pattern.

For bulk queries across many keys in the same table, making concurrent requests is more efficient than sequential queries. However, if you need many entries from the same table, consider whether fetching the entire resource and parsing client-side might be more efficient.

/v1/tables/{table_handle}/raw_item - Read raw BCS-encoded table values
/v1/accounts/{address}/resource/{type} - Fetch the resource containing the table handle
/v1/accounts/{address}/resources - List all resources to discover table handles
/v1/view - Alternative for computed lookups that access tables internally

On this page