Return an entry from a map
Query contract map data using the Stacks API map_entry endpoint
import { Cl, cvToHex } from "@stacks/transactions";// Query a map entry from a contractconst contractAddress = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM";const contractName = "my-contract";const mapName = "user-balances";// Create the map key (e.g., a principal)const mapKey = Cl.standardPrincipal("ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5");const response = await fetch(`https://api.hiro.so/v2/map_entry/${contractAddress}/${contractName}/${mapName}`,{method: "POST",headers: {"Content-Type": "application/json",},body: JSON.stringify(cvToHex(mapKey)),});const result = await response.json();const data = result.data ? Cl.deserialize(result.data) : null;console.log("Map value:", data);
Use cases
- Reading user balances from token contracts
- Checking NFT ownership records
- Retrieving configuration values from contracts
- Monitoring contract state without transactions
Key concepts
The map_entry API:
- POST request: Send the serialized map key
- Hex encoding: Keys must be hex-encoded Clarity values
- Response format: Returns hex-encoded Clarity value or null