Skip to main content

KV FastData API

KV FastData API is the indexed key-value family. Use it when you already know the contract, account, predecessor, or key scope you want to inspect and you want indexed rows without building your own storage indexing layer.

Base URLs​

KV FastData API Mainnet
https://kv.main.fastnear.com
KV FastData API Testnet
https://kv.test.fastnear.com

Quick start​

If you already know one exact key, start with the latest indexed row and stop as soon as it answers the question.

CURRENT_ACCOUNT_ID=social.near
PREDECESSOR_ID=james.near
KEY='graph/follow/sleet.near'
AUTH_HEADER=()
if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi

ENCODED_KEY="$(jq -rn --arg key "$KEY" '$key | @uri')"

curl -s "https://kv.main.fastnear.com/v0/latest/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY" \
  "${AUTH_HEADER[@]}" \
  | jq '{
      latest: (
        .entries[0]
        | {
            current_account_id,
            predecessor_id,
            block_height,
            key,
            value
          }
      )
    }'

This is the narrowest useful KV read: one exact key, one latest indexed row. If the next question becomes “how did this key change over time?”, move to GET History by Exact Key or the fuller KV FastData Examples.

Use this API when​

  • you want latest indexed state for one key or a known key family
  • you want historical key changes by account, key, or predecessor
  • you want batch lookups for known exact keys
  • you are debugging contract storage in indexed form

Do not start here when​

  • you need balances, token holdings, NFTs, or account summaries
  • you need recent block-family data
  • you need exact current on-chain state with canonical RPC semantics

Use FastNear API for higher-level account views, NEAR Data API for block-family reads, and RPC Reference for canonical contract-state inspection.

Minimum useful inputs​

  • network
  • contract ID or another precise scope such as account, predecessor, or exact key
  • whether the user needs the latest indexed value or historical changes

Choose a query shape​

Need a workflow?​

Use KV FastData Examples for worked examples like exact-key lookups, key-history investigation, predecessor-scoped inspection, and canonical RPC follow-up.

Default workflow​

  1. Pick the narrowest scope that matches the user's question.
  2. Stay within KV FastData first when the question is still about indexed key-value data.
  3. Use the latest endpoints for current indexed views and the history endpoints only when the user needs change-over-time answers.
  4. Stop once the indexed rows already answer the storage question.

Auth and availability​

  • Public indexed storage reads often work without a key.
  • If you standardize on one FastNear API key across FastNear surfaces, reuse the same header or query-param shape here too.
  • Add ?network=testnet to switch the page to the testnet backend where supported.
  • List responses omit page_token when there are no more results.

Widen only if​

  • the user needs exact current on-chain state rather than indexed storage data
  • the user needs canonical contract-state semantics
  • the indexed storage view is the wrong abstraction for the question

When that happens, widen to View State in RPC Reference.

Troubleshooting​

My pagination token stopped working​

Treat page_token values as opaque and reuse them only with the same endpoint and filters.

I need product-facing account balances instead of raw key-value rows​

Move up to FastNear API.