{ "version": 4, "homepage": "https://js.fastnear.com", "source": "recipes/source.mjs", "catalogUrl": "https://js.fastnear.com/recipes.json", "packages": [ "@fastnear/api", "@fastnear/wallet", "@fastnear/utils" ], "support": { "apiKeyEnvVar": "FASTNEAR_API_KEY", "apiKeySummary": "Set FASTNEAR_API_KEY before running the authenticated snippets.", "hostedCatalogUrl": "https://js.fastnear.com/recipes.json", "hostedCatalogLabel": "js.fastnear.com/recipes.json", "hostedAgentEntry": "https://js.fastnear.com/agents.js", "trialCreditsUrl": "https://dashboard.fastnear.com", "trialCreditsLabel": "dashboard.fastnear.com", "trialCreditsSummary": "Free trial credits are available at dashboard.fastnear.com.", "discoveryOrder": [ { "step": 1, "label": "Read llms.txt", "detail": "Start with the concise repo and runtime map." }, { "step": 2, "label": "Fetch recipes.json", "detail": "Use the hosted machine-readable recipe catalog with stable IDs, families, auth, returns, and snippets." }, { "step": 3, "label": "Run agents.js", "detail": "Use the hosted terminal wrapper when you want the FastNear JS surface." }, { "step": 4, "label": "Fall back to curl + jq", "detail": "Use raw transport when survey scripting or HTTP-level inspection is more useful." } ], "captureExample": { "title": "Capture and chain one result", "summary": "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.", "language": "bash", "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_SUMMARY=\"$(node -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst account = await near.recipes.viewAccount(\"root.near\");\n\nconst { block_hash, storage_usage } = account;\n\nnear.print({ block_hash, storage_usage });\nEOF\n)\"\nBLOCK_HASH=\"$(printf '%s\\n' \"$ACCOUNT_SUMMARY\" | jq -r '.block_hash')\"\nSTORAGE_USAGE=\"$(printf '%s\\n' \"$ACCOUNT_SUMMARY\" | jq -r '.storage_usage')\"\n\nprintf 'block_hash=%s\\nstorage_usage=%s\\n' \"$BLOCK_HASH\" \"$STORAGE_USAGE\"" } }, "families": [ { "id": "rpc", "summary": "Canonical NEAR JSON-RPC defaults for direct contract views, account state, and transaction status checks.", "authStyle": "query", "defaultBaseUrls": { "mainnet": "https://rpc.mainnet.fastnear.com/", "testnet": "https://rpc.testnet.fastnear.com/" }, "bestFor": [ "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." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "entrypoints": [ "near.view", "near.queryAccount", "near.queryAccessKey", "near.queryBlock", "near.queryTx", "near.sendTx", "near.ft.balance", "near.ft.metadata", "near.ft.totalSupply", "near.ft.storageBalance", "near.nft.metadata", "near.nft.token", "near.nft.forOwner", "near.nft.supplyForOwner", "near.nft.totalSupply", "near.nft.tokens" ] }, { "id": "api", "summary": "FastNear REST aggregations for account holdings, staking, and public-key oriented lookups.", "authStyle": "bearer", "defaultBaseUrls": { "mainnet": "https://api.fastnear.com", "testnet": "https://test.api.fastnear.com" }, "bestFor": [ "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." ], "pagination": { "kind": "page_token", "requestFields": [ "page_token" ], "responseFields": [ "page_token" ], "filtersMustStayStable": true }, "entrypoints": [ "near.api.v1.accountFull", "near.api.v1.accountFt", "near.api.v1.accountNft", "near.api.v1.accountStaking", "near.api.v1.publicKey", "near.api.v1.publicKeyAll", "near.api.v1.ftTop", "near.ft.inventory", "near.nft.inventory" ] }, { "id": "tx", "summary": "Indexed transaction and receipt lookups for readable execution history by hash, account, or block.", "authStyle": "bearer", "defaultBaseUrls": { "mainnet": "https://tx.main.fastnear.com", "testnet": "https://tx.test.fastnear.com" }, "bestFor": [ "Starting from one transaction hash or receipt id.", "Readable execution stories with receipts already joined in.", "Recent account or block-centered transaction history queries." ], "pagination": { "kind": "resume_token", "requestFields": [ "resume_token" ], "responseFields": [ "resume_token" ], "filtersMustStayStable": true }, "entrypoints": [ "near.tx.transactions", "near.tx.receipt", "near.tx.account", "near.tx.block", "near.tx.blocks" ] }, { "id": "transfers", "summary": "Asset-movement-focused history for accounts when the question is specifically about transfers, not full execution.", "authStyle": "bearer", "defaultBaseUrls": { "mainnet": "https://transfers.main.fastnear.com", "testnet": null }, "bestFor": [ "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." ], "pagination": { "kind": "resume_token", "requestFields": [ "resume_token" ], "responseFields": [ "resume_token" ], "filtersMustStayStable": true }, "entrypoints": [ "near.transfers.query" ] }, { "id": "neardata", "summary": "Block and shard documents for recent chain-state inspection without reconstructing shard layouts yourself.", "authStyle": "query", "defaultBaseUrls": { "mainnet": "https://mainnet.neardata.xyz", "testnet": "https://testnet.neardata.xyz" }, "bestFor": [ "Recent block inspection and shard-aware exploration.", "Questions about network recency or recent transaction volume.", "Walking block-height ranges and chunk layouts." ], "pagination": { "kind": "range", "requestFields": [ "blockHeight", "from_block_height", "to_block_height" ], "responseFields": [], "filtersMustStayStable": false }, "entrypoints": [ "near.neardata.lastBlockFinal", "near.neardata.lastBlockOptimistic", "near.neardata.block", "near.neardata.blockHeaders", "near.neardata.blockShard", "near.neardata.blockChunk", "near.neardata.blockOptimistic", "near.neardata.firstBlock", "near.neardata.health" ] }, { "id": "fastdata.kv", "summary": "Indexed key-value history for exact keys, predecessor scans, and account-scoped storage exploration.", "authStyle": "bearer", "defaultBaseUrls": { "mainnet": "https://kv.main.fastnear.com", "testnet": "https://kv.test.fastnear.com" }, "bestFor": [ "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." ], "pagination": { "kind": "resume_token", "requestFields": [ "resume_token" ], "responseFields": [ "resume_token" ], "filtersMustStayStable": true }, "entrypoints": [ "near.fastdata.kv.getLatestKey", "near.fastdata.kv.getHistoryKey", "near.fastdata.kv.latestByAccount", "near.fastdata.kv.historyByAccount", "near.fastdata.kv.latestByPredecessor", "near.fastdata.kv.historyByPredecessor", "near.fastdata.kv.allByPredecessor", "near.fastdata.kv.multi" ] } ], "runtimes": { "api": { "config": [ "near.config({ networkId })", "near.config({ apiKey })", "near.config({ nodeUrl })" ], "types": [ "FastNearRecipeDiscoveryEntry", "FastNearApiV1AccountFullResponse", "FastNearApiV1AccountFtResponse", "FastNearApiV1AccountNftResponse", "FastNearApiV1AccountStakingResponse", "FastNearApiV1PublicKeyResponse", "FastNearApiV1PublicKeyAllResponse", "FastNearApiV1FtTopResponse", "FastNearTxTransactionsResponse", "FastNearTxReceiptResponse", "FastNearTxAccountResponse", "FastNearTxBlockResponse", "FastNearTxBlocksResponse", "FastNearTransfersQueryResponse", "FastNearNeardataLastBlockFinalResponse", "FastNearNeardataLastBlockOptimisticResponse", "FastNearNeardataBlockResponse", "FastNearNeardataBlockHeadersResponse", "FastNearNeardataBlockShardResponse", "FastNearNeardataBlockChunkResponse", "FastNearNeardataBlockOptimisticResponse", "FastNearNeardataFirstBlockResponse", "FastNearNeardataHealthResponse", "FastNearKvGetLatestKeyResponse", "FastNearKvGetHistoryKeyResponse", "FastNearKvLatestByAccountResponse", "FastNearKvHistoryByAccountResponse", "FastNearKvLatestByPredecessorResponse", "FastNearKvHistoryByPredecessorResponse", "FastNearKvAllByPredecessorResponse", "FastNearKvMultiResponse" ], "recipes": [ "near.recipes.viewContract", "near.recipes.viewAccount", "near.recipes.connect", "near.recipes.functionCall", "near.recipes.transfer", "near.recipes.signMessage", "near.recipes.connect", "near.recipes.functionCall" ], "explain": [ "near.explain.action", "near.explain.tx", "near.explain.error" ], "lowLevel": [ "near.view", "near.queryAccount", "near.queryTx", "near.sendTx", "near.requestSignIn", "near.signMessage", "near.ft.balance", "near.ft.metadata", "near.ft.totalSupply", "near.ft.storageBalance", "near.ft.inventory", "near.nft.metadata", "near.nft.token", "near.nft.forOwner", "near.nft.supplyForOwner", "near.nft.totalSupply", "near.nft.tokens", "near.nft.inventory", "near.api.v1.accountFull", "near.api.v1.accountFt", "near.api.v1.accountNft", "near.api.v1.accountStaking", "near.api.v1.publicKey", "near.api.v1.publicKeyAll", "near.api.v1.ftTop", "near.tx.transactions", "near.tx.receipt", "near.tx.account", "near.tx.block", "near.tx.blocks", "near.transfers.query", "near.neardata.lastBlockFinal", "near.neardata.lastBlockOptimistic", "near.neardata.block", "near.neardata.blockHeaders", "near.neardata.blockShard", "near.neardata.blockChunk", "near.neardata.blockOptimistic", "near.neardata.firstBlock", "near.neardata.health", "near.fastdata.kv.getLatestKey", "near.fastdata.kv.getHistoryKey", "near.fastdata.kv.latestByAccount", "near.fastdata.kv.historyByAccount", "near.fastdata.kv.latestByPredecessor", "near.fastdata.kv.historyByPredecessor", "near.fastdata.kv.allByPredecessor", "near.fastdata.kv.multi" ] } }, "recipes": [ { "id": "view-contract", "title": "What does this contract method return?", "summary": "Start with one view call when you already know the contract, method, and arguments.", "network": "mainnet", "auth": "none", "api": "near.recipes.viewContract", "example": { "contractId": "berryclub.ek.near", "methodName": "get_account", "args": { "account_id": "root.near" } }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst result = await near.recipes.viewContract({\n contractId: \"berryclub.ek.near\",\n methodName: \"get_account\",\n args: { account_id: \"root.near\" },\n});\n\nnear.print({\n account_id: result.account_id,\n avocado_balance: result.avocado_balance,\n num_pixels: result.num_pixels,\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\nARGS_BASE64=\"$(jq -nc --arg account_id \"$ACCOUNT_ID\" '{account_id: $account_id}' | base64 | tr -d '\\n')\"\n\ncurl -sS \"https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg args \"$ARGS_BASE64\" '{\n jsonrpc:\"2.0\",id:\"fastnear\",method:\"query\",\n params:{\n request_type:\"call_function\",\n finality:\"final\",\n account_id:\"berryclub.ek.near\",\n method_name:\"get_account\",\n args_base64:$args\n }\n }')\" | jq '.result.result | implode | fromjson | {account_id, avocado_balance, num_pixels}'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const result = await near.recipes.viewContract({\n contractId: \"berryclub.ek.near\",\n methodName: \"get_account\",\n args: { account_id: \"root.near\" },\n});\n\nnear.print({\n account_id: result.account_id,\n avocado_balance: result.avocado_balance,\n num_pixels: result.num_pixels,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst result = await near.recipes.viewContract({\n contractId: \"berryclub.ek.near\",\n methodName: \"get_account\",\n args: { account_id: \"root.near\" },\n});\n\nnear.print({\n account_id: result.account_id,\n avocado_balance: result.avocado_balance,\n num_pixels: result.num_pixels,\n});" } ], "service": "rpc", "returns": "BerryClubAccountView", "outputKeys": [ "account_id", "avocado_balance", "num_pixels" ], "responseNotes": [ "This recipe returns the parsed JSON value from the contract method, not the raw RPC wrapper.", "Use the curl + jq variant when you want to inspect the encoded args or the raw RPC envelope." ], "chooseWhen": [ "Choose this when you already know the exact contract method and want the smallest answer quickly.", "Stay on RPC when the question is still about one direct view call rather than indexed history." ], "followUps": [ "If the method output looks wrong, compare it with the canonical account state from near.recipes.viewAccount.", "If you need a broader ownership snapshot, move to near.api.v1.accountFull." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "view-account", "account-full" ] }, { "id": "view-account", "title": "What does this account look like on chain?", "summary": "Use canonical RPC account state when the question is still about one account record.", "network": "mainnet", "auth": "none", "api": "near.recipes.viewAccount", "example": { "accountId": "root.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst account = await near.recipes.viewAccount(\"root.near\");\n\nconst { amount, locked, storage_usage, block_height, block_hash } = account;\n\nnear.print({\n amount,\n locked,\n storage_usage,\n block_height,\n block_hash,\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\n\ncurl -sS \"https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg account_id \"$ACCOUNT_ID\" '{\n jsonrpc:\"2.0\",id:\"fastnear\",method:\"query\",\n params:{request_type:\"view_account\",account_id:$account_id,finality:\"final\"}\n }')\" | jq '.result | {amount, locked, storage_usage, block_height, block_hash}'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const account = await near.recipes.viewAccount(\"root.near\");\n\nconst { amount, locked, storage_usage, block_height, block_hash } = account;\n\nnear.print({\n amount,\n locked,\n storage_usage,\n block_height,\n block_hash,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst account = await near.recipes.viewAccount(\"root.near\");\n\nconst { amount, locked, storage_usage, block_height, block_hash } = account;\n\nnear.print({\n amount,\n locked,\n storage_usage,\n block_height,\n block_hash,\n});" } ], "service": "rpc", "returns": "RpcViewAccountResponse", "outputKeys": [ "amount", "locked", "storage_usage", "block_height", "block_hash" ], "responseNotes": [ "This is the canonical on-chain account record from JSON-RPC.", "The snippet keeps the object work in JS and emits only the fields most useful for survey scripting." ], "chooseWhen": [ "Choose this when the question is about one account's chain state rather than token holdings or transfers.", "Use this before reaching for aggregations if you need the raw account state answer first." ], "followUps": [ "If the account is active but you need holdings, switch to near.api.v1.accountFull.", "If you need recent transfer activity, continue with near.transfers.query." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "account-full", "transfers-query" ] }, { "id": "inspect-transaction", "title": "What happened in this transaction?", "summary": "Start with the indexed transaction family when all you have is the hash and you want the readable story.", "network": "mainnet", "auth": "none", "api": "near.tx.transactions", "example": { "txHashes": [ "7ZKnhzt2MqMNmsk13dV8GAjGu3Db8aHzSBHeNeu9MJCq" ] }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst tx = await near.recipes.inspectTransaction(\n \"7ZKnhzt2MqMNmsk13dV8GAjGu3Db8aHzSBHeNeu9MJCq\"\n);\n\nnear.print(\n tx\n ? {\n hash: tx.transaction.hash,\n signer_id: tx.transaction.signer_id,\n receiver_id: tx.transaction.receiver_id,\n included_block_height: tx.execution_outcome.block_height,\n receipt_count: tx.receipts.length,\n }\n : null\n);\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nTX_HASH=7ZKnhzt2MqMNmsk13dV8GAjGu3Db8aHzSBHeNeu9MJCq\n\ncurl -sS \"https://tx.main.fastnear.com/v0/transactions\" -H \"Authorization: Bearer $FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg tx_hash \"$TX_HASH\" '{tx_hashes: [$tx_hash]}')\" | jq '{\n hash: .transactions[0].transaction.hash,\n signer_id: .transactions[0].transaction.signer_id,\n receiver_id: .transactions[0].transaction.receiver_id,\n included_block_height: .transactions[0].execution_outcome.block_height,\n receipt_count: (.transactions[0].receipts | length)\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const tx = await near.recipes.inspectTransaction(\n \"7ZKnhzt2MqMNmsk13dV8GAjGu3Db8aHzSBHeNeu9MJCq\"\n);\n\nnear.print(\n tx\n ? {\n hash: tx.transaction.hash,\n signer_id: tx.transaction.signer_id,\n receiver_id: tx.transaction.receiver_id,\n included_block_height: tx.execution_outcome.block_height,\n receipt_count: tx.receipts.length,\n }\n : null\n);" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst tx = await near.recipes.inspectTransaction(\n \"7ZKnhzt2MqMNmsk13dV8GAjGu3Db8aHzSBHeNeu9MJCq\"\n);\n\nnear.print(\n tx\n ? {\n hash: tx.transaction.hash,\n signer_id: tx.transaction.signer_id,\n receiver_id: tx.transaction.receiver_id,\n included_block_height: tx.execution_outcome.block_height,\n receipt_count: tx.receipts.length,\n }\n : null\n);" } ], "service": "tx", "returns": "FastNearTxTransactionsResponse", "outputKeys": [ "transactions[].transaction.hash", "transactions[].transaction.signer_id", "transactions[].transaction.receiver_id", "transactions[].execution_outcome.block_height", "transactions[].receipts" ], "responseNotes": [ "The low-level tx family returns raw indexed JSON with receipts already attached.", "This recipe narrows that response to the one transaction row and prints a compact human-readable summary." ], "chooseWhen": [ "Choose this when the only durable identifier you have is the transaction hash.", "Prefer this over transfers when you need the execution story, receipts, or included block details." ], "followUps": [ "If you care only about asset movement, pivot to near.transfers.query.", "If you need a block-centered history scan, continue with near.tx.account or near.tx.blocks." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "transfers-query", "last-block-final" ] }, { "id": "account-full", "title": "What does this account own?", "summary": "Use the FastNear account aggregator when the question is about holdings, NFTs, or staking in one response.", "network": "mainnet", "auth": "none", "api": "near.api.v1.accountFull", "example": { "accountId": "root.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst account = await near.api.v1.accountFull({\n accountId: \"root.near\",\n});\n\nnear.print({\n account_id: account.account_id,\n near_balance_yocto: account.state.balance,\n ft_contracts: account.tokens.length,\n nft_contracts: account.nfts.length,\n staking_pool_contracts: account.pools.length,\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\n\ncurl -sS \"https://api.fastnear.com/v1/account/$ACCOUNT_ID/full\" -H \"Authorization: Bearer $FASTNEAR_API_KEY\" | jq '{\n account_id,\n near_balance_yocto: .state.balance,\n ft_contracts: (.tokens | length),\n nft_contracts: (.nfts | length),\n staking_pool_contracts: (.pools | length)\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const account = await near.api.v1.accountFull({\n accountId: \"root.near\",\n});\n\nnear.print({\n account_id: account.account_id,\n near_balance_yocto: account.state.balance,\n ft_contracts: account.tokens.length,\n nft_contracts: account.nfts.length,\n staking_pool_contracts: account.pools.length,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst account = await near.api.v1.accountFull({\n accountId: \"root.near\",\n});\n\nnear.print({\n account_id: account.account_id,\n near_balance_yocto: account.state.balance,\n ft_contracts: account.tokens.length,\n nft_contracts: account.nfts.length,\n staking_pool_contracts: account.pools.length,\n});" } ], "service": "api", "returns": "FastNearApiV1AccountFullResponse", "outputKeys": [ "account_id", "state.balance", "tokens", "nfts", "pools" ], "responseNotes": [ "This is the aggregated account surface for holdings and staking, not a raw RPC account object.", "It is the best one-response answer when the task is portfolio-style discovery." ], "chooseWhen": [ "Choose this when you want holdings, NFTs, and staking without stitching multiple calls together.", "Use it after a canonical RPC account check when the next question becomes 'what does this account own?'." ], "followUps": [ "If you need movement history instead of holdings, continue with near.transfers.query.", "If you need one exact contract state read, go back to near.recipes.viewContract." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "view-account", "transfers-query" ] }, { "id": "transfers-query", "title": "What is this account's recent transfer activity?", "summary": "Use the transfers family when the question is specifically about asset movement, not the broader execution story.", "network": "mainnet", "auth": "none", "api": "near.transfers.query", "example": { "accountId": "root.near", "desc": true, "limit": 5 }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst feed = await near.transfers.query({\n accountId: \"root.near\",\n desc: true,\n limit: 5,\n});\n\nnear.print({\n recent: (feed.transfers || []).map((entry) => ({\n block_height: entry.block_height,\n asset_id: entry.asset_id,\n human_amount: entry.human_amount,\n other_account_id: entry.other_account_id,\n transfer_type: entry.transfer_type,\n tx: entry.transaction_id,\n })),\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\n\ncurl -sS \"https://transfers.main.fastnear.com/v0/transfers\" -H \"Authorization: Bearer $FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg account_id \"$ACCOUNT_ID\" '{account_id: $account_id, desc: true, limit: 5}')\" | jq '{\n recent: [.transfers[] | {\n block_height,\n asset_id,\n human_amount,\n other_account_id,\n transfer_type,\n tx: .transaction_id\n }]\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const feed = await near.transfers.query({\n accountId: \"root.near\",\n desc: true,\n limit: 5,\n});\n\nnear.print({\n recent: (feed.transfers || []).map((entry) => ({\n block_height: entry.block_height,\n asset_id: entry.asset_id,\n human_amount: entry.human_amount,\n other_account_id: entry.other_account_id,\n transfer_type: entry.transfer_type,\n tx: entry.transaction_id,\n })),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst feed = await near.transfers.query({\n accountId: \"root.near\",\n desc: true,\n limit: 5,\n});\n\nnear.print({\n recent: (feed.transfers || []).map((entry) => ({\n block_height: entry.block_height,\n asset_id: entry.asset_id,\n human_amount: entry.human_amount,\n other_account_id: entry.other_account_id,\n transfer_type: entry.transfer_type,\n tx: entry.transaction_id,\n })),\n});" } ], "service": "transfers", "returns": "FastNearTransfersQueryResponse", "outputKeys": [ "transfers[].block_height", "transfers[].asset_id", "transfers[].human_amount", "transfers[].other_account_id", "transfers[].transaction_id", "resume_token" ], "responseNotes": [ "Transfers answers the asset-movement question directly and returns raw rows plus resume-token pagination when available.", "It is intentionally narrower than the tx family and better suited to feed-style scripting." ], "chooseWhen": [ "Choose this when the question is about who sent what asset and when.", "Prefer this over near.tx when you do not need receipt details or execution outcomes." ], "followUps": [ "If one transfer row needs a deeper execution story, pivot to near.tx.transactions with the related hash.", "If you need holdings instead of movement, switch to near.api.v1.accountFull." ], "pagination": { "kind": "resume_token", "requestFields": [ "resume_token" ], "responseFields": [ "resume_token" ], "filtersMustStayStable": true }, "relatedRecipes": [ "inspect-transaction", "account-full" ] }, { "id": "last-block-final", "title": "What block is NEAR on right now?", "summary": "Use the NEAR Data family when you want a recent block document without stitching shards together yourself.", "network": "mainnet", "auth": "none", "api": "near.neardata.lastBlockFinal", "example": {}, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst block = await near.neardata.lastBlockFinal();\n\nnear.print({\n height: block.block.header.height,\n timestamp_nanosec: block.block.header.timestamp_nanosec,\n txs_per_shard: block.shards.map((shard) => ({\n shard_id: shard.shard_id,\n tx_count: shard.chunk.transactions.length,\n })),\n total_txs: block.shards.reduce(\n (count, shard) => count + shard.chunk.transactions.length,\n 0\n ),\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\ncurl -sSL \"https://mainnet.neardata.xyz/v0/last_block/final?apiKey=$FASTNEAR_API_KEY\" | jq '{\n height: .block.header.height,\n timestamp_nanosec: .block.header.timestamp_nanosec,\n txs_per_shard: [.shards[] | {shard_id, tx_count: (.chunk.transactions | length)}],\n total_txs: ([.shards[].chunk.transactions[]?] | length)\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const block = await near.neardata.lastBlockFinal();\n\nnear.print({\n height: block.block.header.height,\n timestamp_nanosec: block.block.header.timestamp_nanosec,\n txs_per_shard: block.shards.map((shard) => ({\n shard_id: shard.shard_id,\n tx_count: shard.chunk.transactions.length,\n })),\n total_txs: block.shards.reduce(\n (count, shard) => count + shard.chunk.transactions.length,\n 0\n ),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst block = await near.neardata.lastBlockFinal();\n\nnear.print({\n height: block.block.header.height,\n timestamp_nanosec: block.block.header.timestamp_nanosec,\n txs_per_shard: block.shards.map((shard) => ({\n shard_id: shard.shard_id,\n tx_count: shard.chunk.transactions.length,\n })),\n total_txs: block.shards.reduce(\n (count, shard) => count + shard.chunk.transactions.length,\n 0\n ),\n});" } ], "service": "neardata", "returns": "FastNearNeardataLastBlockFinalResponse", "outputKeys": [ "block.header.height", "block.header.timestamp_nanosec", "shards[].shard_id", "shards[].chunk.transactions" ], "responseNotes": [ "NEAR Data returns block documents with shard content already grouped for block-level inspection.", "This recipe highlights the smallest useful block recency summary while keeping the full response available in JS." ], "chooseWhen": [ "Choose this when the question starts with recent block recency or transaction volume.", "Use the family-level block endpoints when you want to walk heights or inspect one shard or chunk next." ], "followUps": [ "If one transaction in the block matters, continue with near.tx.transactions.", "If you need a specific historical block, move to near.neardata.block or near.neardata.blockChunk." ], "pagination": { "kind": "range", "requestFields": [ "blockHeight", "from_block_height", "to_block_height" ], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "inspect-transaction" ] }, { "id": "kv-latest-key", "title": "What is the latest indexed value for this exact key?", "summary": "Start narrow with KV FastData when you already know the contract, predecessor, and exact storage key.", "network": "mainnet", "auth": "none", "api": "near.fastdata.kv.getLatestKey", "example": { "currentAccountId": "social.near", "predecessorId": "james.near", "key": "graph/follow/sleet.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst result = await near.fastdata.kv.getLatestKey({\n currentAccountId: \"social.near\",\n predecessorId: \"james.near\",\n key: \"graph/follow/sleet.near\",\n});\n\nconst latest = result.entries?.[0] || null;\n\nnear.print({\n latest: latest\n ? {\n current_account_id: latest.current_account_id,\n predecessor_id: latest.predecessor_id,\n block_height: latest.block_height,\n key: latest.key,\n value: latest.value,\n }\n : null,\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nCURRENT_ACCOUNT_ID=social.near\nPREDECESSOR_ID=james.near\nKEY='graph/follow/sleet.near'\n\nENCODED_KEY=\"$(jq -rn --arg key \"$KEY\" '$key | @uri')\"\n\ncurl -sS \"https://kv.main.fastnear.com/v0/latest/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY\" -H \"Authorization: Bearer $FASTNEAR_API_KEY\" | jq '{\n latest: (\n .entries[0]\n | {\n current_account_id,\n predecessor_id,\n block_height,\n key,\n value\n }\n )\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const result = await near.fastdata.kv.getLatestKey({\n currentAccountId: \"social.near\",\n predecessorId: \"james.near\",\n key: \"graph/follow/sleet.near\",\n});\n\nconst latest = result.entries?.[0] || null;\n\nnear.print({\n latest: latest\n ? {\n current_account_id: latest.current_account_id,\n predecessor_id: latest.predecessor_id,\n block_height: latest.block_height,\n key: latest.key,\n value: latest.value,\n }\n : null,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst result = await near.fastdata.kv.getLatestKey({\n currentAccountId: \"social.near\",\n predecessorId: \"james.near\",\n key: \"graph/follow/sleet.near\",\n});\n\nconst latest = result.entries?.[0] || null;\n\nnear.print({\n latest: latest\n ? {\n current_account_id: latest.current_account_id,\n predecessor_id: latest.predecessor_id,\n block_height: latest.block_height,\n key: latest.key,\n value: latest.value,\n }\n : null,\n});" } ], "service": "fastdata.kv", "returns": "FastNearKvGetLatestKeyResponse", "outputKeys": [ "entries[].current_account_id", "entries[].predecessor_id", "entries[].block_height", "entries[].key", "entries[].value" ], "responseNotes": [ "KV FastData keeps the exact indexed storage history question narrow and fast when you already know the key.", "The raw response keeps the full entry list; the example snippet extracts the most informative first entry." ], "chooseWhen": [ "Choose this when you already know the exact key and want the latest indexed value immediately.", "Use the broader history or predecessor scans only after this exact-key lookup stops being enough." ], "followUps": [ "If you need history for the same key, continue with near.fastdata.kv.getHistoryKey.", "If you only know the predecessor and need discovery, continue with near.fastdata.kv.allByPredecessor." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "view-contract" ] }, { "id": "connect-wallet", "title": "How do I connect a wallet?", "summary": "Open the wallet picker and attach a signer to the FastNear runtime.", "network": "mainnet", "auth": "wallet", "api": "near.recipes.connect", "example": { "contractId": "berryclub.ek.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Opening the wallet picker needs a browser environment.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const result = await near.recipes.connect({\n contractId: \"berryclub.ek.near\",\n});\n\nnear.print(result ?? near.selected());" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\nconst result = await near.recipes.connect({\n contractId: \"berryclub.ek.near\",\n});\n\nnear.print(result ?? near.selected());" } ], "service": "wallet", "returns": "{ accountId: string } | undefined", "outputKeys": [ "accountId" ], "responseNotes": [ "Wallet-backed recipes are browser-first because they need an interactive signer.", "This recipe is the smallest explicit connect step before sending transactions or signing messages." ], "chooseWhen": [ "Choose this when the task crosses from read-only inspection into user-approved signing.", "Use it once per browser session before function calls, transfers, or message signatures." ], "followUps": [ "After connecting, send one contract action with near.recipes.functionCall.", "If the next step is a simple NEAR payment, continue with near.recipes.transfer." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "function-call", "transfer", "sign-message", "sign-delegate-actions" ] }, { "id": "function-call", "title": "How do I send one function call?", "summary": "Sign and broadcast a single contract call with readable gas units.", "network": "mainnet", "auth": "wallet", "api": "near.recipes.functionCall", "example": { "receiverId": "berryclub.ek.near", "methodName": "draw", "args": { "pixels": [ { "x": 10, "y": 20, "color": 65280 } ] }, "gas": "100 Tgas", "deposit": "0" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Signing and broadcasting a contract call needs a wallet session.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const cu = near.utils.convertUnit;\n\nconst result = await near.recipes.functionCall({\n receiverId: \"berryclub.ek.near\",\n methodName: \"draw\",\n args: {\n pixels: [{ x: 10, y: 20, color: 65280 }],\n },\n gas: cu(\"100 Tgas\"),\n deposit: \"0\",\n});\n\nnear.print(result);" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\nconst cu = near.utils.convertUnit;\n\nconst result = await near.recipes.functionCall({\n receiverId: \"berryclub.ek.near\",\n methodName: \"draw\",\n args: {\n pixels: [{ x: 10, y: 20, color: 65280 }],\n },\n gas: cu(\"100 Tgas\"),\n deposit: \"0\",\n});\n\nnear.print(result);" } ], "service": "wallet", "returns": "WalletTransactionResult", "outputKeys": [ "transaction", "outcomes", "status" ], "responseNotes": [ "This is the thinnest wallet-backed transaction recipe and keeps the action declaration explicit.", "The example uses readable unit conversion before handing the transaction to the runtime." ], "chooseWhen": [ "Choose this when you need one contract call and already know the receiver, method, and args.", "Prefer this recipe over the lower-level sendTx path when you want the smallest wallet-backed API surface." ], "followUps": [ "If the user only needs a native NEAR transfer, continue with near.recipes.transfer.", "If you want to preview the action before signing, use near.explain.tx on the same action list." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "connect-wallet", "transfer", "sign-message" ] }, { "id": "transfer", "title": "How do I transfer NEAR?", "summary": "Send a simple NEAR transfer with a wallet-backed signature.", "network": "mainnet", "auth": "wallet+deposit", "api": "near.recipes.transfer", "example": { "receiverId": "escrow.ai.near", "amount": "0.1 NEAR" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Sending NEAR needs a wallet-backed signature flow.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const cu = near.utils.convertUnit;\n\nconst result = await near.recipes.transfer({\n receiverId: \"escrow.ai.near\",\n amount: cu(\"0.1 NEAR\"),\n});\n\nnear.print(result);" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\nconst cu = near.utils.convertUnit;\n\nconst result = await near.recipes.transfer({\n receiverId: \"escrow.ai.near\",\n amount: cu(\"0.1 NEAR\"),\n});\n\nnear.print(result);" } ], "service": "wallet", "returns": "WalletTransactionResult", "outputKeys": [ "transaction", "outcomes", "status" ], "responseNotes": [ "This recipe keeps a simple NEAR transfer readable without constructing the action list manually.", "The transaction still goes through the same wallet-backed approval flow as other signing tasks." ], "chooseWhen": [ "Choose this when the task is a plain NEAR payment and not a contract method call.", "Use the function-call recipe instead when the receiver expects method args or custom gas settings." ], "followUps": [ "If you want to explain the transfer before sending it, use near.explain.tx with a Transfer action.", "If the next task is another signed action, keep the same wallet session and continue with near.recipes.functionCall." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "connect-wallet", "function-call" ] }, { "id": "sign-message", "title": "How do I sign a message?", "summary": "Request a wallet-backed NEP-413 signature for an app message.", "network": "mainnet", "auth": "wallet", "api": "near.recipes.signMessage", "example": { "message": "Sign in to FastNear Berry Club" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Message signing depends on a connected wallet provider.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const result = await near.recipes.signMessage({\n message: \"Sign in to FastNear Berry Club\",\n recipient: window.location.host,\n nonce: crypto.getRandomValues(new Uint8Array(32)),\n});\n\nnear.print(result);" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\nconst result = await near.recipes.signMessage({\n message: \"Sign in to FastNear Berry Club\",\n recipient: window.location.host,\n nonce: crypto.getRandomValues(new Uint8Array(32)),\n});\n\nnear.print(result);" } ], "service": "wallet", "returns": "WalletMessageSignatureResult", "outputKeys": [ "signature", "accountId", "publicKey" ], "responseNotes": [ "This is the wallet-backed message-signing path for NEP-413 style app messages.", "It stays separate from transaction recipes because no chain write is involved." ], "chooseWhen": [ "Choose this when you need user-approved application auth without broadcasting a transaction.", "Prefer this over functionCall or transfer when the task is strictly off-chain signing." ], "followUps": [ "If you need to connect the wallet first, start with near.recipes.connect.", "If the flow turns into an on-chain action, move to near.recipes.functionCall or near.recipes.transfer." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "connect-wallet", "sign-delegate-actions" ] }, { "id": "sign-delegate-actions", "title": "How do I sign delegate actions for gasless transactions?", "summary": "Sign NEP-366 delegate actions via the connected wallet so a relayer can submit them on-chain without the user paying gas.", "network": "mainnet", "auth": "wallet", "api": "nearWallet.signDelegateActions", "example": { "delegateActions": [ { "receiverId": "berryclub.ek.near", "actions": [ { "type": "FunctionCall", "methodName": "draw", "args": { "pixels": [ { "x": 10, "y": 20, "color": 65280 } ] }, "gas": "100 Tgas", "deposit": "0" } ] } ] }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Signing delegate actions depends on a connected wallet provider.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const cu = near.utils.convertUnit;\n\nconst result = await nearWallet.signDelegateActions({\n delegateActions: [\n {\n receiverId: \"berryclub.ek.near\",\n actions: [\n {\n type: \"FunctionCall\",\n methodName: \"draw\",\n args: { pixels: [{ x: 10, y: 20, color: 65280 }] },\n gas: cu(\"100 Tgas\"),\n deposit: \"0\",\n },\n ],\n },\n ],\n});\n\nnear.print({\n count: result.signedDelegateActions.length,\n first_delegate_hash: result.signedDelegateActions[0]?.delegateHash,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\nconst cu = near.utils.convertUnit;\n\nconst result = await nearWallet.signDelegateActions({\n delegateActions: [\n {\n receiverId: \"berryclub.ek.near\",\n actions: [\n {\n type: \"FunctionCall\",\n methodName: \"draw\",\n args: { pixels: [{ x: 10, y: 20, color: 65280 }] },\n gas: cu(\"100 Tgas\"),\n deposit: \"0\",\n },\n ],\n },\n ],\n});\n\nnear.print({\n count: result.signedDelegateActions.length,\n first_delegate_hash: result.signedDelegateActions[0]?.delegateHash,\n});" } ], "service": "wallet", "returns": "SignDelegateActionsResponse", "outputKeys": [ "signedDelegateActions[].delegateHash", "signedDelegateActions[].signedDelegate" ], "responseNotes": [ "Returns signed delegate actions that a relayer can submit on-chain, enabling gasless transactions for the user.", "The wallet must support the signDelegateActions feature (check WalletFeatures.signDelegateActions)." ], "chooseWhen": [ "Choose this when building gasless or relay-based flows where a third party submits the transaction on the user's behalf.", "Prefer sign-message when you only need an off-chain signature, or function-call when the user can pay gas directly." ], "followUps": [ "Submit the signed delegate actions through a relayer service to execute on-chain without the signer paying gas.", "If the flow does not need a relayer, use near.recipes.functionCall for a standard wallet-signed transaction instead." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "connect-wallet", "sign-message", "function-call" ] }, { "id": "ft-balance", "title": "What is this account's FT balance?", "summary": "Read a NEP-141 token balance with a one-line wrapper that fills in the standard method name.", "network": "mainnet", "auth": "none", "api": "near.ft.balance", "example": { "contractId": "berryclub.ek.near", "accountId": "root.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst balance = await near.ft.balance({\n contractId: \"berryclub.ek.near\",\n accountId: \"root.near\",\n});\n\nconst meta = await near.ft.metadata({ contractId: \"berryclub.ek.near\" });\n\nnear.print({\n raw_balance: balance,\n symbol: meta.symbol,\n decimals: meta.decimals,\n human_amount: (Number(balance) / 10 ** meta.decimals).toFixed(meta.decimals),\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\nARGS_BASE64=\"$(jq -nc --arg account_id \"$ACCOUNT_ID\" '{account_id: $account_id}' | base64 | tr -d '\\n')\"\n\ncurl -sS \"https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg args \"$ARGS_BASE64\" '{\n jsonrpc:\"2.0\",id:\"fastnear\",method:\"query\",\n params:{\n request_type:\"call_function\",\n finality:\"final\",\n account_id:\"berryclub.ek.near\",\n method_name:\"ft_balance_of\",\n args_base64:$args\n }\n }')\" | jq -r '.result.result | implode'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const balance = await near.ft.balance({\n contractId: \"berryclub.ek.near\",\n accountId: \"root.near\",\n});\n\nconst meta = await near.ft.metadata({ contractId: \"berryclub.ek.near\" });\n\nnear.print({\n raw_balance: balance,\n symbol: meta.symbol,\n decimals: meta.decimals,\n human_amount: (Number(balance) / 10 ** meta.decimals).toFixed(meta.decimals),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst balance = await near.ft.balance({\n contractId: \"berryclub.ek.near\",\n accountId: \"root.near\",\n});\n\nconst meta = await near.ft.metadata({ contractId: \"berryclub.ek.near\" });\n\nnear.print({\n raw_balance: balance,\n symbol: meta.symbol,\n decimals: meta.decimals,\n human_amount: (Number(balance) / 10 ** meta.decimals).toFixed(meta.decimals),\n});" } ], "service": "rpc", "returns": "string", "outputKeys": [ "raw_balance", "symbol", "decimals", "human_amount" ], "responseNotes": [ "near.ft.balance returns the raw integer balance string from ft_balance_of, scaled by the token's decimals.", "Pair with near.ft.metadata to format the human-readable amount in one shot." ], "chooseWhen": [ "Choose this when you already know the FT contract and want one account's balance.", "Use ft-inventory instead when you need every FT balance an account holds." ], "followUps": [ "If you need every token the account holds, switch to near.ft.inventory.", "If you need a historical balance, add useArchival: true and a blockId — see archival-snapshot." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "ft-metadata", "ft-inventory", "archival-snapshot" ] }, { "id": "ft-metadata", "title": "What does this NEP-141 token call itself?", "summary": "Fetch name, symbol, decimals, and icon for a fungible token in one call.", "network": "mainnet", "auth": "none", "api": "near.ft.metadata", "example": { "contractId": "berryclub.ek.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst meta = await near.ft.metadata({\n contractId: \"berryclub.ek.near\",\n});\n\nnear.print({\n name: meta.name,\n symbol: meta.symbol,\n decimals: meta.decimals,\n icon_present: !!meta.icon,\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nEMPTY_ARGS_BASE64=\"$(printf '{}' | base64)\"\n\ncurl -sS \"https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg args \"$EMPTY_ARGS_BASE64\" '{\n jsonrpc:\"2.0\",id:\"fastnear\",method:\"query\",\n params:{\n request_type:\"call_function\",\n finality:\"final\",\n account_id:\"berryclub.ek.near\",\n method_name:\"ft_metadata\",\n args_base64:$args\n }\n }')\" | jq '.result.result | implode | fromjson | {name, symbol, decimals}'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const meta = await near.ft.metadata({\n contractId: \"berryclub.ek.near\",\n});\n\nnear.print({\n name: meta.name,\n symbol: meta.symbol,\n decimals: meta.decimals,\n icon_present: !!meta.icon,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst meta = await near.ft.metadata({\n contractId: \"berryclub.ek.near\",\n});\n\nnear.print({\n name: meta.name,\n symbol: meta.symbol,\n decimals: meta.decimals,\n icon_present: !!meta.icon,\n});" } ], "service": "rpc", "returns": "{ name: string; symbol: string; decimals: number; icon?: string; reference?: string; reference_hash?: string }", "outputKeys": [ "name", "symbol", "decimals", "icon" ], "responseNotes": [ "Wraps the standard NEP-141 ft_metadata view call so the method name does not have to be remembered.", "Decimals comes back as a number; multiply or divide raw balances accordingly." ], "chooseWhen": [ "Choose this when you need to format a balance, label a token, or display branding.", "Pair with ft-balance whenever you also need a human-readable amount." ], "followUps": [ "If you also need an account balance, continue with near.ft.balance.", "If you want a portfolio view across all tokens, use near.ft.inventory." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "ft-balance", "ft-inventory" ] }, { "id": "ft-inventory", "title": "Which fungible tokens does this account hold?", "summary": "List every NEP-141 contract the account holds via the FastNear indexer in one call.", "network": "mainnet", "auth": "bearer", "api": "near.ft.inventory", "example": { "accountId": "root.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\n// Tip: `near.config({ apiKey: \"\" })` raises rate limits.\nconst inventory = await near.ft.inventory({\n accountId: \"root.near\",\n});\n\nnear.print({\n ft_contract_count: inventory.tokens.length,\n preview: inventory.tokens.slice(0, 5).map((entry) => ({\n contract_id: entry.contract_id,\n balance: entry.balance,\n })),\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\n\ncurl -sS \"https://api.fastnear.com/v1/account/$ACCOUNT_ID/ft\" -H \"Authorization: Bearer $FASTNEAR_API_KEY\" | jq '{\n ft_contract_count: (.tokens | length),\n preview: [.tokens[0:5][] | {contract_id, balance}]\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "// Tip: `near.config({ apiKey: \"\" })` raises rate limits.\nconst inventory = await near.ft.inventory({\n accountId: \"root.near\",\n});\n\nnear.print({\n ft_contract_count: inventory.tokens.length,\n preview: inventory.tokens.slice(0, 5).map((entry) => ({\n contract_id: entry.contract_id,\n balance: entry.balance,\n })),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\n// Tip: `near.config({ apiKey: \"\" })` raises rate limits.\nconst inventory = await near.ft.inventory({\n accountId: \"root.near\",\n});\n\nnear.print({\n ft_contract_count: inventory.tokens.length,\n preview: inventory.tokens.slice(0, 5).map((entry) => ({\n contract_id: entry.contract_id,\n balance: entry.balance,\n })),\n});" } ], "service": "api", "returns": "{ tokens: Array<{ contract_id: string; balance: string; last_update_block_height?: number }> }", "outputKeys": [ "ft_contract_count", "preview[].contract_id", "preview[].balance" ], "responseNotes": [ "near.ft.inventory hits the FastNear indexer (api.fastnear.com) — set near.config({ apiKey }) to avoid the public rate limit.", "Returns one row per FT contract the account currently holds; balances are raw integer strings." ], "chooseWhen": [ "Choose this when the question is 'what tokens does this account own?' rather than one specific contract.", "Use ft-balance instead when you already know the contract id." ], "followUps": [ "If you need NFTs as well, switch to near.nft.inventory.", "If you need staking and aggregate state too, use near.api.v1.accountFull." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "ft-balance", "nft-inventory", "account-full" ] }, { "id": "nft-for-owner", "title": "Which NFTs does this account own on this contract?", "summary": "List the tokens an account owns under one NEP-171 contract with metadata included.", "network": "mainnet", "auth": "none", "api": "near.nft.forOwner", "example": { "contractId": "x.paras.near", "accountId": "root.near", "limit": 5 }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\nconst tokens = await near.nft.forOwner({\n contractId: \"x.paras.near\",\n accountId: \"root.near\",\n limit: 5,\n});\n\nnear.print({\n count: tokens.length,\n preview: tokens.map((token) => ({\n token_id: token.token_id,\n title: token.metadata?.title,\n })),\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\nARGS_BASE64=\"$(jq -nc --arg account_id \"$ACCOUNT_ID\" '{account_id: $account_id, limit: 5}' | base64 | tr -d '\\n')\"\n\ncurl -sS \"https://rpc.mainnet.fastnear.com?apiKey=$FASTNEAR_API_KEY\" -H 'content-type: application/json' --data \"$(jq -nc --arg args \"$ARGS_BASE64\" '{\n jsonrpc:\"2.0\",id:\"fastnear\",method:\"query\",\n params:{\n request_type:\"call_function\",\n finality:\"final\",\n account_id:\"x.paras.near\",\n method_name:\"nft_tokens_for_owner\",\n args_base64:$args\n }\n }')\" | jq '.result.result | implode | fromjson | [.[] | {token_id, title: .metadata.title}]'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "const tokens = await near.nft.forOwner({\n contractId: \"x.paras.near\",\n accountId: \"root.near\",\n limit: 5,\n});\n\nnear.print({\n count: tokens.length,\n preview: tokens.map((token) => ({\n token_id: token.token_id,\n title: token.metadata?.title,\n })),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\nconst tokens = await near.nft.forOwner({\n contractId: \"x.paras.near\",\n accountId: \"root.near\",\n limit: 5,\n});\n\nnear.print({\n count: tokens.length,\n preview: tokens.map((token) => ({\n token_id: token.token_id,\n title: token.metadata?.title,\n })),\n});" } ], "service": "rpc", "returns": "Array<{ token_id: string; owner_id: string; metadata?: { title?: string; media?: string; description?: string } }>", "outputKeys": [ "count", "preview[].token_id", "preview[].title" ], "responseNotes": [ "Wraps NEP-171 nft_tokens_for_owner; the contract decides what metadata fields to embed.", "Pass from_index and limit (numbers, sometimes strings depending on the contract) for pagination." ], "chooseWhen": [ "Choose this when you already know the NFT contract and want one account's collection on it.", "Use nft-inventory instead when you want NFTs across every contract for an account." ], "followUps": [ "If you need contract-level metadata, call near.nft.metadata.", "If you need cross-contract NFT discovery, switch to near.nft.inventory." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "nft-inventory" ] }, { "id": "nft-inventory", "title": "Which NFT contracts does this account hold tokens on?", "summary": "Discover every NEP-171 contract the account holds tokens under via the FastNear indexer.", "network": "mainnet", "auth": "bearer", "api": "near.nft.inventory", "example": { "accountId": "root.near" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\n// Tip: `near.config({ apiKey: \"\" })` raises rate limits.\nconst inventory = await near.nft.inventory({\n accountId: \"root.near\",\n});\n\nnear.print({\n contract_count: inventory.tokens.length,\n total_tokens: inventory.tokens.reduce(\n (sum, c) => sum + (c.tokens?.length ?? 0),\n 0\n ),\n preview: inventory.tokens.slice(0, 3).map((entry) => ({\n contract_id: entry.contract_id,\n sample_token_ids: (entry.tokens || []).slice(0, 3).map((t) => t.token_id),\n })),\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nACCOUNT_ID=root.near\n\ncurl -sS \"https://api.fastnear.com/v1/account/$ACCOUNT_ID/nft\" -H \"Authorization: Bearer $FASTNEAR_API_KEY\" | jq '{\n contract_count: (.tokens | length),\n preview: [.tokens[0:3][] | {contract_id, token_count: (.tokens // [] | length)}]\n }'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "// Tip: `near.config({ apiKey: \"\" })` raises rate limits.\nconst inventory = await near.nft.inventory({\n accountId: \"root.near\",\n});\n\nnear.print({\n contract_count: inventory.tokens.length,\n total_tokens: inventory.tokens.reduce(\n (sum, c) => sum + (c.tokens?.length ?? 0),\n 0\n ),\n preview: inventory.tokens.slice(0, 3).map((entry) => ({\n contract_id: entry.contract_id,\n sample_token_ids: (entry.tokens || []).slice(0, 3).map((t) => t.token_id),\n })),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\n// Tip: `near.config({ apiKey: \"\" })` raises rate limits.\nconst inventory = await near.nft.inventory({\n accountId: \"root.near\",\n});\n\nnear.print({\n contract_count: inventory.tokens.length,\n total_tokens: inventory.tokens.reduce(\n (sum, c) => sum + (c.tokens?.length ?? 0),\n 0\n ),\n preview: inventory.tokens.slice(0, 3).map((entry) => ({\n contract_id: entry.contract_id,\n sample_token_ids: (entry.tokens || []).slice(0, 3).map((t) => t.token_id),\n })),\n});" } ], "service": "api", "returns": "{ tokens: Array<{ contract_id: string; tokens?: Array<{ token_id: string }> }> }", "outputKeys": [ "contract_count", "total_tokens", "preview[].contract_id", "preview[].sample_token_ids" ], "responseNotes": [ "near.nft.inventory hits the FastNear indexer — set near.config({ apiKey }) to avoid the public rate limit.", "One row per NFT contract the account holds; the embedded token list is best-effort and may need follow-up calls for full metadata." ], "chooseWhen": [ "Choose this when the question is 'what NFT contracts does this account hold tokens on?'.", "Use nft-for-owner when you already know the specific contract id." ], "followUps": [ "Drill into one contract with near.nft.forOwner for the per-token details.", "Pull holdings + staking + native NEAR with near.api.v1.accountFull." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "nft-for-owner", "ft-inventory", "account-full" ] }, { "id": "archival-snapshot", "title": "What did this account look like at a specific block?", "summary": "Read canonical account state at a historical block by setting useArchival on the query.", "network": "mainnet", "auth": "none", "api": "near.queryAccount", "example": { "accountId": "root.near", "blockId": 100000000, "useArchival": true }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": true, "code": "# Assumes FASTNEAR_API_KEY is already set in your shell.\nnode -e \"$(curl -fsSL https://js.fastnear.com/agents.js)\" <<'EOF'\n// Reads canonical account state at a specific historical block via the\n// archival RPC. Add useArchival to any view/query when blockId predates\n// the regular RPC's retention window (~5 epochs / a few days).\nconst past = await near.queryAccount({\n accountId: \"root.near\",\n blockId: 100_000_000,\n useArchival: true,\n});\n\nnear.print({\n amount: past.amount,\n storage_usage: past.storage_usage,\n block_hash: past.block_hash,\n block_height: past.block_height,\n});\nEOF" }, { "id": "curl-jq", "label": "curl + jq", "environment": "curl", "language": "bash", "runnable": true, "code": "# NEAR's public archival RPC — no apiKey required.\nACCOUNT_ID=root.near\nBLOCK_ID=100000000\n\ncurl -sS \"https://archival-rpc.mainnet.near.org\" -H 'content-type: application/json' --data \"$(jq -nc --arg account_id \"$ACCOUNT_ID\" --argjson block \"$BLOCK_ID\" '{\n jsonrpc:\"2.0\",id:\"fastnear\",method:\"query\",\n params:{request_type:\"view_account\",account_id:$account_id,block_id:$block}\n }')\" | jq '.result | {amount, storage_usage, block_height, block_hash}'" }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "// Reads canonical account state at a specific historical block via the\n// archival RPC. Add useArchival to any view/query when blockId predates\n// the regular RPC's retention window (~5 epochs / a few days).\nconst past = await near.queryAccount({\n accountId: \"root.near\",\n blockId: 100_000_000,\n useArchival: true,\n});\n\nnear.print({\n amount: past.amount,\n storage_usage: past.storage_usage,\n block_hash: past.block_hash,\n block_height: past.block_height,\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\n\n// Reads canonical account state at a specific historical block via the\n// archival RPC. Add useArchival to any view/query when blockId predates\n// the regular RPC's retention window (~5 epochs / a few days).\nconst past = await near.queryAccount({\n accountId: \"root.near\",\n blockId: 100_000_000,\n useArchival: true,\n});\n\nnear.print({\n amount: past.amount,\n storage_usage: past.storage_usage,\n block_hash: past.block_hash,\n block_height: past.block_height,\n});" } ], "service": "rpc", "returns": "RpcViewAccountResponse", "outputKeys": [ "amount", "storage_usage", "block_hash", "block_height" ], "responseNotes": [ "useArchival: true routes a single call to NEAR's archival RPC (archival-rpc.{mainnet,testnet}.near.org) which retains state past the regular RPC's ~5-epoch window.", "The same flag works on near.view, near.queryAccount, near.queryBlock, near.queryAccessKey, near.queryTx, and the lower-level near.sendRpc — falls back to the regular RPC if archival isn't configured for the network." ], "chooseWhen": [ "Choose this when blockId predates the regular RPC's retention window or you specifically want a historical snapshot.", "Combine with the FT or NFT helpers (`useArchival: true` is forwarded) when you need a historical token balance." ], "followUps": [ "Pair with near.ft.balance({ blockId, useArchival: true }) for a historical token balance.", "If you need a full holdings snapshot at a block, walk near.api.v1.accountFull with the blockId once it's supported on that surface." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "view-account", "ft-balance" ] }, { "id": "connect-testnet", "title": "How do I open a testnet wallet session alongside mainnet?", "summary": "Use the per-network connect parameter to keep mainnet and testnet sessions side by side.", "network": "testnet", "auth": "wallet", "api": "near.recipes.connect", "example": { "network": "testnet", "contractId": "guest-book.testnet" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Opening the wallet picker needs a browser environment.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "// near.recipes.connect honors a per-call network override\n// (@fastnear/api 1.1.1+), so this opens a testnet session alongside any\n// existing mainnet session — wallet state is keyed per network.\nconst result = await near.recipes.connect({\n network: \"testnet\",\n contractId: \"guest-book.testnet\",\n});\n\nnear.print({\n connected: result,\n active_networks: nearWallet.connectedNetworks(),\n});" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\n// near.recipes.connect honors a per-call network override\n// (@fastnear/api 1.1.1+), so this opens a testnet session alongside any\n// existing mainnet session — wallet state is keyed per network.\nconst result = await near.recipes.connect({\n network: \"testnet\",\n contractId: \"guest-book.testnet\",\n});\n\nnear.print({\n connected: result,\n active_networks: nearWallet.connectedNetworks(),\n});" } ], "service": "wallet", "returns": "{ accountId: string; network?: \"mainnet\" | \"testnet\" } | undefined", "outputKeys": [ "connected.accountId", "connected.network", "active_networks" ], "responseNotes": [ "@fastnear/wallet 1.1.0 keys session state per network, so signing in on testnet does not evict an active mainnet session.", "@fastnear/api 1.1.1 added a `network` parameter to near.recipes.connect (and signOut) — earlier versions silently used near.config().networkId.", "nearWallet.connectedNetworks() returns the list of networks with an active session." ], "chooseWhen": [ "Choose this when the task spans both networks in the same page (mainnet read + testnet write, or A/B testing).", "Use connect-wallet when one network at a time is enough." ], "followUps": [ "Send a function call on the testnet contract with near.recipes.functionCall({ network: \"testnet\", … }) — see the function-call-testnet recipe.", "Read the active session per network with nearWallet.accountId({ network: \"testnet\" }) and nearWallet.getActiveNetwork()." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "connect-wallet", "function-call", "function-call-testnet" ] }, { "id": "function-call-testnet", "title": "How do I send a function call on testnet without losing my mainnet session?", "summary": "Pair near.recipes.connect({ network: \"testnet\" }) with near.recipes.functionCall({ network: \"testnet\" }) — connect honors the per-network override added in 1.1.1; functionCall does the same thanks to per-network account state in 1.1.2.", "network": "testnet", "auth": "wallet", "api": "near.recipes.functionCall", "example": { "network": "testnet", "receiverId": "guest-book.testnet", "methodName": "add_message", "args": { "text": "hello from a per-network call" }, "gas": "30000000000000", "deposit": "0" }, "snippets": [ { "id": "terminal", "label": "Terminal", "environment": "terminal", "language": "bash", "runnable": false, "reason": "browser_required", "code": "# Browser wallet required.\n# Signing a transaction needs the wallet picker, which needs a browser.\n# Use the browser-global or ESM snippet for this task." }, { "id": "browser-global", "label": "Browser Global", "environment": "browserGlobal", "language": "js", "runnable": true, "code": "// near.recipes.functionCall accepts a per-call network override\n// (@fastnear/api 1.1.2+) — once a testnet session is open, the api reads\n// the testnet account from its per-network state map and dispatches the\n// signed transaction through the wallet's testnet slot. The mainnet\n// session, if any, is untouched.\nawait near.recipes.connect({\n network: \"testnet\",\n contractId: \"guest-book.testnet\",\n});\n\nconst result = await near.recipes.functionCall({\n network: \"testnet\",\n receiverId: \"guest-book.testnet\",\n methodName: \"add_message\",\n args: { text: \"hello from a per-network call\" },\n gas: \"30000000000000\",\n deposit: \"0\",\n});\n\nnear.print(result);" }, { "id": "esm", "label": "ESM", "environment": "esm", "language": "js", "runnable": true, "code": "import * as near from \"@fastnear/api\";\nimport * as nearWallet from \"@fastnear/wallet\";\n\nnear.config({ apiKey: process.env.FASTNEAR_API_KEY || undefined });\nnear.useWallet(nearWallet);\nawait nearWallet.restore({\n network: \"mainnet\",\n contractId: \"berryclub.ek.near\",\n manifest: \"./manifest.json\",\n});\n\n// near.recipes.functionCall accepts a per-call network override\n// (@fastnear/api 1.1.2+) — once a testnet session is open, the api reads\n// the testnet account from its per-network state map and dispatches the\n// signed transaction through the wallet's testnet slot. The mainnet\n// session, if any, is untouched.\nawait near.recipes.connect({\n network: \"testnet\",\n contractId: \"guest-book.testnet\",\n});\n\nconst result = await near.recipes.functionCall({\n network: \"testnet\",\n receiverId: \"guest-book.testnet\",\n methodName: \"add_message\",\n args: { text: \"hello from a per-network call\" },\n gas: \"30000000000000\",\n deposit: \"0\",\n});\n\nnear.print(result);" } ], "service": "wallet", "returns": "{ outcomes?: any[] } | { rejected: true } | undefined", "outputKeys": [ "outcomes[].transaction.hash", "outcomes[].status" ], "responseNotes": [ "@fastnear/api 1.1.2 keys account state per network, so near.recipes.functionCall reads the testnet signer from its testnet slot regardless of which network is currently active.", "Local-signing also honors the network override in 1.1.2 — the RPC helpers, queryAccessKey/queryBlock/sendTxToRpc, and the nonce/block caches are all keyed per network.", "nearWallet.connectedNetworks() returns the list of networks with an active session if you want to gate the call on testnet being signed in first." ], "chooseWhen": [ "Choose this when an action lives on testnet but the page also holds a live mainnet session.", "Use function-call when only one network is involved." ], "followUps": [ "Sign a NEP-413 message with the testnet session via near.recipes.signMessage(message, { network: \"testnet\" }).", "Send NEAR with near.recipes.transfer({ network: \"testnet\", … }) — same per-network surface." ], "pagination": { "kind": "none", "requestFields": [], "responseFields": [], "filtersMustStayStable": false }, "relatedRecipes": [ "connect-testnet", "function-call", "transfer" ] } ], "explain": [ { "api": "near.explain.action", "summary": "Normalize one action into a stable JSON summary.", "example": "{\n \"kind\": \"action\",\n \"type\": \"FunctionCall\",\n \"methodName\": \"draw\",\n \"gas\": \"100000000000000\",\n \"deposit\": \"0\",\n \"args\": {\n \"pixels\": [\n {\n \"x\": 10,\n \"y\": 20,\n \"color\": 65280\n }\n ]\n },\n \"argsBase64\": null,\n \"params\": {\n \"methodName\": \"draw\",\n \"gas\": \"100000000000000\",\n \"deposit\": \"0\",\n \"args\": {\n \"pixels\": [\n {\n \"x\": 10,\n \"y\": 20,\n \"color\": 65280\n }\n ]\n },\n \"argsBase64\": null\n }\n}" }, { "api": "near.explain.tx", "summary": "Summarize a signer, receiver, and action list into stable JSON.", "example": "{\n \"kind\": \"transaction\",\n \"signerId\": \"root.near\",\n \"receiverId\": \"berryclub.ek.near\",\n \"actionCount\": 1,\n \"actions\": [\n {\n \"kind\": \"action\",\n \"type\": \"FunctionCall\",\n \"methodName\": \"draw\",\n \"gas\": \"100000000000000\",\n \"deposit\": \"0\",\n \"args\": {\n \"pixels\": [\n {\n \"x\": 10,\n \"y\": 20,\n \"color\": 65280\n }\n ]\n },\n \"argsBase64\": null,\n \"params\": {\n \"methodName\": \"draw\",\n \"gas\": \"100000000000000\",\n \"deposit\": \"0\",\n \"args\": {\n \"pixels\": [\n {\n \"x\": 10,\n \"y\": 20,\n \"color\": 65280\n }\n ]\n },\n \"argsBase64\": null\n }\n }\n ]\n}" }, { "api": "near.explain.error", "summary": "Turn thrown RPC, wallet, or transport failures into a predictable JSON object.", "example": "{\n \"kind\": \"rpc_error\",\n \"code\": -32000,\n \"name\": \"FastNearError\",\n \"message\": \"Server error\",\n \"data\": {\n \"name\": \"HANDLER_ERROR\"\n },\n \"retryable\": true\n}" } ] }