# FastNear JS monorepo

Homepage: https://js.fastnear.com

Primary packages:
- @fastnear/api
- @fastnear/wallet
- @fastnear/utils
- @fastnear/ml-dsa-65
- @fastnear/x402
- @fastnear/intents

Low-level-first runtime surfaces:
- near.config({ apiKey })
- near.config({ retry, batch }) — auto 429/transient retry + bulk-read concurrency cap, both on by default
- near.view
- near.view.many — bulk views, settled results, concurrency-capped
- near.batch — bulk RPC, settled results, per-item error kind (transport/http/rpc/contract)
- near.queryAccount
- near.queryAccessKey
- near.queryAccessKeyList
- near.queryProtocolVersion
- near.sendTx({ signer, signerId, ... })
- near.tx.transactions
- near.api.v1.accountFull
- near.transfers.query
- near.neardata.lastBlockFinal
- near.fastdata.kv.getLatestKey
- near.recipes.viewContract
- near.recipes.viewAccount
- near.recipes.inspectTransaction
- near.recipes.functionCall
- near.recipes.transfer
- near.recipes.connect
- near.recipes.signMessage
- near.recipes.list
- near.recipes.toJSON
- near.explain.action
- near.explain.tx
- near.explain.error

ML-DSA-65 account-key surface:
- @fastnear/ml-dsa-65 generateSigner / signerFromSeed / signerFromSecretKey
- Protocol activation: active RPC protocol_version >= 85
- Exact wire sizes: 1952-byte public key; 3309-byte signature
- Verification charge: 100 Ggas per outer or delegated verification
- Full access-key form: ml-dsa-65:<base58 public key>
- Access-key-list form: ml-dsa-65-hash:<base58 SHA3-256 digest>
- Handle domain tag: near:ml-dsa-65-pubkey-hash:v1
- Quickstarts: ml-dsa-65-generate, ml-dsa-65-explicit-send, ml-dsa-65-enroll-delete, ml-dsa-65-reconcile

Wallet runtime surfaces (@fastnear/wallet):
- nearWallet.connect({ network, contractId, manifest })
- nearWallet.disconnect({ network })
- nearWallet.restore({ network })
- nearWallet.sendTransaction({ receiverId, actions, network })
- nearWallet.sendTransactions({ transactions, network })
- nearWallet.signMessage({ message, recipient, nonce, network })
- nearWallet.signDelegateActions({ delegateActions: [{ ..., blockHeightTtl }], signerId, network }) — timeout-aware requests require signDelegateActionsWithTtl
- nearWallet.addFunctionCallKey({ contractId, methodNames, allowance, network })
- nearWallet.accountId({ network })
- nearWallet.isConnected({ network })
- nearWallet.connectedNetworks()
- nearWallet.switchNetwork(network)
- nearWallet.onConnect(handler)
- nearWallet.onDisconnect(handler)

x402 payment surface (@fastnear/x402):
- Runtime: Package-only; not included in agents.js or near.js.
- Protocol: x402 v2 exact; networks: near:mainnet, near:testnet; asset: NEP-141 fungible tokens
- Pay a URL in Node: createLocalNearSigner + createNearPaymentFetch (@fastnear/x402/node + @fastnear/x402)
- Protect a seller resource: createNearResourceServer (@fastnear/x402/server); explicit facilitator required
- Browser: createFastNearWalletSigner / createNearX402Client / createNearPaymentFetch (global nearX402)
- Node: @fastnear/x402/node createLocalNearSigner
- Seller: @fastnear/x402/server createNearResourceServer; explicit facilitator required
- Self-hosted facilitator: @fastnear/x402/facilitator createNearFacilitator
- Wallet features: signDelegateActions + signDelegateActionsWithTtl
- Status: Stable with tested Meteor Wallet support; other wallets must advertise both timeout-aware delegate-signing capabilities and pass the x402 testnet harness before being documented as compatible.
- Guide: https://github.com/fastnear/js-monorepo/blob/main/packages/x402/README.md

