Перейти к основному содержимому

KV FastData API

KV FastData API — это индексированное семейство «ключ–значение». Используйте его, когда уже известен контракт, аккаунт, predecessor_id или область ключа, которую нужно проинспектировать, и нужны индексированные строки без построения собственного слоя индексации хранилища.

Базовые URL​

OpenAPI: JSON · YAML · все спецификации

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

Быстрый старт​

Если вы уже знаете один точный ключ, начните с последней индексированной строки и остановитесь, как только она ответит на вопрос.

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
          }
      )
    }'

Это самый узкий полезный KV-запрос: один точный ключ и одна последняя индексированная строка. Если следующий вопрос уже звучит как «как этот ключ менялся со временем?», переходите к истории по точному ключу или к более подробным примерам KV FastData.

Используйте этот API, когда​

  • нужно последнее индексированное состояние по одному ключу или известному семейству ключей
  • нужна история изменений по аккаунту, ключу или predecessor_id
  • нужны пакетные поиски по уже известным точным ключам
  • идёт отладка хранилища контракта в индексированном виде

Не стартуйте здесь, когда​

  • нужны балансы, активы токенов, NFT или сводки аккаунта
  • нужны свежие данные семейства блоков
  • нужно точное текущее состояние в цепочке с канонической семантикой RPC

Используйте FastNear API для представлений аккаунта более высокого уровня, NEAR Data API для чтений семейства блоков и Справочник RPC для канонической инспекции состояния контракта.

Минимально полезные входы​

  • сеть
  • идентификатор контракта или другая точная область — аккаунт, predecessor_id или точный ключ
  • нужно пользователю последнее индексированное значение или история изменений

Выберите форму запроса​

Нужен сценарий?​

Используйте примеры KV FastData для практических примеров: поиска по точному ключу, истории ключей, анализа по predecessor_id и перехода к каноническому RPC.

Рабочий цикл по умолчанию​

  1. Выберите самую узкую область, подходящую под вопрос пользователя.
  2. Оставайтесь внутри KV FastData, пока вопрос остаётся про индексированные данные «ключ–значение».
  3. Используйте эндпоинты «последнего значения» для текущих индексированных представлений, а исторические эндпоинты — только когда пользователю нужны ответы с изменением во времени.
  4. Остановитесь, как только индексированных строк уже достаточно для ответа на вопрос о хранилище.

Аутентификация и доступность​

  • Передавайте API-ключ FastNear в каждом запросе.
  • Если вы стандартизируете один FastNear API-ключ на всех поверхностях FastNear, используйте здесь тот же формат через заголовок или параметр запроса.
  • Добавьте ?network=testnet, чтобы переключить страницу на testnet-бэкенд там, где это поддерживается.
  • В ответах со списками поле page_token отсутствует, когда новых результатов больше нет.

Расширяйтесь, только если​

  • пользователю нужно точное текущее состояние в цепочке, а не индексированные данные хранилища
  • пользователю нужна каноническая семантика состояния контракта
  • индексированное представление хранилища — неподходящая абстракция для вопроса

Тогда расширяйтесь на Просмотр состояния контракта в Справочнике RPC.

Устранение неполадок​

Токен пагинации перестал работать​

Считайте значения page_token непрозрачными и переиспользуйте их только с тем же эндпоинтом и фильтрами.

Мне нужны продуктовые балансы аккаунта, а не сырые строки «ключ–значение»​

Переходите на FastNear API.