Tables — Move REST API on Movement

Overview

Move tables are on-chain key-value stores used extensively by DeFi protocols, NFT collections, token registries, and governance systems on Movement. Unlike Move resources (which are stored at a specific account address), table items are stored under opaque handles and accessed by key. This endpoint lets you look up individual table items by providing the table handle, key type, value type, and key value.

Tables are the backbone of many Move data structures. Token balances in CoinStore, NFT ownership records, DEX liquidity positions, and staking delegations are all stored in tables.

Endpoint

POST /v1/tables/{table_handle}/item

Base URL: https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1

Code Examples

Look Up a Table Item

# Look up a string-to-string table item
curl -s -X POST "https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1/tables/0xTABLE_HANDLE/item" \
  -H "Content-Type: application/json" \
  -d '{
    "key_type": "0x1::string::String",
    "value_type": "0x1::string::String",
    "key": "my_key"
  }'

Look Up Token Balance from a Table

Finding Table Handles from Resources

Checking if a Key Exists

Common Use Cases

Token Registry Lookups

Many token registries and metadata stores use tables. Look up token metadata (name, symbol, decimals, icon URL) by token address. This is common for wallet applications and DEX aggregators.

NFT Ownership and Metadata

NFT collections use tables to map token IDs to owner addresses and metadata. Query individual token ownership, collection statistics, and property maps through table lookups.

Protocol Configuration

DeFi protocols store configuration parameters (fee tiers, interest rates, oracle addresses) in tables. Query these to display current protocol parameters or validate settings before submitting transactions.

Staking and Delegation Records

Staking protocols track delegations, rewards, and validator information in tables. Look up a user's staking position by their address, or query validator performance data.

Movement-Specific Notes

• Table handles are opaque hex strings assigned when a table is created on-chain. They are not human-readable and cannot be derived -- you must discover them from the account resources that contain the table.
• Keys and values are BCS-encoded internally, but the REST API handles serialization and deserialization. You provide JSON-encoded values and receive JSON-encoded responses.
• There is no endpoint to enumerate all keys in a table. To iterate over table contents, you need an indexer or to use event logs that track insertions.
• Table lookups are constant-time operations (O(1)) on-chain, making them efficient for large data sets.

Related Endpoints

• GET /v1/accounts/{address}/resources -- Find table handles within account resources.
• POST /v1/view -- Call view functions that may internally query tables.
• GET /v1/accounts/{address}/modules -- Inspect module ABIs to understand table key/value types.
• GET /v1/accounts/{address}/events/{creation_number} -- Track table insertions and updates via events.