tables_item

Endpoint

POST /v1/tables/{table_handle}/item

Request

Path Parameters

Name	Type	Required	Description
table_handle	string	Yes	Table handle address

Request Body

{
  "key_type": "address",
  "value_type": "u128",
  "key": "0x619dc29a0aac8fa146714058e8dd6d2d0f3bdf5f6331907bf91f3acd81e6935"
}

Response

Success Response (200)

Returns the value from the table, decoded according to the specified value_type:

"1234567890"

For simple types like u128, the response is a string-encoded number. For struct types, the response is a JSON object with the struct's fields.

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid table handle, key type, value type, or key format
404	table_item_not_found	Key doesn't exist in table
404	table_not_found	Table handle doesn't exist

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.

curl -s -X POST "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/tables/0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca/item" \
  -H "Content-Type: application/json" \
  -d '{"key_type":"address","value_type":"u128","key":"0x619dc29a0aac8fa146714058e8dd6d2d0f3bdf5f6331907bf91f3acd81e6935"}'

Python example:

import requests

response = requests.post(
    "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/tables/{handle}/item",
    json={
        "key_type": "address",
        "value_type": "u128",
        "key": "0x1"
    }
)
value = response.json()

TypeScript example:

const response = await aptos.getTableItem<number>({
  handle: "0x1b854...",
  data: {
    key_type: "address",
    value_type: "u128",
    key: "0x1"
  }
});

Use Cases

Table queries are essential for accessing Aptos's on-chain data structures:

1. Supply Tracking: Query coin supply tables to retrieve current circulation, maximum supply, and minting statistics for fungible assets and coins.

2. Configuration Lookups: Access on-chain configuration tables for protocol parameters, fee structures, and governance settings without parsing raw resources.

3. Mapping Queries: Retrieve values from key-value mappings stored in Move tables, such as user balances, token ownership, or application-specific data.

4. State Verification: Verify specific state values in smart contracts by directly querying table items rather than fetching and parsing entire resources.

5. Indexer Alternatives: For simple lookups, table queries can be more efficient than setting up GraphQL indexers or processing full resource data.

6. Analytics Queries: 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. Type mismatches cause deserialization errors.

Key Encoding: Keys must be properly BCS-encoded. For addresses, use the full 0x-prefixed 64-character hex string. For complex types, use BCS serialization libraries.

Handle Discovery: Table handles are not easily discoverable. They're typically stored in resource fields of type Table<K, V>. Query the resource first to extract the handle.

404 Handling: A 404 can mean either the table doesn't exist or the key doesn't exist in the table. Check the error message to distinguish these cases.

Ledger Version: Use the optional ledger_version query parameter to query tables at historical points in time for time-series analysis or state reconstruction.

Performance Considerations

Table item queries are optimized with indexed 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 Merkle tree structure, providing O(log n) lookup time. However, the constant factors are low enough that even tables with millions of entries respond quickly.

For bulk queries across many keys, consider whether querying the entire resource and parsing it client-side might be more efficient than multiple table queries.