Skip to main content

Agents on FastNear

This page is the operational starting point for AI agents, crawlers, and automation runtimes using FastNear. The goal is simple: identify the user's actual task, choose one FastNear API first, fetch the smallest useful result, and only widen to another API when there is a clear missing piece.

If you only need the next step​

FastNear for agents in one minute​

  • Use indexed APIs when the user wants a product-shaped answer such as balances, holdings, account history, or transfer history.
  • Use RPC Reference when the user needs canonical protocol-native fields, contract calls, or transaction submission.
  • Use NEAR Data API when the question is about recent optimistic or finalized blocks and explicit polling.
  • Use Snapshots for operator workflows, not application-level data reads.
  • One FastNear API key works across the RPC and REST APIs.
  • Stop after the first sufficient answer. Do not collect from multiple APIs unless the current result is insufficient.

What to resolve before the first request​

Try to identify these inputs before you make a call:

  • Network: mainnet or testnet.
  • Primary identifier: account ID, public key, transaction hash, receipt ID, block height/hash, contract ID plus storage key, or node/bootstrap task.
  • Answer shape: summary, history, canonical protocol output, or operator instructions.
  • Freshness requirement: historical, current, optimistic/latest, or finalized/latest.
  • Precision requirement: indexed summary is acceptable, or exact canonical node semantics are required.

If one of these is missing, make a small assumption when the likely starting API does not change. Ask a clarifying question only when the wrong API choice would materially change the result.

FastNear APIs at a glance​

APIStart here when...Typical inputsWiden only if...
FastNear APIThe user wants balances, NFTs, staking, public-key resolution, or an account summaryaccount_id, public keyThe user needs exact canonical node fields
RPC ReferenceThe user wants canonical protocol output, contract calls, validator data, or transaction submissionaccount_id, block height/hash, method-specific paramsThe user also needs a higher-level summary or indexed history
Transactions APIThe user wants transaction, receipt, account, or block execution historytransaction hash, receipt ID, account_id, block identifiersThe user needs exact RPC-level follow-up or finality semantics
Transfers APIThe user wants transfer-only historyaccount_id, transfer filtersThe question broadens to general execution context
NEAR Data APIThe user wants recent optimistic or finalized blocks, headers, or latest-block helpersblock height/hash, freshness requirementThe user needs exact canonical block/state follow-up
KV FastData APIThe user wants indexed contract key history or latest indexed key-value statecontract ID, storage keyThe user needs exact on-chain current state
SnapshotsThe user is standing up infrastructurenetwork, node type, operator goalThe user shifts to application-level chain questions

Default workflow​

Use this loop unless the task clearly needs something more specialized:

  1. Translate the user's wording into the task they actually need solved. Examples: account summary, canonical state inspection, transaction investigation, transfer-only history, recent block monitoring, or node bootstrap.
  2. Pick one FastNear API first. Do not gather from multiple APIs until the first result proves insufficient.
  3. Pull the smallest relevant docs context. Use the API index page, endpoint page, or Markdown mirror instead of broad unrelated docs.
  4. Make the first request that matches the user's identifier and expected answer shape.
  5. Stop if the result is already sufficient to answer the user's question.
  6. Widen only when you can name the missing piece precisely. Examples: canonical confirmation, broader execution history, fresher block-family data, or exact protocol fields.

Good defaults​

When the user's wording is short but the intent is common, these defaults are usually correct:

Full routing rules and tradeoffs live in Choosing the Right Surface.

Widen carefully​

Good escalation patterns:

Bad pattern:

  • Pull from several FastNear APIs before you know what the user actually needs. That usually produces a noisier answer, not a better one.

Authenticate once, reuse everywhere​

Public endpoints work without a key. Add a key for higher limits or paid access patterns. The same key works across every FastNear API above; send it either as an HTTP header or a URL parameter:

Authorization header
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 parameter
curl "https://rpc.mainnet.fastnear.com?apiKey=${API_KEY}"

Get a key from dashboard.fastnear.com. Operational posture for non-interactive runtimes: Auth for Agents — keys go in env vars or a secret manager, never in browser storage, chat logs, or prompts. Full flow and header details: Auth & Access.

Pull clean docs into a prompt​

  • Every page has a Copy Markdown button in the top-right toolbar. It emits a navigation-chrome-free Markdown version of the page, ready to paste into a prompt or RAG store.
  • The llms.txt convention is mirrored here:
  • Machine-readable site structure for graph-aware ingestion: /structured-data/site-graph.json (mirrored in /ru/).
  • Per-page Markdown mirrors live under the same slug with a .md suffix if you prefer direct fetches over the Copy Markdown button.

Per-call hints an agent should know​

  • Parameter names, response fields, and example payloads are rendered live on each endpoint page. The underlying registry lives at src/data/generatedFastnearPageModels.json if you are mirroring schema into another system.
  • ?network=testnet is supported on specific pages only. Each page calls out its network support in the Auth and availability section; do not assume it works globally.
  • Pagination tokens (resume_token, page_token) are opaque. Reuse them verbatim and only with the endpoint plus filter set that produced them.
  • Status routes: every REST family ships a /status and /health path for liveness and sync-latency inspection.

What a useful agent answer should contain​

  • A brief statement of which FastNear API was used and why, especially if the choice was an inference.
  • The answer in the shape the user is likely to need next: summary first for humans, exact fields or next-call guidance when the caller is technical.
  • Any important caveat about freshness, canonicality, pagination, or network choice.
  • A follow-up path only when it is likely to help. Examples: "use RPC for canonical confirmation" or "use Transactions API if you need broader execution context."

Avoid dumping raw payloads when the user is really asking for interpretation.

Next docs by need​