[{"data":1,"prerenderedAt":563},["ShallowReactive",2],{"navigation_docs":3,"-guide-selection":120,"-guide-selection-surround":558},[4,56,116],{"title":5,"path":6,"stem":7,"children":8,"icon":55},"Guide","\u002Fguide","1.guide\u002F01.index",[9,11,15,19,23,27,31,35,39,43,47,51],{"title":10,"path":6,"stem":7},"Getting Started",{"title":12,"path":13,"stem":14},"CLI","\u002Fguide\u002Fcli","1.guide\u002F02.cli",{"title":16,"path":17,"stem":18},"Provider selection","\u002Fguide\u002Fselection","1.guide\u002F03.selection",{"title":20,"path":21,"stem":22},"Balances","\u002Fguide\u002Fbalances","1.guide\u002F04.balances",{"title":24,"path":25,"stem":26},"Transactions","\u002Fguide\u002Ftransactions","1.guide\u002F05.transactions",{"title":28,"path":29,"stem":30},"Tokens","\u002Fguide\u002Ftokens","1.guide\u002F06.tokens",{"title":32,"path":33,"stem":34},"Contracts","\u002Fguide\u002Fcontracts","1.guide\u002F07.contracts",{"title":36,"path":37,"stem":38},"Gas and blocks","\u002Fguide\u002Fgas-and-blocks","1.guide\u002F08.gas-and-blocks",{"title":40,"path":41,"stem":42},"Errors","\u002Fguide\u002Ferrors","1.guide\u002F09.errors",{"title":44,"path":45,"stem":46},"Agents","\u002Fguide\u002Fagents","1.guide\u002F10.agents",{"title":48,"path":49,"stem":50},"Custom providers","\u002Fguide\u002Fcustom","1.guide\u002F11.custom",{"title":52,"path":53,"stem":54},"Explorer","\u002Fguide\u002Fexplorer","1.guide\u002F12.explorer","i-solar-book-2-linear",{"title":57,"path":58,"stem":59,"children":60,"icon":115},"Providers","\u002Fproviders","2.providers\u002F0.index",[61,63,67,71,75,79,83,87,91,95,99,103,107,111],{"title":62,"path":58,"stem":59},"Overview",{"title":64,"path":65,"stem":66},"Etherscan","\u002Fproviders\u002Fetherscan","2.providers\u002F01.etherscan",{"title":68,"path":69,"stem":70},"Blockscout","\u002Fproviders\u002Fblockscout","2.providers\u002F02.blockscout",{"title":72,"path":73,"stem":74},"Blockchair","\u002Fproviders\u002Fblockchair","2.providers\u002F03.blockchair",{"title":76,"path":77,"stem":78},"Mempool","\u002Fproviders\u002Fmempool","2.providers\u002F04.mempool",{"title":80,"path":81,"stem":82},"Blockstream","\u002Fproviders\u002Fblockstream","2.providers\u002F05.blockstream",{"title":84,"path":85,"stem":86},"Solscan","\u002Fproviders\u002Fsolscan","2.providers\u002F06.solscan",{"title":88,"path":89,"stem":90},"Helius","\u002Fproviders\u002Fhelius","2.providers\u002F07.helius",{"title":92,"path":93,"stem":94},"TONAPI","\u002Fproviders\u002Fton","2.providers\u002F08.ton",{"title":96,"path":97,"stem":98},"TRONSCAN","\u002Fproviders\u002Ftronscan","2.providers\u002F09.tronscan",{"title":100,"path":101,"stem":102},"Aptos Explorer","\u002Fproviders\u002Faptos","2.providers\u002F10.aptos",{"title":104,"path":105,"stem":106},"Blockberry","\u002Fproviders\u002Fblockberry","2.providers\u002F11.blockberry",{"title":108,"path":109,"stem":110},"Koios","\u002Fproviders\u002Fkoios","2.providers\u002F12.koios",{"title":112,"path":113,"stem":114},"Arweave gateway","\u002Fproviders\u002Farweave","2.providers\u002F13.arweave","i-solar-library-linear",{"title":117,"path":118,"stem":119},"Chains","\u002Fchains","3.chains",{"id":121,"title":16,"body":122,"description":551,"extension":552,"links":553,"meta":554,"navigation":245,"path":17,"seo":556,"stem":18,"__hash__":557},"docs\u002F1.guide\u002F03.selection.md",{"type":123,"value":124,"toc":544},"minimark",[125,130,146,190,193,329,333,340,344,365,501,514,518,525,529,540],[126,127,129],"h2",{"id":128},"the-ranking","The ranking",[131,132,133,137,138,141,142,145],"p",{},[134,135,136],"code",{},"resolveProvider(preferred, chain, capability)"," answers a name without loading a single provider module. With an explicit ",[134,139,140],{},"preferred"," it returns that name, or throws ",[134,143,144],{},"UnknownProviderError"," if nothing is registered under it. Without one it walks the built-in list in this order and returns the first that serves the chain and, when asked for one, the capability:",[147,148,149,161,167,181],"ol",{},[150,151,152,156,157,160],"li",{},[153,154,155],"strong",{},"Providers with configured keys."," Every environment variable a provider reads must be set. ",[134,158,159],{},"ETHERSCAN_API_KEY"," alone puts Etherscan first for the ten chains it serves.",[150,162,163,166],{},[153,164,165],{},"Keyless providers."," Blockscout, Mempool, Blockstream, TONAPI, Aptos, Koios and the Arweave gateway, in registry order.",[150,168,169,172,173,176,177,180],{},[153,170,171],{},"Any registry entry that serves the chain."," Keyed providers without a key land here, so a Solana read without ",[134,174,175],{},"SOLSCAN_API_KEY"," still resolves to Solscan and fails with an ",[134,178,179],{},"AuthError"," that says what is missing.",[150,182,183,185,186,189],{},[153,184,68],{},", when no provider claims the chain at all. It then answers with ",[134,187,188],{},"UnsupportedChainError",", which is more useful than nothing.",[131,191,192],{},"When a capability is asked for and nobody serves it on that chain, selection falls back to the ranking by chain alone so the error you get is the typed limitation of a provider that at least knows the chain.",[194,195,200],"pre",{"className":196,"code":197,"language":198,"meta":199,"style":199},"language-ts shiki shiki-themes github-light github-light poimandres","import { resolveProvider } from \"@agntn\u002Fexplorers\";\n\nresolveProvider(undefined, \"ethereum\"); \u002F\u002F \"etherscan\" with a key, \"blockscout\" without\nresolveProvider(undefined, \"bitcoin\", \"gasData\"); \u002F\u002F \"mempool\"; Blockchair and Blockstream have no fee data\nresolveProvider(\"koios\"); \u002F\u002F \"koios\", whatever the chain\n","ts","",[134,201,202,240,247,278,310],{"__ignoreMap":199},[203,204,207,211,215,219,222,226,230,234,237],"span",{"class":205,"line":206},"line",1,[203,208,210],{"class":209},"sP0CR","import",[203,212,214],{"class":213},"sKlNE"," {",[203,216,218],{"class":217},"snHMy"," resolveProvider",[203,220,221],{"class":213}," }",[203,223,225],{"class":224},"stCPd"," from",[203,227,229],{"class":228},"scVjq"," \"",[203,231,233],{"class":232},"sQ7BG","@agntn\u002Fexplorers",[203,235,236],{"class":228},"\"",[203,238,239],{"class":213},";\n",[203,241,243],{"class":205,"line":242},2,[203,244,246],{"emptyLinePlaceholder":245},true,"\n",[203,248,250,254,257,261,264,266,269,271,274],{"class":205,"line":249},3,[203,251,253],{"class":252},"sULi6","resolveProvider",[203,255,256],{"class":213},"(",[203,258,260],{"class":259},"sNe8j","undefined",[203,262,263],{"class":213},", ",[203,265,236],{"class":228},[203,267,268],{"class":232},"ethereum",[203,270,236],{"class":228},[203,272,273],{"class":213},"); ",[203,275,277],{"class":276},"sjhu3","\u002F\u002F \"etherscan\" with a key, \"blockscout\" without\n",[203,279,281,283,285,287,289,291,294,296,298,300,303,305,307],{"class":205,"line":280},4,[203,282,253],{"class":252},[203,284,256],{"class":213},[203,286,260],{"class":259},[203,288,263],{"class":213},[203,290,236],{"class":228},[203,292,293],{"class":232},"bitcoin",[203,295,236],{"class":228},[203,297,263],{"class":213},[203,299,236],{"class":228},[203,301,302],{"class":232},"gasData",[203,304,236],{"class":228},[203,306,273],{"class":213},[203,308,309],{"class":276},"\u002F\u002F \"mempool\"; Blockchair and Blockstream have no fee data\n",[203,311,313,315,317,319,322,324,326],{"class":205,"line":312},5,[203,314,253],{"class":252},[203,316,256],{"class":213},[203,318,236],{"class":228},[203,320,321],{"class":232},"koios",[203,323,236],{"class":228},[203,325,273],{"class":213},[203,327,328],{"class":276},"\u002F\u002F \"koios\", whatever the chain\n",[126,330,332],{"id":331},"blockchair-is-the-odd-one","Blockchair is the odd one",[131,334,335,336,339],{},"Blockchair works without a key and works better with one. It is a keyed provider in tier 1 when ",[134,337,338],{},"BLOCKCHAIR_API_KEY"," is set, and it joins the keyless tier only during the fallback pass described below. So a Bitcoin balance on a machine without keys goes to Mempool first, and Blockchair is what it retries on.",[126,341,343],{"id":342},"the-one-retry","The one retry",[131,345,346,349,350,353,354,357,358,361,362,364],{},[134,347,348],{},"withProvider(preferred, chain, run, capability)"," is what the CLI, the MCP server and both agent extensions call. It resolves a provider, creates it, and runs your callback with ",[134,351,352],{},"{ chain, name, provider }",". If the callback throws ",[134,355,356],{},"RateLimitError"," or ",[134,359,360],{},"PlanRestrictedError"," and the provider was chosen automatically, it runs once more on the next candidate that serves the chain and capability. Every other failure stays with the first provider, and an explicit ",[134,363,140],{}," is never retried, because you asked for that one.",[194,366,368],{"className":196,"code":367,"language":198,"meta":199,"style":199},"import { withProvider } from \"@agntn\u002Fexplorers\";\n\nconst balance = await withProvider(\n  undefined,\n  \"ethereum\",\n  ({ provider, chain }) => provider.getBalance(\"0x…\", chain),\n  \"balances\",\n);\n",[134,369,370,391,395,417,425,436,483,495],{"__ignoreMap":199},[203,371,372,374,376,379,381,383,385,387,389],{"class":205,"line":206},[203,373,210],{"class":209},[203,375,214],{"class":213},[203,377,378],{"class":217}," withProvider",[203,380,221],{"class":213},[203,382,225],{"class":224},[203,384,229],{"class":228},[203,386,233],{"class":232},[203,388,236],{"class":228},[203,390,239],{"class":213},[203,392,393],{"class":205,"line":242},[203,394,246],{"emptyLinePlaceholder":245},[203,396,397,401,405,408,412,414],{"class":205,"line":249},[203,398,400],{"class":399},"s1TYA","const",[203,402,404],{"class":403},"saoiD"," balance",[203,406,407],{"class":399}," =",[203,409,411],{"class":410},"sZW6a"," await",[203,413,378],{"class":252},[203,415,416],{"class":213},"(\n",[203,418,419,422],{"class":205,"line":280},[203,420,421],{"class":259},"  undefined",[203,423,424],{"class":213},",\n",[203,426,427,430,432,434],{"class":205,"line":312},[203,428,429],{"class":228},"  \"",[203,431,268],{"class":232},[203,433,236],{"class":228},[203,435,424],{"class":213},[203,437,439,442,446,448,451,454,457,461,464,467,469,471,474,476,478,480],{"class":205,"line":438},6,[203,440,441],{"class":213},"  ({ ",[203,443,445],{"class":444},"s1jWp","provider",[203,447,263],{"class":213},[203,449,450],{"class":444},"chain",[203,452,453],{"class":213}," }) ",[203,455,456],{"class":399},"=>",[203,458,460],{"class":459},"spVlQ"," provider",[203,462,463],{"class":213},".",[203,465,466],{"class":252},"getBalance",[203,468,256],{"class":213},[203,470,236],{"class":228},[203,472,473],{"class":232},"0x…",[203,475,236],{"class":228},[203,477,263],{"class":213},[203,479,450],{"class":459},[203,481,482],{"class":213},"),\n",[203,484,486,488,491,493],{"class":205,"line":485},7,[203,487,429],{"class":228},[203,489,490],{"class":232},"balances",[203,492,236],{"class":228},[203,494,424],{"class":213},[203,496,498],{"class":205,"line":497},8,[203,499,500],{"class":213},");\n",[131,502,503,504,506,507,509,510,513],{},"Two consequences worth knowing. The callback can run twice, so it belongs to reads and nothing that has side effects. And if the fallback fails with an ",[134,505,179],{},", an ",[134,508,188],{}," or an ",[134,511,512],{},"UnsupportedOperationError",", you get the first provider's error back, because the second one's complaint is about its own configuration, not about your request.",[126,515,517],{"id":516},"default-chains","Default chains",[131,519,520,521,524],{},"With neither provider nor chain, a read starts on Ethereum. An explicit provider without a chain keeps that provider's default: Bitcoin for Mempool and Blockstream, Solana for Solscan and Helius, TON, TRON, Aptos, Sui for Blockberry, Cardano for Koios, Arweave for the gateway. Etherscan, Blockscout and Blockchair default to Ethereum. The table is ",[134,522,523],{},"PROVIDER_DEFAULT_CHAIN",", exported.",[126,526,528],{"id":527},"strictness","Strictness",[131,530,531,532,534,535,539],{},"An explicit provider on a chain it cannot serve is an ",[134,533,188],{},", not a silent switch to one that can. Misconfiguration stays visible. The ",[536,537,52],"a",{"href":538},"\u002Fexplorer"," has a provider select for exactly this: pick Mempool on Ethereum and read the error.",[541,542,543],"style",{},"html pre.shiki code .sP0CR, html code.shiki .sP0CR{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#5DE4C7}html pre.shiki code .sKlNE, html code.shiki .sKlNE{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#A6ACCD}html pre.shiki code .snHMy, html code.shiki .snHMy{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#ADD7FF}html pre.shiki code .stCPd, html code.shiki .stCPd{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#A6ACCD}html pre.shiki code .scVjq, html code.shiki .scVjq{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#A6ACCD}html pre.shiki code .sQ7BG, html code.shiki .sQ7BG{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#5DE4C7}html pre.shiki code .sULi6, html code.shiki .sULi6{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#E4F0FBD0}html pre.shiki code .sNe8j, html code.shiki .sNe8j{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#D0679D}html pre.shiki code .sjhu3, html code.shiki .sjhu3{--shiki-light:#6A737D;--shiki-light-font-style:inherit;--shiki-default:#6A737D;--shiki-default-font-style:inherit;--shiki-dark:#767C9DB0;--shiki-dark-font-style:italic}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .s1TYA, html code.shiki .s1TYA{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#91B4D5}html pre.shiki code .saoiD, html code.shiki .saoiD{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#E4F0FB}html pre.shiki code .sZW6a, html code.shiki .sZW6a{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#5DE4C7C0}html pre.shiki code .s1jWp, html code.shiki .s1jWp{--shiki-light:#E36209;--shiki-default:#E36209;--shiki-dark:#E4F0FB}html pre.shiki code .spVlQ, html code.shiki .spVlQ{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#E4F0FB}",{"title":199,"searchDepth":242,"depth":242,"links":545},[546,547,548,549,550],{"id":128,"depth":242,"text":129},{"id":331,"depth":242,"text":332},{"id":342,"depth":242,"text":343},{"id":516,"depth":242,"text":517},{"id":527,"depth":242,"text":528},"How resolveProvider ranks candidates, when withProvider retries, and why an explicit provider is never second guessed.","md",null,{"icon":555},"i-solar-routing-2-linear",{"title":16,"description":551},"awyi2R4K7Xf0tWmryqLlfkooR5mDzSqpw4C5DNEzvVU",[559,561],{"title":12,"path":13,"stem":14,"description":560,"children":-1},"One binary, eight reads and an MCP server. An address as the first argument means balance, no ceremony.",{"title":20,"path":21,"stem":22,"description":562,"children":-1},"getBalance on every chain, the Balance shape, ENS resolution, UTXO totals, and why blockNumber is sometimes null.",1788626961518]