NEAR Intents surface (@fastnear/intents):
- Runtime: Package-only; not included in agents.js or near.js.
- Verifier: intents.near (mainnet); ledger: NEP-245 multi-token ids like nep141:wrap.near
- Quote/track swaps: createOneClickClient (https://1click.chaindefuser.com); keyless adds a 0.2% fee
- Browser signing: createWalletIntentSigner (global nearIntents) over nearWallet.signMessage — NEP-413, full-access keys only
- Node signing: @fastnear/intents/node createLocalIntentSigner
- Verifier helpers: ftDepositAction / wrapNearAction / ftWithdrawAction + mtBalance / mtBatchBalances views
- Solver relay: @fastnear/intents/relay createSolverRelayClient (https://solver-relay-v2.chaindefuser.com/rpc); quotes need a partner API key
- Signature encoding: MultiPayload wants ed25519:<base58> — the signers re-encode the wallet's base64
- Status: The wallet signing path uses nearWallet.signMessage (NEP-413), which every near-connect executor implements; the funded end-to-end swap path is verified by the mainnet smoke runbook before being documented further.
- Guide: https://github.com/fastnear/js-monorepo/blob/main/packages/intents/README.md

Named endpoint response types:
- FastNearRecipeDiscoveryEntry
- FastNearApiV1AccountFullResponse
- FastNearTxTransactionsResponse
- FastNearTransfersQueryResponse
- FastNearNeardataLastBlockFinalResponse
- FastNearKvGetLatestKeyResponse

Canonical machine-readable catalog:
- recipes/index.json
- https://js.fastnear.com/recipes.json

Canonical hosted agent wrapper:
- https://js.fastnear.com/agents.js

Hosted topic explainers:
- https://js.fastnear.com/transactions.html — Constructing a transaction
- https://js.fastnear.com/x402.html — x402 payments on NEAR
- https://js.fastnear.com/post-quantum.html — Post-quantum ML-DSA-65 keys
- https://js.fastnear.com/retries.html — Retries and bulk reads
- https://js.fastnear.com/intents.html — NEAR Intents

Wrapper source in repo:
- recipes/near-node.mjs

Mental model:
- Start with the low-level APIs when you know the exact FastNear family you want.
- Use near.recipes.* as compact task helpers layered on top of those lower-level APIs.
- Use near.recipes.list() or near.recipes.toJSON() when you want to discover the task helpers at runtime.

Result shapes:
- near.query* (queryAccount, queryBlock, queryAccessKey, queryTx) return the raw JSON-RPC envelope { jsonrpc, result, id } — read your data from the .result field.
- near.view, near.recipes.*, near.ft.*, near.nft.*, near.tx.*, near.api.v1.*, near.transfers.*, near.neardata.*, and near.fastdata.kv.* return the data shape directly (no envelope).
- Wide integers are strings: amounts, gas, deposits, nonces and other u64/u128 values come back as decimal strings (JSON-safe, matching NEAR RPC). Constructing a tx accepts string | number | bigint and unit strings like "100 Tgas" / "0.01 NEAR"; inspect a built transaction with near.utils.txToJson (never JSON.stringify a bigint). You never need BigInt to build, send, or read a transaction.

Trial credits / API keys:
- https://dashboard.fastnear.com

Discovery order:
- 1. Read llms.txt: Start with the concise repo and runtime map.
- 2. Fetch recipes.json: Use the hosted machine-readable recipe catalog with stable IDs, families, auth, returns, and snippets.
- 3. Run agents.js: Use the hosted terminal wrapper when you want the FastNear JS surface.
- 4. Fall back to curl + jq: Use raw transport when survey scripting or HTTP-level inspection is more useful.

Families:
- rpc: Canonical NEAR JSON-RPC defaults for direct contract views, account state, and transaction status checks. 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..
- api: FastNear REST aggregations for account holdings, staking, and public-key oriented lookups. 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..
- tx: Indexed transaction and receipt lookups for readable execution history by hash, account, or block. 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..
- transfers: Asset-movement-focused history for accounts when the question is specifically about transfers, not full execution. 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..
- neardata: Block and shard documents for recent chain-state inspection without reconstructing shard layouts yourself. Best for Recent block inspection and shard-aware exploration. / Questions about network recency or recent transaction volume. / Walking block-height ranges and chunk layouts..
- fastdata.kv: Indexed key-value history for exact keys, predecessor scans, and account-scoped storage exploration. 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..

Recipe index format: id: question (family, return type, auth style, default network)

Recipe index:
- view-contract: What does this contract method return? (rpc, BerryClubAccountView, none, mainnet)
- view-account: What does this account look like on chain? (rpc, RpcViewAccountResponse, none, mainnet)
- inspect-transaction: What happened in this transaction? (tx, FastNearTxTransactionsResponse, none, mainnet)
- account-full: What does this account own? (api, FastNearApiV1AccountFullResponse, none, mainnet)
- transfers-query: What is this account's recent transfer activity? (transfers, FastNearTransfersQueryResponse, none, mainnet)
- last-block-final: What block is NEAR on right now? (neardata, FastNearNeardataLastBlockFinalResponse, none, mainnet)
- kv-latest-key: What is the latest indexed value for this exact key? (fastdata.kv, FastNearKvGetLatestKeyResponse, none, mainnet)
- connect-wallet: How do I connect a wallet? (wallet, { accountId: string } | undefined, wallet, mainnet)
- function-call: How do I send one function call? (wallet, WalletTransactionResult, wallet, mainnet)
- transfer: How do I transfer NEAR? (wallet, WalletTransactionResult, wallet+deposit, mainnet)
- sign-message: How do I sign a message? (wallet, WalletMessageSignatureResult, wallet, mainnet)
- sign-delegate-actions: How do I sign delegate actions for gasless transactions? (wallet, SignDelegateActionsResponse, wallet, mainnet)
- explain-transaction: How do I build and preview a transaction before signing? (api, ExplainedTransaction, none, mainnet)
- ft-balance: What is this account's FT balance? (rpc, string, none, mainnet)
- ft-metadata: What does this NEP-141 token call itself? (rpc, { name: string; symbol: string; decimals: number; icon?: string; reference?: string; reference_hash?: string }, none, mainnet)
- ft-inventory: Which fungible tokens does this account hold? (api, { tokens: Array<{ contract_id: string; balance: string; last_update_block_height?: number }> }, bearer, mainnet)
- nft-for-owner: Which NFTs does this account own on this contract? (rpc, Array<{ token_id: string; owner_id: string; metadata?: { title?: string; media?: string; description?: string } }>, none, mainnet)
- nft-inventory: Which NFT contracts does this account hold tokens on? (api, { tokens: Array<{ contract_id: string; last_update_block_height: number | null }> }, bearer, mainnet)
- archival-snapshot: What did this account look like at a specific block? (rpc, RpcViewAccountResponse, none, mainnet)
- connect-testnet: How do I open a testnet wallet session alongside mainnet? (wallet, { accountId: string; network?: "mainnet" | "testnet" } | undefined, wallet, testnet)
- function-call-testnet: How do I send a function call on testnet without losing my mainnet session? (wallet, { outcomes?: any[] } | { rejected: true } | undefined, wallet, testnet)