Skip to main content

KV FastData Examples

Examples​

The shell examples below run against the KV FastData hosts and pass FASTNEAR_API_KEY from your shell as an apiKey query parameter, so set it first. Bearer auth with Authorization: Bearer ${FASTNEAR_API_KEY} is also supported when headers fit your client better.

Check one exact key, then replay its history​

When you already know the contract, predecessor, and exact key, start narrow. latest answers the present-tense question; history shows whether that one row changed over time.

CURRENT_ACCOUNT_ID=social.near
PREDECESSOR_ID=james.near
KEY='graph/follow/sleet.near'

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

LATEST="$(curl -s "https://kv.main.fastnear.com/v0/latest/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY?apiKey=${FASTNEAR_API_KEY:-}")"

echo "$LATEST" | jq '{
  latest: (
    .entries[0]
    | {
        current_account_id,
        predecessor_id,
        block_height,
        key,
        value
      }
  )
}'

curl -s "https://kv.main.fastnear.com/v0/history/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY?apiKey=${FASTNEAR_API_KEY:-}" \
  | jq '{writes: [.entries[] | {block_height, value}]}'

For an exact follow-edge style key like this, latest tells you the current indexed value in one row and history shows whether the edge was written once or toggled over time. Start here when you already know the storage path; widen to predecessor scans only when you need discovery rather than proof.

Inspect one predecessor's indexed writes, then narrow to the key that changed​

all-by-predecessor returns the latest indexed writes one account made across every contract it touched. Lift an interesting key and replay it through history to see how that row changed over time.

PREDECESSOR_ID=jemartel.near

FIRST="$(curl -s "https://kv.main.fastnear.com/v0/all/$PREDECESSOR_ID?apiKey=${FASTNEAR_API_KEY:-}" \
  -H 'content-type: application/json' \
  --data '{"include_metadata":true,"limit":10}')"

echo "$FIRST" | jq '{
  page_token,
  entries: [.entries[] | {current_account_id, predecessor_id, block_height, key, value, tx_hash}]
}'

For jemartel.near, the listing mixes an account_id identity assertion on contextual.near with a run of graph/follow/* additions to the same contract. The tx_hash on each row is the direct handoff into /tx/examples if you want the full transaction story behind any write.

Lift the most recent row and replay it through history:

PREDECESSOR_ID=jemartel.near
FIRST="$(curl -s "https://kv.main.fastnear.com/v0/all/$PREDECESSOR_ID?apiKey=${FASTNEAR_API_KEY:-}" \
  -H 'content-type: application/json' \
  --data '{"include_metadata":true,"limit":10}')"

CURRENT_ACCOUNT_ID="$(echo "$FIRST" | jq -r '.entries[0].current_account_id')"
EXACT_KEY="$(echo "$FIRST" | jq -r '.entries[0].key')"
ENCODED_KEY="$(jq -rn --arg key "$EXACT_KEY" '$key | @uri')"

curl -s "https://kv.main.fastnear.com/v0/history/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY?apiKey=${FASTNEAR_API_KEY:-}" \
  | jq '{entries: [.entries[] | {block_height, value}]}'

For the account_id row, history returns a single write at block 185965311 with value "jemartel.near:mainnet" — the identity assertion stands, stable since that block. KV preserves every write equally: a quiet key shows one row, a busy key shows many — same shape, no summarization.

Common mistakes​

  • Starting with broad account or predecessor scans when an exact key is already known.
  • Using KV FastData when the user really wants balances or holdings.
  • Confusing indexed history with exact current chain state.
  • Reusing pagination tokens or changing filters mid-scan.