default to url param ?apiKey for examples, mentioning auth Bearer tok…

docs/api/examples.md

@@ -10,19 +10,16 @@ page_actions:
 
 ## Examples
 
-All shell examples below work on the public FastNear API hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they add it as a bearer header automatically; if it is unset, they fall back to the public unauthenticated path.
+All shell examples below work on the public FastNear API hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they pass it as an `apiKey` query parameter automatically; if it is unset, they fall back to the public unauthenticated path. Bearer auth with `Authorization: Bearer ${FASTNEAR_API_KEY}` is also supported when headers fit your client better.
 
 ### Summarize one account in one call
 
 `/v1/account/{id}/full` is the FastNear API's account aggregator — one call bundles the account's NEAR state, every FT contract it's touched, every NFT collection it's received, and every validator pool it's delegated to. When you already have the `account_id`, this is the fastest "what does this account look like?" read.
 
 ```bash
 ACCOUNT_ID=root.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
-  "${AUTH_HEADER[@]}" \
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq '{
       account_id,
       near_balance_yocto: .state.balance,
@@ -40,18 +37,14 @@ Look up which account a key belongs to, then read that account's holdings in one
 
 ```bash
 PUBLIC_KEY='ed25519:CCaThr3uokqnUs6Z5vVnaDcJdrfuTpYJHJWcAGubDjT'
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-LOOKUP="$(curl -s "https://api.fastnear.com/v1/public_key/$(jq -rn --arg k "$PUBLIC_KEY" '$k | @uri')" \
-  "${AUTH_HEADER[@]}")"
+LOOKUP="$(curl -s "https://api.fastnear.com/v1/public_key/$(jq -rn --arg k "$PUBLIC_KEY" '$k | @uri')?apiKey=${FASTNEAR_API_KEY:-}")"
 
 echo "$LOOKUP" | jq '{matched: (.account_ids | length), account_ids}'
 
 ACCOUNT_ID="$(echo "$LOOKUP" | jq -r '.account_ids[0]')"
 
-curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
-  "${AUTH_HEADER[@]}" \
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq '{account_id, state, tokens: (.tokens|length), nfts: (.nfts|length), pools: (.pools|length)}'
 ```
 
@@ -63,11 +56,8 @@ NEAR account state has three buckets that wallet UIs tend to conflate: `balance`
 
 ```bash
 ACCOUNT_ID=root.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
-  "${AUTH_HEADER[@]}" \
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq '
       (.state.balance | tonumber) as $amount
       | (.state.locked  | tonumber) as $locked
@@ -97,11 +87,8 @@ Every entry under `/full`'s `tokens`, `nfts`, and `pools` arrays carries its own
 
 ```bash
 ACCOUNT_ID=root.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full" \
-  "${AUTH_HEADER[@]}" \
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/full?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq '
       [
         (.tokens // [])[].last_update_block_height,
@@ -129,11 +116,8 @@ NEAR account names encode a hierarchy: `mint.sharddog.near` is a subaccount of `
 ```bash
 ACCOUNT_ID=root.near
 PUBLISHER=sharddog.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/nft" \
-  "${AUTH_HEADER[@]}" \
+curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/nft?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq --arg publisher "$PUBLISHER" '
       ("." + $publisher) as $suffix
       | {
@@ -162,13 +146,9 @@ Direct pool positions live on `/staking`; liquid staking tokens (stNEAR, LiNEAR,
 ```bash
 ACCOUNT_ID=root.near
 LIQUID_PROVIDERS_JSON='["meta-pool.near","lst.rhealab.near","linear-protocol.near"]'
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-STAKING="$(curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/staking" \
-  "${AUTH_HEADER[@]}")"
-FT="$(curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/ft" \
-  "${AUTH_HEADER[@]}")"
+STAKING="$(curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/staking?apiKey=${FASTNEAR_API_KEY:-}")"
+FT="$(curl -s "https://api.fastnear.com/v1/account/$ACCOUNT_ID/ft?apiKey=${FASTNEAR_API_KEY:-}")"
 
 jq -n \
   --argjson staking "$STAKING" \

