This project is a monorepo for various NPM packages scoped under @fastnear/. It's a TypeScript project that is a full rewrite, creating a new JavaScript library for building on NEAR Protocol.
The API itself (ergonomics, how you use it) will be changing more liberally until the release is out of alpha.
This repo also contains wallet-related packages, which provides an alternate path to the established wallet selector. While functional, the wallet side of this monorepo has seen less attention.
At this early stage, the best place to begin understanding this library is:
https://js.fastnear.com
It will load a demo backed by the same runtime surfaces that ship in this monorepo.
The monorepo now ships a low-level-first runtime plus a compact task catalog for humans and agents:
recipes/index.jsonis the canonical machine-readable task catalog.llms.txtis the concise repo map for agents.llms-full.txtexpands the same map with copy-paste snippets.recipes/near-node.mjsis the source file for the hostedagents.jsterminal wrapper.https://js.fastnear.com/recipes.jsonis the canonical hosted recipe catalog.
near.config({ apiKey })is the terse auth and base-url switch for the runtime.- Start with the low-level surfaces when you already know the family and want exact response shapes:
near.view,near.queryAccount,near.tx.*,near.api.v1.*,near.transfers.*,near.neardata.*, andnear.fastdata.kv.*. near.recipes.*stays available for the shortest task-oriented helpers layered on top of those low-level surfaces.near.recipes.list()andnear.recipes.toJSON()expose compact task discovery at runtime.near.api.v1.*,near.tx.*,near.transfers.*,near.neardata.*, andnear.fastdata.kv.*expose endpoint-shaped service namespaces that return raw parsed JSON.- Named exported response types are available from
@fastnear/api, for exampleFastNearTxTransactionsResponseandFastNearKvGetLatestKeyResponse. near.explain.*turns actions, transactions, and thrown errors into stable JSON summaries.- The original low-level entrypoints stay intact:
near.view,near.queryAccount,near.queryTx,near.sendTx,near.requestSignIn, andnear.signMessage.
- Canonical terminal wrapper:
https://js.fastnear.com/agents.js - Canonical hosted recipe catalog:
https://js.fastnear.com/recipes.json - Backward-compatible alias:
https://js.fastnear.com/near-node.mjs - Published CDN release gate:
yarn smoke:agent:published - npm publish updates
https://js.fastnear.com/near.jsthrough the package-backed redirect path. - Hosted site deploy updates
agents.js,near-node.mjs,recipes.json,llms.txt, andllms-full.txt.
- API key env var:
FASTNEAR_API_KEY - Hosted recipe catalog:
https://js.fastnear.com/recipes.json - Hosted terminal wrapper:
https://js.fastnear.com/agents.js - Free trial credits:
https://dashboard.fastnear.com
Set FASTNEAR_API_KEY before running the authenticated snippets.
- Read llms.txt — Start with the concise repo and runtime map.
- Fetch recipes.json — Use the hosted machine-readable recipe catalog with stable IDs, families, auth, returns, and snippets.
- Run agents.js — Use the hosted terminal wrapper when you want the FastNear JS surface.
- Fall back to curl + jq — Use raw transport when survey scripting or HTTP-level inspection is more useful.
Keep the object work in JS, then hand the emitted JSON back to shell tooling when you need one more filter step. Every near.recipes.*, near.view, near.ft.*, and near.nft.* accepts a per-call { network: "testnet" } override; see the connect-testnet and function-call-testnet recipes for the end-to-end testnet flow.
# Assumes FASTNEAR_API_KEY is already set in your shell.
ACCOUNT_SUMMARY="$(node -e "$(curl -fsSL https://js.fastnear.com/agents.js)" <<'EOF'
const account = await near.recipes.viewAccount("root.near");
const { block_hash, storage_usage } = account;
near.print({ block_hash, storage_usage });
EOF
)"
BLOCK_HASH="$(printf '%s\n' "$ACCOUNT_SUMMARY" | jq -r '.block_hash')"
STORAGE_USAGE="$(printf '%s\n' "$ACCOUNT_SUMMARY" | jq -r '.storage_usage')"
printf 'block_hash=%s\nstorage_usage=%s\n' "$BLOCK_HASH" "$STORAGE_USAGE"Canonical NEAR JSON-RPC defaults for direct contract views, account state, and transaction status checks.
- Auth style:
query - Default base URLs: mainnet
https://rpc.mainnet.fastnear.com/, testnethttps://rpc.testnet.fastnear.com/ - Pagination: none; request fields: none; response fields: none; filters must stay stable: no
- Best for:
- Direct contract view calls with exact method names and args.
- Canonical account state and access key reads.
- Low-level RPC questions before you need indexed or aggregated surfaces.
- Entrypoints:
near.viewnear.queryAccountnear.queryAccessKeynear.queryBlocknear.queryTxnear.sendTxnear.ft.balancenear.ft.metadatanear.ft.totalSupplynear.ft.storageBalancenear.nft.metadatanear.nft.tokennear.nft.forOwnernear.nft.supplyForOwnernear.nft.totalSupplynear.nft.tokens
FastNear REST aggregations for account holdings, staking, and public-key oriented lookups.
- Auth style:
bearer - Default base URLs: mainnet
https://api.fastnear.com, testnethttps://test.api.fastnear.com - Pagination: page_token; request fields: page_token; response fields: page_token; filters must stay stable: yes
- Best for:
- Combined account snapshots with fungible tokens, NFTs, and staking.
- Public-key-to-account discovery.
- Questions where one aggregated response is better than stitching multiple RPC calls.
- Entrypoints:
near.api.v1.accountFullnear.api.v1.accountFtnear.api.v1.accountNftnear.api.v1.accountStakingnear.api.v1.publicKeynear.api.v1.publicKeyAllnear.api.v1.ftTopnear.ft.inventorynear.nft.inventory
Indexed transaction and receipt lookups for readable execution history by hash, account, or block.
- Auth style:
bearer - Default base URLs: mainnet
https://tx.main.fastnear.com, testnethttps://tx.test.fastnear.com - Pagination: resume_token; request fields: resume_token; response fields: resume_token; filters must stay stable: yes
- Best for:
- Starting from one transaction hash or receipt id.
- Readable execution stories with receipts already joined in.
- Recent account or block-centered transaction history queries.
- Entrypoints:
near.tx.transactionsnear.tx.receiptnear.tx.accountnear.tx.blocknear.tx.blocks
Asset-movement-focused history for accounts when the question is specifically about transfers, not full execution.
- Auth style:
bearer - Default base URLs: mainnet
https://transfers.main.fastnear.com, testnetnull - Pagination: resume_token; request fields: resume_token; response fields: resume_token; filters must stay stable: yes
- Best for:
- Recent transfer feeds for one account.
- Asset movement summaries across FT, NFT, and native transfers.
- Survey scripting where transfer rows matter more than transaction internals.
- Entrypoints:
near.transfers.query
Block and shard documents for recent chain-state inspection without reconstructing shard layouts yourself.
- Auth style:
query - Default base URLs: mainnet
https://mainnet.neardata.xyz, testnethttps://testnet.neardata.xyz - Pagination: range; request fields: blockHeight, from_block_height, to_block_height; response fields: none; filters must stay stable: no
- Best for:
- Recent block inspection and shard-aware exploration.
- Questions about network recency or recent transaction volume.
- Walking block-height ranges and chunk layouts.
- Entrypoints:
near.neardata.lastBlockFinalnear.neardata.lastBlockOptimisticnear.neardata.blocknear.neardata.blockHeadersnear.neardata.blockShardnear.neardata.blockChunknear.neardata.blockOptimisticnear.neardata.firstBlocknear.neardata.health
Indexed key-value history for exact keys, predecessor scans, and account-scoped storage exploration.
- Auth style:
bearer - Default base URLs: mainnet
https://kv.main.fastnear.com, testnethttps://kv.test.fastnear.com - Pagination: resume_token; request fields: resume_token; response fields: resume_token; filters must stay stable: yes
- Best for:
- Exact-key lookups when you already know the contract, predecessor, and key.
- Storage history scans keyed by predecessor or current account.
- Questions about SocialDB-style writes and indexed storage history.
- Entrypoints:
near.fastdata.kv.getLatestKeynear.fastdata.kv.getHistoryKeynear.fastdata.kv.latestByAccountnear.fastdata.kv.historyByAccountnear.fastdata.kv.latestByPredecessornear.fastdata.kv.historyByPredecessornear.fastdata.kv.allByPredecessornear.fastdata.kv.multi
Start with one view call when you already know the contract, method, and arguments.
# Assumes FASTNEAR_API_KEY is already set in your shell.
node -e "$(curl -fsSL https://js.fastnear.com/agents.js)" <<'EOF'
const result = await near.recipes.viewContract({
contractId: "berryclub.ek.near",
methodName: "get_account",
args: { account_id: "root.near" },
});
near.print({
account_id: result.account_id,
avocado_balance: result.avocado_balance,
num_pixels: result.num_pixels,
});
EOFStart with the indexed transaction family when all you have is the hash and you want the readable story.
# Assumes FASTNEAR_API_KEY is already set in your shell.
node -e "$(curl -fsSL https://js.fastnear.com/agents.js)" <<'EOF'
const tx = await near.recipes.inspectTransaction(
"7ZKnhzt2MqMNmsk13dV8GAjGu3Db8aHzSBHeNeu9MJCq"
);
near.print(
tx
? {
hash: tx.transaction.hash,
signer_id: tx.transaction.signer_id,
receiver_id: tx.transaction.receiver_id,
included_block_height: tx.execution_outcome.block_height,
receipt_count: tx.receipts.length,
}
: null
);
EOFUse the FastNear account aggregator when the question is about holdings, NFTs, or staking in one response.
# Assumes FASTNEAR_API_KEY is already set in your shell.
node -e "$(curl -fsSL https://js.fastnear.com/agents.js)" <<'EOF'
const account = await near.api.v1.accountFull({
accountId: "root.near",
});
near.print({
account_id: account.account_id,
near_balance_yocto: account.state.balance,
ft_contracts: account.tokens.length,
nft_contracts: account.nfts.length,
staking_pool_contracts: account.pools.length,
});
EOFStart narrow with KV FastData when you already know the contract, predecessor, and exact storage key.
# Assumes FASTNEAR_API_KEY is already set in your shell.
node -e "$(curl -fsSL https://js.fastnear.com/agents.js)" <<'EOF'
const result = await near.fastdata.kv.getLatestKey({
currentAccountId: "social.near",
predecessorId: "james.near",
key: "graph/follow/sleet.near",
});
const latest = result.entries?.[0] || null;
near.print({
latest: latest
? {
current_account_id: latest.current_account_id,
predecessor_id: latest.predecessor_id,
block_height: latest.block_height,
key: latest.key,
value: latest.value,
}
: null,
});
EOFnear.explain.action: Normalize one action into a stable JSON summary.near.explain.tx: Summarize a signer, receiver, and action list into stable JSON.near.explain.error: Turn thrown RPC, wallet, or transport failures into a predictable JSON object.
The repo keeps the confidence ladder intentionally small:
yarn testis the fast local and PR path. It runs Vitest plus the local generated-snippet smoke.yarn smoke:services:liveis the live infrastructure check. It does one read-only call per FastNear family, including a pinned archival RPC read.yarn smoke:agent:publishedis the manual published-surface gate. Use it after publish when you want to verify the publicagents.js,recipes.json, andllms.txtassets.
Yarn is used in this repo, and it's likely not the yarn commonly installed. You must run:
yarn set version berry
yarn build
Will go through all the workspaces packages (see workspaces key in package.json) and build them for ECMAScript, CommonJS, and a Universal Module Definition. This is achieved using esbuild.
Remember that esbuild and similar systems separate the TypeScript evaluation, strict or not, and so we cannot assume that a successful yarn build means valid TypeScript.
yarn type-check
During development, this was helpful:
yarn type-check && yarn build
If the tsc call (that does not emit artifacts) finds an error, it'll stop before building.
Will run a command and catch TypeScript problems that should be fixed.
This repo has a tsconfig.base.json that is used in some packages during build. It currently has strict: true but it can be helpful to turn it off during particularly rapid development. It won't (shouldn't) harm your project to turn off strict mode. This library will seek to adhere to strict mode, but that does not cascade into demanding this from end developers.
Each workspace package (NPM module) has an esbuild.config.mjs file that's used to take the TypeScript files in the src directory and compile them to:
The modern JavaScript module system, primarily used for browser and server environments, and the default for most new packages.
The older module system for NodeJS, ensuring backwards compatibility.
A universal module format that works in browsers (with or without a bundler) and in NodeJS, bridging the gap between different environments.
Universal Module Definition (UMD) is a versatile module format that aims to provide compatibility across different environments, including both browsers and server-side applications. Unlike purely browser-centric solutions like AMD or server-specific formats like CommonJS, UMD offers a unified approach. It checks the environment and adapts accordingly, making it suitable for various scenarios without requiring major adjustments. source
All workspace packages publish a new version regardless of whether the package was modified.
Each package's dist folder is revisioned, so make sure to run build. Not intending to focus much on CI.
In the project root, open package.json and change the version that should be reflected in all packages.
yarn constraints
The file yarn.config.cjs defines a Yarn constraint that takes the root manifest and updates all the workspace package versions based on that.
After you bump the version run yarn build again because the artifacts will be updated in the comments about the version.
OTP is required and can be input into the command:
yarn workspaces foreach --all -tv run release --access public --otp <OTP>
Use the workspace release script rather than raw npm publish. The release scripts publish a tarball produced by yarn pack, so workspace dependencies are packed with concrete versions while npm CLI auth and OTP handling still work normally.
I've only been testing with MyNEARWallet for a wallet. There may be obvious issues in the other ones, I don't know :)
Generally, the most progress has been on the API. Expect to find more unaddressed wallet issues than API ones. And feel free to lean in, knowing it's alpha and greenfield.
Give extra attention to examples/static/ and examples/nextjs/; they now represent the intended example surfaces for the repo.
Exports are coming from the utils package in this monorepo. Want to acknowledge the hard work that went into this, and show gratitude for their willingness to have open source licenses.
The Borsh binary serialization format originated in the NEAR ecosystem. This monorepo includes @fastnear/borsh, a clean-room reimplementation that replaces the external borsh npm package (borsh-js). The implementation is not derived from borsh-js code.
Note: we are currently exporting sha256 from this library, but I believe the Web API Crypto and Crypto.Subtle have this ability and that library export won't be needed.