Агенты на FastNear

Эта страница — операционная точка входа для ИИ-агентов, краулеров и сред автоматизации, использующих FastNear. Цель простая: распознать реальную задачу пользователя, выбрать один API FastNear, получить минимальный полезный результат и расширяться на другой API только тогда, когда явно не хватает части ответа.

Если нужен только следующий шаг

• Нужно выбрать, с какого API FastNear начать? Используйте Как выбрать подходящую поверхность.
• Нужны правила работы с учётными данными? Используйте Аутентификацию для агентов.
• Нужны примеры многошаговых сценариев? Используйте Плейбуки для агентов.
• Нужна точная документация по эндпоинту сейчас? Сразу откройте Справочник RPC, FastNear API, Транзакции API, API переводов, NEAR Data API или KV FastData API.

FastNear для агентов за минуту

• Используйте индексированные API, когда пользователю нужен ответ в продуктовой форме — балансы, активы, история аккаунта или история переводов.
• Используйте Справочник RPC, когда пользователю нужны канонические поля на уровне протокола, вызовы контрактов или отправка транзакций.
• Используйте NEAR Data API, когда вопрос касается свежих оптимистичных или финализированных блоков и явного опроса.
• Используйте Снапшоты для операторских сценариев, а не для чтения прикладных данных.
• Один API-ключ FastNear работает и для RPC, и для REST API.
• Останавливайтесь после первого достаточного ответа. Не собирайте данные из нескольких API, если текущего результата достаточно.

Что определить до первого запроса

Попробуйте выявить эти входные данные до вызова:

• Сеть: mainnet или testnet.
• Первичный идентификатор: идентификатор аккаунта, публичный ключ, хеш транзакции, ID квитанции, высота / хеш блока, идентификатор контракта плюс ключ хранилища или задача по подъёму узла.
• Форма ответа: сводка, история, канонический вывод протокола или инструкции оператора.
• Требование к свежести: историческая, текущая, оптимистичная / последняя или финализированная / последняя.
• Требование к точности: достаточно индексированной сводки или нужна точная каноническая семантика узла.

Если чего-то не хватает — делайте небольшое предположение, когда вероятный стартовый API от этого не меняется. Задавайте уточняющий вопрос только тогда, когда неверный выбор API существенно изменит результат.

API FastNear с одного взгляда

API	Начните здесь, когда...	Типичные входы	Расширяйтесь, только если...
FastNear API	Пользователю нужны балансы, NFT, стейкинг, разрешение публичного ключа или сводка по аккаунту	account_id, публичный ключ	Нужны точные канонические поля узла
Справочник RPC	Пользователю нужен канонический вывод протокола, вызовы контрактов, данные валидаторов или отправка транзакций	account_id, высота / хеш блока, параметры конкретного метода	Также нужна сводка более высокого уровня или индексированная история
Транзакции API	Пользователю нужна история транзакций, квитанций, аккаунта или исполнения по блокам	хеш транзакции, ID квитанции, account_id, идентификаторы блока	Нужна точная семантика продолжения или финальности на уровне RPC
API переводов	Пользователю нужна история только переводов	account_id, фильтры переводов	Вопрос расширяется до общего контекста исполнения
NEAR Data API	Пользователю нужны свежие оптимистичные или финализированные блоки, заголовки или помощники по последнему блоку	высота / хеш блока, требование к свежести	Нужно точное каноническое продолжение по блоку или состоянию
KV FastData API	Пользователю нужна индексированная история ключа контракта или последнее индексированное состояние «ключ–значение»	идентификатор контракта, ключ хранилища	Нужно точное текущее состояние в цепочке
Снапшоты	Пользователь поднимает инфраструктуру	сеть, тип узла, цель оператора	Пользователь переключается на прикладные вопросы о цепочке

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

Используйте этот цикл, если задача явно не требует чего-то более специального:

1. Переформулируйте слова пользователя в реальную задачу. Примеры: сводка по аккаунту, инспекция канонического состояния, расследование транзакции, история только переводов, мониторинг свежих блоков или подъём узла.
2. Выберите один API FastNear. Не собирайте данные из нескольких API, пока первый результат не окажется недостаточным.
3. Подтяните минимальный релевантный контекст документации. Используйте страницу-индекс API, страницу эндпоинта или Markdown-зеркало вместо широкого неочевидного набора документов.
4. Сделайте первый запрос, соответствующий идентификатору пользователя и ожидаемой форме ответа.
5. Остановитесь, если результата уже достаточно для ответа пользователю.
6. Расширяйтесь, только когда можете точно назвать недостающую часть. Примеры: каноническое подтверждение, более широкая история исполнения, более свежие данные семейства блоков или точные поля протокола.

Хорошие значения по умолчанию

Когда формулировка пользователя коротка, но намерение типично, такие значения по умолчанию обычно корректны:

