@defillama/sdk 5.0.238 → 5.0.242

package/build/abi/multicall.js

@@ -376,6 +376,7 @@ function multicallAddress(chainId) {
         case 7119: return '0xFd4b34b5763f54a580a0d9f7997A2A993ef9ceE9'; // sentrix
         case 36900: return '0x73df6E8F0D112D22bD672952323b43d6893AB6D2'; // adi
         case 589: return '0x36b580266BD2B9581B805BF99D0Db92FbC9CAa56'; // lady
+        case 3344: return '0x1D9589CF11D92f46addd491e9698D7719c45a18f'; // pentagonchain (v1: aggregate only, deployed block 401584)
         default:
             return null;
     }

package/build/abi/multicall3.js

@@ -240,6 +240,11 @@ const DEPLOYMENT_BLOCK = {
     prom: 1238475,
     nibiru: 19587573,
     arc: 1,
+    btcwchain: 178635,
+    horizen: 1,
+    metall2: 1,
+    rbn: 2714761,
+    xpla: 19189761,
 };
 async function makeMultiCall(functionABI, calls, chain, block) {
     if (!functionABI)
@@ -394,4 +399,5 @@ const CUSTOM_MULTICALL_ADDRESSES = {
     'eni': '0xbf9d276932DF9c0AA1644b2569482f7a754433be',
     'shido': '0xe3da1EC9e9BfEa1fE8C5905133c36A86351e4561',
     'prom': '0xfF785aF3De8C2cb5727A8665984E741c16679131',
+    'btcwchain': '0xA0093EA76633A983364cb2582959870eaffDdea0',
 };

package/build/chains/aptos.d.ts

@@ -4,6 +4,11 @@ export declare const DEFAULT_ENDPOINTS: Record<string, string>;
  * (the public aptos fullnode keeps only a few weeks of blocks). Override with `<CHAIN>_ARCHIVAL_RPC`.
  */
 export declare const ARCHIVAL_ENDPOINTS: Record<string, string>;
+/**
+ * Indexer (Hasura GraphQL) endpoints. Override / add fallbacks with `<CHAIN>_INDEXER` (comma separated).
+ * The `<CHAIN>_API_KEY` bearer key is sent here too (aptoslabs keys cover both the full node and the indexer).
+ */
+export declare const INDEXER_ENDPOINTS: Record<string, string>;
 export declare const aptosChains: string[];
 export declare const APT_COIN_TYPE = "0x1::aptos_coin::AptosCoin";
 export declare const APT_DECIMALS = 8;
@@ -68,6 +73,8 @@ export declare function getEndpointList({ chain }?: ChainOptions): string[];
 export declare function getEndpoint({ chain }?: ChainOptions): string;
 /** Archival endpoints for the chain (`<CHAIN>_ARCHIVAL_RPC` env, then built-in); empty when none. */
 export declare function getArchivalEndpointList({ chain }?: ChainOptions): string[];
+/** Indexer GraphQL endpoints for the chain (`<CHAIN>_INDEXER` env first, then built-in); empty when none. */
+export declare function getIndexerEndpointList({ chain }?: ChainOptions): string[];
 /** GET `path` (relative to the node root, e.g. `/v1/accounts/0x1`). 404 -> `null` when `allowNotFound`. */
 export declare function get({ chain, path, params, allowNotFound, timeout, retries, archival }: RequestOptions & {
     path: string;
@@ -81,6 +88,38 @@ export declare function post({ chain, path, body, params, allowNotFound, timeout
     params?: Record<string, any>;
     allowNotFound?: boolean;
 }): Promise<any>;
+/** GraphQL `errors` in a 200 response (bad query, or a rate limit the indexer reports in-band). */
+export declare class IndexerError extends Error {
+    errors: any[];
+    constructor(errors: any[]);
+}
+/**
+ * Run a GraphQL query against the chain's indexer, returning `data`. Same transport as the node calls:
+ * rotates over `<CHAIN>_INDEXER` endpoints (then the default), retries transport/5xx/429 failures with
+ * backoff and sends the `<CHAIN>_API_KEY` bearer key. GraphQL `errors` throw `IndexerError` and are
+ * only retried when they report a rate limit (a bad query fails fast).
+ */
+export declare function indexerQuery<T = any>({ chain, query, variables, timeout, retries }: RequestOptions & {
+    query: string;
+    variables?: Record<string, any>;
+}): Promise<T>;
+export interface FungibleAssetBalance {
+    owner: string;
+    /** coin type (`0x1::aptos_coin::AptosCoin`) or FA metadata address */
+    assetType: string;
+    /** raw amount (coin + fungible store balance combined by the indexer) */
+    amount: string;
+}
+/**
+ * Coin + fungible asset balances of many owners from the indexer (`current_fungible_asset_balances`),
+ * `chunkSize` owners per query and paginated, so a few requests replace one node call per owner per token.
+ * Owners are matched by the indexer's 64-hex form, so short addresses are padded first.
+ */
+export declare function getFungibleAssetBalances({ chain, owners, chunkSize, pageSize, timeout, retries }: RequestOptions & {
+    owners: string[];
+    chunkSize?: number;
+    pageSize?: number;
+}): Promise<FungibleAssetBalance[]>;
 export declare function getLedgerInfo({ chain, archival }?: ChainOptions & {
     archival?: boolean;
 }): Promise<LedgerInfo>;

package/build/chains/aptos.js

@@ -3,13 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APT_DECIMALS = exports.APT_COIN_TYPE = exports.aptosChains = exports.ARCHIVAL_ENDPOINTS = exports.DEFAULT_ENDPOINTS = void 0;
+exports.IndexerError = exports.APT_DECIMALS = exports.APT_COIN_TYPE = exports.aptosChains = exports.INDEXER_ENDPOINTS = exports.ARCHIVAL_ENDPOINTS = exports.DEFAULT_ENDPOINTS = void 0;
 exports.isAptosChain = isAptosChain;
 exports.getEndpointList = getEndpointList;
 exports.getEndpoint = getEndpoint;
 exports.getArchivalEndpointList = getArchivalEndpointList;
+exports.getIndexerEndpointList = getIndexerEndpointList;
 exports.get = get;
 exports.post = post;
+exports.indexerQuery = indexerQuery;
+exports.getFungibleAssetBalances = getFungibleAssetBalances;
 exports.getLedgerInfo = getLedgerInfo;
 exports.getAccount = getAccount;
 exports.getResources = getResources;
@@ -52,6 +55,9 @@ exports.parseTypeTag = parseTypeTag;
  * retried on the archival endpoint (`<CHAIN>_ARCHIVAL_RPC`, default `archive.mainnet.aptoslabs.com`).
  * Timestamp -> version lookups use a REST binary search over block heights instead of the
  * aptoslabs indexer GraphQL API, so they work on any full node and on Movement.
+ * Indexer GraphQL queries (`indexerQuery`, `getFungibleAssetBalances`) go through the same transport:
+ * `<CHAIN>_INDEXER` (comma separated) overrides / adds to the default endpoint, with rotation, retries
+ * and the bearer key.
  *
  * Usage: `sdk.chains.aptos.getResource({ account: '0x1', type: '0x1::coin::CoinInfo<0x1::aptos_coin::AptosCoin>' })`
  */
@@ -73,6 +79,15 @@ exports.DEFAULT_ENDPOINTS = {
 exports.ARCHIVAL_ENDPOINTS = {
     aptos: 'https://archive.mainnet.aptoslabs.com',
 };
+/**
+ * Indexer (Hasura GraphQL) endpoints. Override / add fallbacks with `<CHAIN>_INDEXER` (comma separated).
+ * The `<CHAIN>_API_KEY` bearer key is sent here too (aptoslabs keys cover both the full node and the indexer).
+ */
+exports.INDEXER_ENDPOINTS = {
+    // keyless public endpoints (third-party indexers like Nodit need a key: add them via <CHAIN>_INDEXER)
+    aptos: 'https://api.mainnet.aptoslabs.com/v1/graphql,https://indexer.mainnet.aptoslabs.com/v1/graphql',
+    move: 'https://indexer.mainnet.movementnetwork.xyz/v1/graphql',
+};
 exports.aptosChains = Object.keys(exports.DEFAULT_ENDPOINTS);
 exports.APT_COIN_TYPE = '0x1::aptos_coin::AptosCoin';
 exports.APT_DECIMALS = 8;
@@ -106,6 +121,16 @@ function getArchivalEndpointList({ chain } = {}) {
         return [];
     }
 }
+/** Indexer GraphQL endpoints for the chain (`<CHAIN>_INDEXER` env first, then built-in); empty when none. */
+function getIndexerEndpointList({ chain } = {}) {
+    chain = resolveChain(chain);
+    try {
+        return (0, rpc_1.getEndpoints)(chain, exports.INDEXER_ENDPOINTS[chain], { envKey: `${chain.toUpperCase()}_INDEXER` });
+    }
+    catch {
+        return [];
+    }
+}
 function getHeaders(chain) {
     const headers = { 'Content-Type': 'application/json' };
     const apiKey = (0, env_1.getEnvValue)(`${chain.toUpperCase()}_API_KEY`);
@@ -154,10 +179,10 @@ async function request(options) {
     }
 }
 async function requestOn(endpoints, options) {
-    var _a;
+    var _a, _b, _c;
     const chain = resolveChain(options.chain);
-    const limiter = (0, rpc_1.getLimiter)(chain.toUpperCase(), 10);
-    const { method, path, params, body, allowNotFound, withMetadata, timeout = DEFAULT_TIMEOUT } = options;
+    const limiter = (0, rpc_1.getLimiter)((_a = options.limiterKey) !== null && _a !== void 0 ? _a : chain.toUpperCase(), 10);
+    const { method, path, params, body, allowNotFound, withMetadata, validate, timeout = DEFAULT_TIMEOUT } = options;
     const headers = getHeaders(chain);
     const config = { timeout, headers, params };
     const res = await (0, rpc_1.withRetry)(async (attempt) => {
@@ -165,11 +190,11 @@ async function requestOn(endpoints, options) {
         const url = (0, rpc_1.joinUrl)(base, path);
         return limiter(async () => {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            let response;
             try {
-                const response = method === 'post'
+                response = method === 'post'
                     ? await axios_1.default.post(url, body, config)
                     : await axios_1.default.get(url, config);
-                return withMetadata ? response : response.data;
             }
             catch (e) {
                 if (allowNotFound && isNotFound(e)) {
@@ -186,11 +211,14 @@ async function requestOn(endpoints, options) {
                 err._isCustomError = true; // already formatted: keeps status/errorCode intact through withRetry/formError
                 throw err;
             }
+            if (validate)
+                validate(response.data);
+            return withMetadata ? response : response.data;
         });
     }, {
-        label: `${chain} ${method.toUpperCase()} ${path.split('?')[0].slice(0, 80)}`,
-        retries: (_a = options.retries) !== null && _a !== void 0 ? _a : Math.max(3, endpoints.length),
-        shouldRetry: rpc_1.isRetryableError,
+        label: `${chain} ${method.toUpperCase()} ${(path || (0, rpc_1.shortUrl)(endpoints[0])).split('?')[0].slice(0, 80)}`,
+        retries: (_b = options.retries) !== null && _b !== void 0 ? _b : Math.max(3, endpoints.length),
+        shouldRetry: (_c = options.shouldRetry) !== null && _c !== void 0 ? _c : rpc_1.isRetryableError,
     });
     return res === NOT_FOUND ? null : res;
 }
@@ -211,6 +239,66 @@ async function post({ chain, path, body, params, allowNotFound, timeout, retries
     return request({ chain, method: 'post', path, body, params, allowNotFound, timeout, retries, archival });
 }
 // ---------------------------------------------------------------------------
+// indexer (GraphQL)
+// ---------------------------------------------------------------------------
+/** GraphQL `errors` in a 200 response (bad query, or a rate limit the indexer reports in-band). */
+class IndexerError extends Error {
+    constructor(errors) {
+        super(`aptos indexer: ${errors.map((e) => { var _a; return (_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : JSON.stringify(e); }).join('; ').slice(0, 300)}`);
+        this.name = 'IndexerError';
+        this.errors = errors;
+    }
+}
+exports.IndexerError = IndexerError;
+/**
+ * Run a GraphQL query against the chain's indexer, returning `data`. Same transport as the node calls:
+ * rotates over `<CHAIN>_INDEXER` endpoints (then the default), retries transport/5xx/429 failures with
+ * backoff and sends the `<CHAIN>_API_KEY` bearer key. GraphQL `errors` throw `IndexerError` and are
+ * only retried when they report a rate limit (a bad query fails fast).
+ */
+async function indexerQuery({ chain, query, variables = {}, timeout, retries }) {
+    chain = resolveChain(chain);
+    const endpoints = getIndexerEndpointList({ chain });
+    if (!endpoints.length)
+        throw new Error(`[${chain}] no indexer endpoint configured (env ${chain.toUpperCase()}_INDEXER)`);
+    const res = await requestOn(endpoints, {
+        chain, method: 'post', path: '', body: { query, variables }, timeout, retries,
+        limiterKey: `${chain.toUpperCase()}_INDEXER`,
+        validate: (data) => { var _a; if ((_a = data === null || data === void 0 ? void 0 : data.errors) === null || _a === void 0 ? void 0 : _a.length)
+            throw new IndexerError(data.errors); },
+        shouldRetry: (e) => e instanceof IndexerError ? (0, rpc_1.isRateLimitError)(e) : (0, rpc_1.isRetryableError)(e),
+    });
+    return res === null || res === void 0 ? void 0 : res.data;
+}
+const FA_BALANCES_QUERY = `query ($owners: [String!]!, $offset: Int!, $limit: Int!) {
+  current_fungible_asset_balances(where: { owner_address: { _in: $owners } }, offset: $offset, limit: $limit, order_by: [{ owner_address: asc }, { asset_type: asc }]) {
+    owner_address
+    asset_type
+    amount
+  }
+}`;
+/**
+ * Coin + fungible asset balances of many owners from the indexer (`current_fungible_asset_balances`),
+ * `chunkSize` owners per query and paginated, so a few requests replace one node call per owner per token.
+ * Owners are matched by the indexer's 64-hex form, so short addresses are padded first.
+ */
+async function getFungibleAssetBalances({ chain, owners, chunkSize = 50, pageSize = 1000, timeout, retries }) {
+    var _a;
+    const unique = [...new Set(owners.map(normalizeAddress))];
+    const out = [];
+    for (const chunk of (0, rpc_1.sliceIntoChunks)(unique, chunkSize)) {
+        for (let offset = 0;; offset += pageSize) {
+            const data = await indexerQuery({ chain, query: FA_BALANCES_QUERY, variables: { owners: chunk, offset, limit: pageSize }, timeout, retries });
+            const rows = (_a = data === null || data === void 0 ? void 0 : data.current_fungible_asset_balances) !== null && _a !== void 0 ? _a : [];
+            for (const { owner_address, asset_type, amount } of rows)
+                out.push({ owner: owner_address, assetType: asset_type, amount: String(amount) });
+            if (rows.length < pageSize)
+                break;
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // ledger / accounts / resources
 // ---------------------------------------------------------------------------
 function microsToSeconds(value) {

package/build/chains/utxo.d.ts

@@ -1,3 +1,4 @@
+export type ProviderKind = 'esplora' | 'blockbook' | 'blockcypher' | 'tatum' | 'insight' | 'whatsonchain' | 'blockchair' | 'haskoin' | 'kaspa' | 'mvc';
 export interface UtxoChainConfig {
     decimals: number;
     /** explorer base urls in fallback order, overridable with `<CHAIN>_EXPLORER_API` */
@@ -6,9 +7,13 @@ export interface UtxoChainConfig {
     concurrency: number;
     /** pause before every request (free-tier rate limits), applied inside the limiter */
     sleepMs?: number;
+    /** dialect for endpoints whose host is not recognised, overridable with `<CHAIN>_EXPLORER_PROVIDER` */
+    provider?: ProviderKind;
 }
 export declare const CHAINS: Record<string, UtxoChainConfig>;
+/** Built-in chains; env-defined chains (see `getChainConfig`) are not listed here. */
 export declare const utxoChains: string[];
+export declare const PROVIDER_KINDS: ProviderKind[];
 /** mempool.space base url, used for the timestamp -> block lookup (`BITCOIN_MEMPOOL_API`). */
 export declare const DEFAULT_MEMPOOL_API = "https://mempool.space/api";
 /** blockchain.info multiaddr endpoint for bulk bitcoin balances (`BITCOIN_MULTIADDR_API`). */
@@ -19,7 +24,10 @@ export declare const MULTIADDR_CHUNK_SIZE = 100;
 export declare const MULTIADDR_SLEEP_MS = 10000;
 /** bitcoin cache api accepts up to 700 addresses per call */
 export declare const CACHE_API_CHUNK_SIZE = 700;
+/** True for built-in chains and for chains enabled through env (`<CHAIN>_EXPLORER_API` / `<CHAIN>_WHITELISTED_RPC`). */
 export declare function isUtxoChain(chain: any): boolean;
+/** Resolved config for `chain`: `CHAINS[chain]` or the env-defined config. Throws for unknown chains. */
+export declare function getChainConfig(chain: string): UtxoChainConfig;
 /** Explorer base urls for `chain`: env `<CHAIN>_EXPLORER_API` wins, then `CHAINS[chain].endpoints`. */
 export declare function getEndpoints({ chain }?: {
     chain?: string;

package/build/chains/utxo.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CACHE_API_CHUNK_SIZE = exports.MULTIADDR_SLEEP_MS = exports.MULTIADDR_CHUNK_SIZE = exports.DEFAULT_MULTIADDR_API = exports.DEFAULT_MEMPOOL_API = exports.utxoChains = exports.CHAINS = void 0;
+exports.CACHE_API_CHUNK_SIZE = exports.MULTIADDR_SLEEP_MS = exports.MULTIADDR_CHUNK_SIZE = exports.DEFAULT_MULTIADDR_API = exports.DEFAULT_MEMPOOL_API = exports.PROVIDER_KINDS = exports.utxoChains = exports.CHAINS = void 0;
 exports.isUtxoChain = isUtxoChain;
+exports.getChainConfig = getChainConfig;
 exports.getEndpoints = getEndpoints;
 exports.isBitcoinAddress = isBitcoinAddress;
 exports.toBigInt = toBigInt;
@@ -26,14 +27,14 @@ exports.getBlockAtTimestamp = getBlockAtTimestamp;
 /**
  * Balance client for bitcoin-like UTXO chains via public explorer APIs
  * (esplora/blockstream, mempool.space, blockbook, blockcypher, tatum, insight,
- * whatsonchain, blockchair, kaspa REST, mvcapi).
+ * whatsonchain, blockchair, haskoin, kaspa REST, mvcapi).
  *
  * Replaces the chain access parts of:
  *   - DefiLlama-Adapters  projects/helper/chain/bitcoin.js (getBalanceNow,
  *     getBalance(addr, timestamp), getCachedBitcoinBalances / cachedBTCBalCall,
  *     blockchain.info multiaddr batching)
  *   - DefiLlama-Adapters  projects/helper/chain/litecoin.js, doge.js, dash.js,
- *     bsv.js, zcash.js, kaspa.js, mvc.js (per-chain getBalance)
+ *     bsv.js, zcash.js, kaspa.js, mvc.js, bitcoincash.js (per-chain getBalance)
  *   - defillama-server    coins/src/adapters/other/others2.ts getBtcBalanceSats
  *     (blockstream -> mempool.space failover)
  *
@@ -42,8 +43,14 @@ exports.getBlockAtTimestamp = getBlockAtTimestamp;
  * sompi, ...) as a decimal string.
  *
  * Explorer base urls are overridable per chain with `<CHAIN>_EXPLORER_API`
- * (comma separated fallbacks, also `SDK_` / `LLAMA_SDK_` prefixed). Unknown
- * hosts are assumed to speak the chain's default provider dialect.
+ * (comma separated fallbacks, also `SDK_` / `LLAMA_SDK_` prefixed). Known hosts
+ * pick their dialect automatically; unknown hosts use `<CHAIN>_EXPLORER_PROVIDER`
+ * (one of the provider kinds below) and otherwise the chain's default dialect.
+ *
+ * Chains not listed in `CHAINS` can be enabled purely through env: setting
+ * `<CHAIN>_EXPLORER_API` (or `<CHAIN>_WHITELISTED_RPC`) makes `isUtxoChain`
+ * accept the chain, with `<CHAIN>_DECIMALS` (default 8), `<CHAIN>_EXPLORER_PROVIDER`
+ * (default esplora) and `<CHAIN>_RPC_CONCURRENCY` (default 5) completing the config.
  *
  * Usage: `sdk.chains.utxo.getBalance({ chain: 'bitcoin', address: 'bc1q...' })`
  */
@@ -56,6 +63,13 @@ exports.CHAINS = {
         endpoints: ['https://blockstream.info/api', 'https://mempool.space/api', 'https://rpc.ankr.com/http/btc_blockbook/api/v2'],
         concurrency: 5,
     },
+    bitcoincash: {
+        decimals: 8,
+        // haskoin (also mirrored by blockchain.com) takes cashaddr with or without the
+        // `bitcoincash:` prefix as well as legacy base58 addresses
+        endpoints: ['https://api.haskoin.com/bch', 'https://api.blockchain.info/haskoin-store/bch', 'https://api.tatum.io/v3/bcash', 'https://api.blockchair.com/bitcoin-cash'],
+        concurrency: 5,
+    },
     litecoin: {
         decimals: 8,
         endpoints: ['https://litecoinspace.org/api', 'https://api.blockchair.com/litecoin'],
@@ -81,8 +95,10 @@ exports.CHAINS = {
     },
     zcash: {
         decimals: 8,
-        // blockchair free tier: ~30 req/min per IP
-        endpoints: ['https://api.blockchair.com/zcash'],
+        // blockchair free tier: ~30 req/min per IP; zelcore blockbook is unthrottled; nownodes needs NOWNODES_API_KEY.
+        // Dead or gated as of 2026-10: zcha.in, zcashblockexplorer.com, zcashnetwork.info, zcashexplorer.app (403),
+        // trezor blockbooks (cloudflare), ankr zec_blockbook (plan-gated), cryptoid (no zec), tatum (no zec), 3xpl (token)
+        endpoints: ['https://api.blockchair.com/zcash', 'https://blockbook.zec.zelcore.io/api/v2', 'https://zecbook.nownodes.io/api/v2'],
         concurrency: 1,
         sleepMs: 5000,
     },
@@ -97,7 +113,11 @@ exports.CHAINS = {
         concurrency: 5,
     },
 };
+/** Built-in chains; env-defined chains (see `getChainConfig`) are not listed here. */
 exports.utxoChains = Object.keys(exports.CHAINS);
+exports.PROVIDER_KINDS = ['esplora', 'blockbook', 'blockcypher', 'tatum', 'insight', 'whatsonchain', 'blockchair', 'haskoin', 'kaspa', 'mvc'];
+const ENV_CHAIN_DEFAULT_DECIMALS = 8;
+const ENV_CHAIN_DEFAULT_CONCURRENCY = 5;
 /** mempool.space base url, used for the timestamp -> block lookup (`BITCOIN_MEMPOOL_API`). */
 exports.DEFAULT_MEMPOOL_API = 'https://mempool.space/api';
 /** blockchain.info multiaddr endpoint for bulk bitcoin balances (`BITCOIN_MULTIADDR_API`). */
@@ -111,15 +131,55 @@ exports.CACHE_API_CHUNK_SIZE = 700;
 const DEFAULT_CHAIN = 'bitcoin';
 /** UTXO snapshots newer than this are read from `/utxo`, older ones by replaying `/txs` */
 const RECENT_WINDOW_SECONDS = 30 * 60;
+/** True for built-in chains and for chains enabled through env (`<CHAIN>_EXPLORER_API` / `<CHAIN>_WHITELISTED_RPC`). */
 function isUtxoChain(chain) {
-    return typeof chain === 'string' && Object.prototype.hasOwnProperty.call(exports.CHAINS, chain);
+    if (typeof chain !== 'string')
+        return false;
+    if (Object.prototype.hasOwnProperty.call(exports.CHAINS, chain))
+        return true;
+    return getEnvChainConfig(chain) !== undefined;
+}
+function parseProviderKind(value, chain) {
+    if (!value)
+        return undefined;
+    const kind = value.trim().toLowerCase();
+    if (!exports.PROVIDER_KINDS.includes(kind))
+        throw new Error(`utxo: unknown provider "${value}" for ${chain} (${chain.toUpperCase()}_EXPLORER_PROVIDER), expected one of ${exports.PROVIDER_KINDS.join(', ')}`);
+    return kind;
 }
-function getConfig(chain) {
-    const config = exports.CHAINS[chain];
+/**
+ * Config for a chain that is not in `CHAINS`, built from env: `<CHAIN>_EXPLORER_API`
+ * (or `<CHAIN>_WHITELISTED_RPC`) enables it, `<CHAIN>_DECIMALS` defaults to 8 and
+ * `<CHAIN>_EXPLORER_PROVIDER` picks the dialect for unrecognised hosts (default esplora).
+ */
+function getEnvChainConfig(chain) {
+    var _a;
+    if (!/^[a-z0-9_-]+$/i.test(chain))
+        return undefined;
+    const key = chain.toUpperCase();
+    const endpoints = (0, rpc_1.toEndpointList)((0, env_1.getEnvValue)(`${key}_EXPLORER_API`));
+    if (!endpoints.length && !(0, rpc_1.toEndpointList)((0, env_1.getWhitelistedRPCs)(key)).length)
+        return undefined;
+    const decimals = (0, env_1.getEnvValue)(`${key}_DECIMALS`);
+    if (decimals !== undefined && !/^\d+$/.test(decimals.trim()))
+        throw new Error(`utxo: invalid ${key}_DECIMALS "${decimals}"`);
+    return {
+        decimals: decimals === undefined ? ENV_CHAIN_DEFAULT_DECIMALS : +decimals,
+        // env endpoints are picked up by resolveEndpoints, keep defaults empty so they are not listed twice
+        endpoints: [],
+        concurrency: ENV_CHAIN_DEFAULT_CONCURRENCY,
+        provider: (_a = parseProviderKind((0, env_1.getEnvValue)(`${key}_EXPLORER_PROVIDER`), chain)) !== null && _a !== void 0 ? _a : 'esplora',
+    };
+}
+/** Resolved config for `chain`: `CHAINS[chain]` or the env-defined config. Throws for unknown chains. */
+function getChainConfig(chain) {
+    var _a;
+    const config = (_a = exports.CHAINS[chain]) !== null && _a !== void 0 ? _a : getEnvChainConfig(chain);
     if (!config)
-        throw new Error(`utxo: unsupported chain "${chain}" (known: ${exports.utxoChains.join(', ')})`);
+        throw new Error(`utxo: unsupported chain "${chain}" (known: ${exports.utxoChains.join(', ')}; set ${String(chain).toUpperCase()}_EXPLORER_API to add it)`);
     return config;
 }
+const getConfig = getChainConfig;
 /** Explorer base urls for `chain`: env `<CHAIN>_EXPLORER_API` wins, then `CHAINS[chain].endpoints`. */
 function getEndpoints({ chain = DEFAULT_CHAIN } = {}) {
     const config = getConfig(chain);
@@ -244,7 +304,7 @@ function parseBalanceResponse(json, { address, decimals }) {
     // insight (dash): `balance` is in coins, `balanceSat` in base units
     if (json.balanceSat !== undefined)
         return toBigInt(json.balanceSat).toString();
-    // whatsonchain (bsv) / mvcapi: `{ confirmed, unconfirmed }` in base units
+    // whatsonchain (bsv) / mvcapi / haskoin (bitcoincash): `{ confirmed, unconfirmed }` in base units
     if (json.confirmed !== undefined) {
         if (typeof json.confirmed !== 'number' && typeof json.confirmed !== 'string')
             throw new Error(`utxo: unexpected balance response for ${address}`);
@@ -266,10 +326,14 @@ function parseBalanceResponse(json, { address, decimals }) {
 }
 const PROVIDERS = [
     { kind: 'blockchair', match: /blockchair\.com/i, balancePath: (a) => `/dashboards/address/${a}?limit=0` },
-    { kind: 'tatum', match: /tatum\.io/i, balancePath: (a) => `/address/balance/${a}`, headers: tatumHeaders },
+    { kind: 'tatum', match: /tatum\.io/i, balancePath: (a) => `/address/balance/${a}`, headers: tatumHeaders, keyEnv: 'TATUM_API_KEY' },
+    // nownodes `<coin>book.nownodes.io` hosts are blockbooks behind an `api-key` header
+    { kind: 'blockbook', match: /nownodes\.io/i, balancePath: (a) => `/address/${a}`, headers: nownodesHeaders, keyEnv: 'NOWNODES_API_KEY' },
     { kind: 'blockcypher', match: /blockcypher\.com/i, balancePath: (a) => `/addrs/${a}/balance` },
     { kind: 'insight', match: /insight/i, balancePath: (a) => `/addr/${a}` },
     { kind: 'whatsonchain', match: /whatsonchain\.com/i, balancePath: (a) => `/address/${a}/balance` },
+    // haskoin store (api.haskoin.com, api.blockchain.info/haskoin-store): `{ confirmed, unconfirmed }` in base units
+    { kind: 'haskoin', match: /haskoin/i, balancePath: (a) => `/address/${a}/balance` },
     { kind: 'kaspa', match: /kaspa/i, balancePath: (a) => `/addresses/${encodeURIComponent(a)}/balance` },
     { kind: 'mvc', match: /mvcapi\.com/i, balancePath: (a) => `/address/${a}/balance` },
     { kind: 'blockbook', match: /blockbook/i, balancePath: (a) => `/address/${a}` },
@@ -282,13 +346,35 @@ function tatumHeaders() {
         return undefined;
     return { 'x-api-key': key, 'User-Agent': 'Thunder Client (https://www.thunderclient.com)' };
 }
-/** Provider dialect for an endpoint; unknown hosts use the chain's first default endpoint's dialect. */
+function nownodesHeaders() {
+    const key = (0, env_1.getEnvValue)('NOWNODES_API_KEY');
+    if (!key)
+        return undefined;
+    return { 'api-key': key };
+}
+const ESPLORA_PROVIDER = PROVIDERS[PROVIDERS.length - 1];
+/** Provider for an explicitly requested dialect; keyless entries win over keyed host-specific ones. */
+function providerByKind(kind) {
+    var _a;
+    return (_a = PROVIDERS.find(p => p.kind === kind && !p.headers)) !== null && _a !== void 0 ? _a : PROVIDERS.find(p => p.kind === kind);
+}
+/**
+ * Provider dialect for an endpoint. Known hosts match directly; otherwise
+ * `<CHAIN>_EXPLORER_PROVIDER` / `config.provider` wins, then the dialect of the
+ * chain's first default endpoint, then esplora.
+ */
 function detectProvider(endpoint, chain) {
+    var _a;
     const found = PROVIDERS.find(p => p.match.test(endpoint));
     if (found)
         return found;
-    const fallback = PROVIDERS.find(p => p.match.test(getConfig(chain).endpoints[0]));
-    return fallback !== null && fallback !== void 0 ? fallback : PROVIDERS[PROVIDERS.length - 1];
+    const config = getConfig(chain);
+    const kind = (_a = parseProviderKind((0, env_1.getEnvValue)(`${chain.toUpperCase()}_EXPLORER_PROVIDER`), chain)) !== null && _a !== void 0 ? _a : config.provider;
+    if (kind)
+        return providerByKind(kind);
+    const firstDefault = config.endpoints[0];
+    const fallback = firstDefault ? PROVIDERS.find(p => p.match.test(firstDefault)) : undefined;
+    return fallback !== null && fallback !== void 0 ? fallback : ESPLORA_PROVIDER;
 }
 /** Endpoints of `chain` that speak esplora (needed for utxo / tx / block calls). */
 function esploraEndpoints(chain) {
@@ -306,7 +392,7 @@ async function esploraGet(chain, path, { retries, timeout } = {}) {
  * when all of them fail.
  */
 async function getBalance({ chain = DEFAULT_CHAIN, address, retries = 2, timeout }) {
-    var _a;
+    var _a, _b;
     const { decimals } = getConfig(chain);
     const endpoints = getEndpoints({ chain });
     const errors = [];
@@ -314,7 +400,7 @@ async function getBalance({ chain = DEFAULT_CHAIN, address, retries = 2, timeout
         const provider = detectProvider(endpoint, chain);
         const headers = provider.headers ? provider.headers() : undefined;
         if (provider.headers && !headers) {
-            (0, debugLog_1.debugLog)(`[chains.utxo] ${chain}: skipping ${endpoint}, no api key configured (TATUM_API_KEY)`);
+            (0, debugLog_1.debugLog)(`[chains.utxo] ${chain}: skipping ${endpoint}, no api key configured (${(_a = provider.keyEnv) !== null && _a !== void 0 ? _a : 'api key env'})`);
             continue;
         }
         try {
@@ -322,7 +408,7 @@ async function getBalance({ chain = DEFAULT_CHAIN, address, retries = 2, timeout
             return parseBalanceResponse(data, { address, decimals });
         }
         catch (e) {
-            const message = String((_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e).slice(0, 200);
+            const message = String((_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e).slice(0, 200);
             errors.push(`${endpoint}: ${message}`);
             (0, debugLog_1.debugLog)(`[chains.utxo] ${chain} balance error for ${address} via ${endpoint}: ${message}`);
         }