docs/fastdata/kv/examples.md

@@ -10,7 +10,7 @@ page_actions:
 
 ## Examples
 
-All shell examples below work on the public KV FastData hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they add it as a bearer header automatically; if it is unset, they fall back to the public unauthenticated path.
+All shell examples below work on the public KV FastData hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they pass it as an `apiKey` query parameter automatically; if it is unset, they fall back to the public unauthenticated path. 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
 
@@ -20,13 +20,10 @@ When you already know the contract, predecessor, and exact key, start narrow. `l
 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')"
 
-LATEST="$(curl -s "https://kv.main.fastnear.com/v0/latest/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY" \
-  "${AUTH_HEADER[@]}")"
+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: (
@@ -41,8 +38,7 @@ echo "$LATEST" | jq '{
   )
 }'
 
-curl -s "https://kv.main.fastnear.com/v0/history/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY" \
-  "${AUTH_HEADER[@]}" \
+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}]}'
 ```
 
@@ -54,11 +50,8 @@ For an exact follow-edge style key like this, `latest` tells you the current ind
 
 ```bash
 PREDECESSOR_ID=jemartel.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-FIRST="$(curl -s "https://kv.main.fastnear.com/v0/all/$PREDECESSOR_ID" \
-  "${AUTH_HEADER[@]}" \
+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}')"
 
@@ -74,19 +67,15 @@ Lift the most recent row and replay it through `history`:
 
 ```bash
 PREDECESSOR_ID=jemartel.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
-FIRST="$(curl -s "https://kv.main.fastnear.com/v0/all/$PREDECESSOR_ID" \
-  "${AUTH_HEADER[@]}" \
+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" \
-  "${AUTH_HEADER[@]}" \
+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}]}'
 ```
 

docs/neardata/examples.md

@@ -12,18 +12,15 @@ page_actions:
 
 NEAR Data returns each block fully hydrated as one JSON document — header plus per-shard chunks, receipts, execution outcomes, and state changes — so a single `curl` gives you everything you need to filter for a specific contract without a second call.
 
-All shell examples below work on the public NEAR Data hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they add it as a bearer header automatically; if it is unset, they fall back to the public unauthenticated path.
+All shell examples below work on the public NEAR Data hosts as-is. If `FASTNEAR_API_KEY` is set in your shell, they pass it as an `apiKey` query parameter automatically; if it is unset, they fall back to the public unauthenticated path. Bearer auth with `Authorization: Bearer ${FASTNEAR_API_KEY}` is also supported when headers fit your client better.
 
 ### What block is NEAR on right now?
 
 `/v0/last_block/final` 302-redirects to the current finalized block. Before filtering for a specific contract, it's worth seeing what one block looks like at the protocol level: transactions arrive sharded, so the tx count for a block is a sum across shards — not a single top-level number.
 
 ```bash
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-curl -sL "https://mainnet.neardata.xyz/v0/last_block/final" \
-  "${AUTH_HEADER[@]}" \
+curl -sL "https://mainnet.neardata.xyz/v0/last_block/final?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq '{
       height: .block.header.height,
       timestamp_nanosec: .block.header.timestamp_nanosec,