• «Проверь этот аккаунт» обычно стартует с FastNear API.
• «Проверь этот публичный ключ» обычно стартует с FastNear API для разрешения ключа в аккаунт.
• «Проверь эту транзакцию» обычно стартует с Транзакции API.
• «Проверь эту квитанцию» обычно стартует с Транзакции API.
• «Проверь этот блок» обычно стартует с NEAR Data API для мониторинга свежих блоков или со Справочника RPC для точных канонических данных блока.
• «Проверь этот ключ / историю контракта» обычно стартует с KV FastData API.
• «Помоги поднять узел» стартует со Снапшотов.

Полные правила маршрутизации и компромиссы — в Как выбрать подходящую поверхность.

Расширяйтесь осторожно

Хорошие шаблоны эскалации:

• Начните с FastNear API, затем переходите в Справочник RPC, если пользователь просит каноническое подтверждение.
• Начните с Транзакции API, затем переходите в Справочник RPC, если пользователю нужно протокольное продолжение по транзакции или квитанции.
• Начните с API переводов, затем расширяйтесь в Транзакции API, если вопрос выходит за рамки событий переводов.
• Начните с NEAR Data API, затем переходите в Справочник RPC, если нужна точная каноническая инспекция блока или состояния.

Плохой шаблон:

• Тянуть данные из нескольких API FastNear до того, как понятно, что именно нужно пользователю. Обычно это даёт более шумный ответ, а не более полезный.

Аутентифицируйтесь один раз, используйте везде

Публичные эндпоинты работают и без ключа. Добавьте ключ, если нужны повышенные лимиты или платные сценарии. Один и тот же ключ работает со всеми API FastNear выше; передавайте его либо в HTTP-заголовке, либо в URL-параметре:

Заголовок Authorization

curl "https://rpc.mainnet.fastnear.com" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"method":"block","params":{"finality":"final"},"id":1,"jsonrpc":"2.0"}'

URL-параметр

curl "https://rpc.mainnet.fastnear.com?apiKey=${API_KEY}"

Получить ключ: dashboard.fastnear.com. Операционный режим для неинтерактивных сред: Аутентификация для агентов — ключи должны жить в переменных окружения или менеджере секретов, а не в браузерном хранилище, логах чатов или промптах. Полный сценарий и детали заголовков: Аутентификация и доступ.

Как вынимать чистую документацию в промпт

• На каждой странице в правом верхнем углу есть кнопка Копировать Markdown. Она отдаёт Markdown-версию страницы без навигации, готовую к вставке в промпт или RAG-хранилище.
• Соглашение llms.txt поддерживается:
  • /llms.txt — индекс страниц и краткие описания.
  • /llms-full.txt — полный корпус документации в одном файле.
  • Русскоязычные аналоги: /ru/llms.txt и /ru/llms-full.txt.
• Машиночитаемая структура сайта для поглощения с учётом графа: /structured-data/site-graph.json (зеркало в /ru/).
• Под тем же slug с суффиксом .md лежит Markdown-зеркало каждой страницы, если прямой запрос удобнее кнопки «Копировать Markdown».

Подсказки на каждый вызов

• Имена параметров, поля ответа и примеры пэйлоадов отрисовываются на каждой странице эндпоинта в реальном времени. Первоисточник — реестр src/data/generatedFastnearPageModels.json, используйте его, если зеркалите схему в другой системе.
• ?network=testnet поддерживается только на конкретных страницах. Каждая страница отмечает поддержку сетей в разделе Аутентификация и доступность; не считайте, что переключение работает везде.
• Токены пагинации (resume_token, page_token) непрозрачны. Используйте их ровно в том виде, в котором они пришли, и только с тем же эндпоинтом и фильтрами, что их вернули.
• В каждом REST-семействе есть маршруты /status и /health для проверки живости и задержки синхронизации.

Что должен содержать полезный ответ агента

• Краткое указание на то, какой API FastNear был использован и почему, особенно если выбор был выводом.
• Ответ в форме, которая, скорее всего, понадобится пользователю следующей: сначала сводка для людей; точные поля или подсказки по следующему вызову для технического потребителя.
• Любое важное предостережение о свежести, каноничности, пагинации или выборе сети.
• Путь продолжения — только когда это реально помогает. Примеры: «используйте RPC для канонического подтверждения» или «используйте Транзакции API, если нужен более широкий контекст исполнения».

Избегайте сбрасывать сырые пэйлоады, когда пользователь на самом деле спрашивает об интерпретации.

Следующие документы по потребности

• Нужна глубина маршрутизации и компромиссы? Как выбрать подходящую поверхность
• Нужен режим работы с учётными данными и обращение с секретами? Аутентификация для агентов
• Нужны примеры сценариев? Плейбуки для агентов