@@ -40,11 +37,8 @@ A live block shows 9 shards and a handful of transactions scattered across them
 
 ```bash
 TARGET_CONTRACT=intents.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-curl -sL "https://mainnet.neardata.xyz/v0/last_block/final" \
-  "${AUTH_HEADER[@]}" \
+curl -sL "https://mainnet.neardata.xyz/v0/last_block/final?apiKey=${FASTNEAR_API_KEY:-}" \
   | jq --arg contract "$TARGET_CONTRACT" '{
       height: .block.header.height,
       contract: $contract,
@@ -66,8 +60,6 @@ Optimistic blocks ship at `/v0/block_opt/{height}` about a second ahead of `/v0/
 
 ```bash
 TARGET_CONTRACT=intents.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
 count_touches() {
   jq --arg contract "$1" '
@@ -78,15 +70,14 @@ count_touches() {
 }
 
 OPT_LOCATION="$(
-  curl -s -D - -o /dev/null "${AUTH_HEADER[@]}" "https://mainnet.neardata.xyz/v0/last_block/optimistic" \
+  curl -s -D - -o /dev/null "https://mainnet.neardata.xyz/v0/last_block/optimistic?apiKey=${FASTNEAR_API_KEY:-}" \
     | awk 'tolower($1) == "location:" {print $2}' | tr -d '\r'
 )"
-OPT_HEIGHT="${OPT_LOCATION##*/}"
+OPT_PATH="${OPT_LOCATION%%\?*}"
+OPT_HEIGHT="${OPT_PATH##*/}"
 
-echo "optimistic @ $OPT_HEIGHT: $(curl -s "https://mainnet.neardata.xyz$OPT_LOCATION" \
-  "${AUTH_HEADER[@]}" | count_touches "$TARGET_CONTRACT") touches"
-FINAL="$(curl -s "https://mainnet.neardata.xyz/v0/block/$OPT_HEIGHT" \
-  "${AUTH_HEADER[@]}")"
+echo "optimistic @ $OPT_HEIGHT: $(curl -s "https://mainnet.neardata.xyz$OPT_PATH?apiKey=${FASTNEAR_API_KEY:-}" | count_touches "$TARGET_CONTRACT") touches"
+FINAL="$(curl -s "https://mainnet.neardata.xyz/v0/block/$OPT_HEIGHT?apiKey=${FASTNEAR_API_KEY:-}")"
 if [ "$(printf '%s' "$FINAL" | jq 'type')" = '"null"' ]; then
   echo "finalized @ $OPT_HEIGHT: not caught up yet"
 else
@@ -102,18 +93,14 @@ Most finalized blocks show no state mutation for any given contract — activity
 
 ```bash
 TARGET_CONTRACT=intents.near
-AUTH_HEADER=()
-if [ -n "${FASTNEAR_API_KEY:-}" ]; then AUTH_HEADER=(-H "Authorization: Bearer $FASTNEAR_API_KEY"); fi
 
-HEAD="$(curl -sL "https://mainnet.neardata.xyz/v0/last_block/final" \
-  "${AUTH_HEADER[@]}" | jq '.block.header.height')"
+HEAD="$(curl -sL "https://mainnet.neardata.xyz/v0/last_block/final?apiKey=${FASTNEAR_API_KEY:-}" | jq '.block.header.height')"
 FOUND_HEIGHT=""
 FOUND_SHARD=""
 
 for OFFSET in $(seq 0 15); do
   H=$((HEAD - OFFSET))
-  SHARD="$(curl -s "https://mainnet.neardata.xyz/v0/block/$H" \
-    "${AUTH_HEADER[@]}" \
+  SHARD="$(curl -s "https://mainnet.neardata.xyz/v0/block/$H?apiKey=${FASTNEAR_API_KEY:-}" \
     | jq -r --arg contract "$TARGET_CONTRACT" '
         .shards[]
         | select([.state_changes[]? | select(.change.account_id? == $contract)] | length > 0)
@@ -128,8 +115,7 @@ done
 if [ -z "$FOUND_HEIGHT" ]; then
   echo "no state mutation for $TARGET_CONTRACT in the last 16 finalized blocks"
 else
-  curl -s "https://mainnet.neardata.xyz/v0/block/$FOUND_HEIGHT/shard/$FOUND_SHARD" \
-    "${AUTH_HEADER[@]}" \
+  curl -s "https://mainnet.neardata.xyz/v0/block/$FOUND_HEIGHT/shard/$FOUND_SHARD?apiKey=${FASTNEAR_API_KEY:-}" \
     | jq --arg contract "$TARGET_CONTRACT" --argjson height "$FOUND_HEIGHT" --argjson shard_id "$FOUND_SHARD" '{
         height: $height,
         shard_id: $shard_id,