ZelCore-io · stultusmundi · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/.env.example b/.env.example
@@ -3,3 +3,8 @@ CRYPTO_COMPARE_KEY='YOUR_CRYPTOCOMPARE_API_KEY'
 LIVE_COIN_WATCH_KEY='YOUR_LIVECOINWATCH_API_KEY'
 NODE_ENV=development
 BASE_URL=http://localhost:3333
+
+# Kill switch for the Binance bStocks synthetic markets in /v2/rates.
+# Set to "false" (case-insensitive) to stop serving bstock-* entries without
+# a redeploy. Any other value, or unset, leaves them enabled.
+BSTOCKS_ENABLED=true
diff --git a/README.md b/README.md
@@ -31,6 +31,36 @@ Example: http://localhost:3333/rates
 docker run -e API_KEY=yourApiKey -p 4444:3333 zelcash/rates-api
 ```
 
+## bStocks (Binance tokenized equities)
+
+`GET /v2/rates` emits one synthetic `crypto` entry per Binance bStock — a
+tokenized US equity on BNB Smart Chain (e.g. `bstock-tslab` for Tesla). Prices
+come straight from Binance's public Spot API (no API key required):
+
+- Universe: the intersection of Binance's tokenised-asset list
+  (`GET https://www.binance.com/bapi/asset/v2/public/asset/asset/get-tokenised-asset`,
+  filtered to assets with a BSC contract) with Spot symbols currently in
+  `TRADING` status — about 56 of the ~66 listed assets qualify today.
+- Quote currency: **USDT**, not USDC — verified live, no USDC pairs exist for
+  these symbols.
+- `rates.usd` = `<CODE>USDT` last price; `rates.btc` = that price divided by
+  `BTCUSDT` from the same ticker batch (same venue, no cross-venue basis).
+  `change24h`/`change7d` come from Binance's 24h ticker and 7d rolling-window
+  ticker respectively.
+- `provider` is always the literal string `"coingecko"`, never `"binance"`.
+  The ZelCore client keys its market store on `${provider}-${id}` and the
+  sibling `api` repo advertises each bStock's `coinInfo.coingeckoID` as
+  `bstock-<code>`; the two literals only meet if the provider here is exactly
+  `"coingecko"`. This is a cross-repo contract — do not change it in
+  isolation.
+- Binance does **not** omit a halted symbol (e.g. during a stock split) from
+  its ticker response — it returns the symbol present with
+  `lastPrice: "0.00000000"`. Prices are therefore accepted only when finite
+  and strictly positive; a halted/zero-priced symbol keeps serving its last
+  known-good price rather than a stale zero or a dropped entry, per the
+  bStocks partner guide's "display-only during halts is acceptable" allowance.
+- Toggle via `config.bStocksEnabled` (`config/index.ts`).
+
 ## Update Documentation
 
 To update typedoc documentation please run.

diff --git a/config/index.ts b/config/index.ts
@@ -11,6 +11,20 @@ export const config = {
   liveCoinWatchUrl: 'https://api.livecoinwatch.com/',
   zelCoinsUrl: 'https://raw.githubusercontent.com/ZelCore-io/Zelcore/master/coins.json',
   zelCoinInfoUrl: 'https://raw.githubusercontent.com/ZelCore-io/Zelcore/master/coininfo.json',
+  binanceApiUrl: 'https://api.binance.com/',
+  binanceAssetUrl: 'https://www.binance.com/',
+  // Env kill switch: disabling in production should not require a code
+  // change + redeploy. Defaults to enabled when unset.
+  bStocksEnabled: (process.env.BSTOCKS_ENABLED ?? '').toLowerCase() !== 'false',
+  // How long a failed Binance request (tokenised-asset list / trading-symbol
+  // set) is negatively-cached before retrying, so an outage doesn't re-spend
+  // the full AxiosWrapper retry budget on every 30s refresh cycle.
+  binanceFailureCacheMs: 60 * 1000,
+  // How long a bStock's last-known-good price is served after Binance stops
+  // pricing it fresh. The outage this exists for (a stock split halt,
+  // exchange maintenance) is naturally multi-day, so this is deliberately far
+  // longer than the ticker windows themselves.
+  bstocksLastGoodMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
 };
 
 export default config;
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
-**rates-api v3.0.0** • [**Docs**](modules.md)
+**rates-api v3.0.0**
 
 ***
 
@@ -35,6 +35,36 @@ Example: http://localhost:3333/rates
 docker run -e API_KEY=yourApiKey -p 4444:3333 zelcash/rates-api
 ```
 
+## bStocks (Binance tokenized equities)
+
+`GET /v2/rates` emits one synthetic `crypto` entry per Binance bStock — a
+tokenized US equity on BNB Smart Chain (e.g. `bstock-tslab` for Tesla). Prices
+come straight from Binance's public Spot API (no API key required):
+
+- Universe: the intersection of Binance's tokenised-asset list
+  (`GET https://www.binance.com/bapi/asset/v2/public/asset/asset/get-tokenised-asset`,
+  filtered to assets with a BSC contract) with Spot symbols currently in
+  `TRADING` status — about 56 of the ~66 listed assets qualify today.
+- Quote currency: **USDT**, not USDC — verified live, no USDC pairs exist for
+  these symbols.
+- `rates.usd` = `<CODE>USDT` last price; `rates.btc` = that price divided by
+  `BTCUSDT` from the same ticker batch (same venue, no cross-venue basis).
+  `change24h`/`change7d` come from Binance's 24h ticker and 7d rolling-window
+  ticker respectively.
+- `provider` is always the literal string `"coingecko"`, never `"binance"`.
+  The ZelCore client keys its market store on `${provider}-${id}` and the
+  sibling `api` repo advertises each bStock's `coinInfo.coingeckoID` as
+  `bstock-<code>`; the two literals only meet if the provider here is exactly
+  `"coingecko"`. This is a cross-repo contract — do not change it in
+  isolation.
+- Binance does **not** omit a halted symbol (e.g. during a stock split) from
+  its ticker response — it returns the symbol present with
+  `lastPrice: "0.00000000"`. Prices are therefore accepted only when finite
+  and strictly positive; a halted/zero-priced symbol keeps serving its last
+  known-good price rather than a stale zero or a dropped entry, per the
+  bStocks partner guide's "display-only during halts is acceptable" allowance.
+- Toggle via `config.bStocksEnabled` (`config/index.ts`).
+
 ## Update Documentation
 
 To update typedoc documentation please run.

diff --git a/docs/index/README.md b/docs/index/README.md
@@ -1,7 +1,7 @@
-[**rates-api v3.0.0**](../README.md) • **Docs**
+[**rates-api v3.0.0**](../README.md)
 
 ***
 
-[rates-api v3.0.0](../modules.md) / index
+[rates-api](../modules.md) / index
 
 # index
diff --git a/docs/modules.md b/docs/modules.md
@@ -1,4 +1,4 @@
-[**rates-api v3.0.0**](README.md) • **Docs**
+[**rates-api v3.0.0**](README.md)
 
 ***
 
@@ -14,9 +14,11 @@
 - [src/lib/utils](src/lib/utils/README.md)
 - [src/routes](src/routes/README.md)
 - [src/services/apiServices](src/services/apiServices/README.md)
+- [src/services/bstocks](src/services/bstocks/README.md)
 - [src/services/coinAggregatorIDs](src/services/coinAggregatorIDs/README.md)
 - [src/services/newContracts](src/services/newContracts/README.md)
 - [src/services/providers](src/services/providers/README.md)
+- [src/services/providers/binance](src/services/providers/binance/README.md)
 - [src/services/providers/bitpay](src/services/providers/bitpay/README.md)
 - [src/services/providers/coinGecko](src/services/providers/coinGecko/README.md)
 - [src/services/providers/cryptoCompare](src/services/providers/cryptoCompare/README.md)

diff --git a/docs/src/lib/axios/README.md b/docs/src/lib/axios/README.md
@@ -1,14 +1,12 @@
-[**rates-api v3.0.0**](../../../README.md) • **Docs**
+[**rates-api v3.0.0**](../../../README.md)
 
 ***
 
-[rates-api v3.0.0](../../../modules.md) / src/lib/axios
+[rates-api](../../../modules.md) / src/lib/axios
 
 # src/lib/axios
 
-## Index
-
-### Classes
+## Classes
 
 - [AxiosWrapper](classes/AxiosWrapper.md)
 

diff --git a/docs/src/lib/axios/classes/AxiosWrapper.md b/docs/src/lib/axios/classes/AxiosWrapper.md
@@ -1,11 +1,13 @@
-[**rates-api v3.0.0**](../../../../README.md) • **Docs**
+[**rates-api v3.0.0**](../../../../README.md)
 
 ***
 
-[rates-api v3.0.0](../../../../modules.md) / [src/lib/axios](../README.md) / AxiosWrapper
+[rates-api](../../../../modules.md) / [src/lib/axios](../README.md) / AxiosWrapper
 
 # Class: AxiosWrapper
 
+Defined in: src/lib/axios.ts:26
+
 A wrapper around Axios to handle automatic retries and customizable configurations.
 
 This class provides a simplified interface over Axios, adding automatic retry functionality
@@ -31,55 +33,65 @@ apiClient.post('/users', { name: 'John Doe' })
 
 ## Constructors
 
-### new AxiosWrapper()
+### Constructor
+
+> **new AxiosWrapper**(`baseURL`, `maxRetries?`, `timeout?`): `AxiosWrapper`
 
-> **new AxiosWrapper**(`baseURL`, `maxRetries`, `timeout`): [`AxiosWrapper`](AxiosWrapper.md)
+Defined in: src/lib/axios.ts:43
 
 Creates an instance of AxiosWrapper.
 
 #### Parameters
 
-• **baseURL**: `string`
+##### baseURL
+
+`string`
 
 The base URL for all requests.
 
-• **maxRetries**: `number` = `3`
+##### maxRetries?
+
+`number` = `3`
 
 The maximum number of retry attempts for failed requests (default is 3).
 
-• **timeout**: `number` = `5000`
+##### timeout?
+
+`number` = `5000`
 
 The timeout in milliseconds for requests (default is 5000 ms).
 
 #### Returns
 
-[`AxiosWrapper`](AxiosWrapper.md)
+`AxiosWrapper`
 
 #### Example
 
 ```typescript
 const apiClient = new AxiosWrapper('https://api.example.com', 5, 10000);
 ```
 
-#### Defined in
-
-[src/lib/axios.ts:43](https://github.com/ZelCore-io/rates-api/blob/6ee8192dea404fd0a0f6ba9b7352f3b7673523eb/src/lib/axios.ts#L43)
-
 ## Methods
 
 ### delete()
 
-> **delete**(`url`, `config`?): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+> **delete**(`url`, `config?`): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+
+Defined in: src/lib/axios.ts:171
 
 Performs a DELETE request.
 
 #### Parameters
 
-• **url**: `string`
+##### url
+
+`string`
 
 The URL to send the DELETE request to.
 
-• **config?**: `AxiosRequestConfig`\<`any`\>
+##### config?
+
+`AxiosRequestConfig`\<`any`\>
 
 Optional Axios request configuration.
 
@@ -97,25 +109,27 @@ apiClient.delete('/users/123')
   .catch(error => console.error(error));
 ```
 
-#### Defined in
-
-[src/lib/axios.ts:171](https://github.com/ZelCore-io/rates-api/blob/6ee8192dea404fd0a0f6ba9b7352f3b7673523eb/src/lib/axios.ts#L171)
-
 ***
 
 ### get()
 
-> **get**(`url`, `config`?): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+> **get**(`url`, `config?`): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+
+Defined in: src/lib/axios.ts:115
 
 Performs a GET request.
 
 #### Parameters
 
-• **url**: `string`
+##### url
+
+`string`
 
 The URL to send the GET request to.
 
-• **config?**: `AxiosRequestConfig`\<`any`\>
+##### config?
+
+`AxiosRequestConfig`\<`any`\>
 
 Optional Axios request configuration.
 
@@ -133,29 +147,33 @@ apiClient.get('/users')
   .catch(error => console.error(error));
 ```
 
-#### Defined in
-
-[src/lib/axios.ts:115](https://github.com/ZelCore-io/rates-api/blob/6ee8192dea404fd0a0f6ba9b7352f3b7673523eb/src/lib/axios.ts#L115)
-
 ***
 
 ### post()
 
-> **post**(`url`, `data`?, `config`?): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+> **post**(`url`, `data?`, `config?`): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+
+Defined in: src/lib/axios.ts:134
 
 Performs a POST request.
 
 #### Parameters
 
-• **url**: `string`
+##### url
+
+`string`
 
 The URL to send the POST request to.
 
-• **data?**: `any`
+##### data?
+
+`any`
 
 The data to send with the POST request.
 
-• **config?**: `AxiosRequestConfig`\<`any`\>
+##### config?
+
+`AxiosRequestConfig`\<`any`\>
 
 Optional Axios request configuration.
 
@@ -173,29 +191,33 @@ apiClient.post('/users', { name: 'John Doe' })
   .catch(error => console.error(error));
 ```
 
-#### Defined in
-
-[src/lib/axios.ts:134](https://github.com/ZelCore-io/rates-api/blob/6ee8192dea404fd0a0f6ba9b7352f3b7673523eb/src/lib/axios.ts#L134)
-
 ***
 
 ### put()
 
-> **put**(`url`, `data`?, `config`?): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+> **put**(`url`, `data?`, `config?`): `Promise`\<`AxiosResponse`\<`any`, `any`\>\>
+
+Defined in: src/lib/axios.ts:153
 
 Performs a PUT request.
 
 #### Parameters
 
-• **url**: `string`
+##### url
+
+`string`
 
 The URL to send the PUT request to.
 
-• **data?**: `any`
+##### data?
+
+`any`
 
 The data to send with the PUT request.
 
-• **config?**: `AxiosRequestConfig`\<`any`\>
+##### config?
+
+`AxiosRequestConfig`\<`any`\>
 
 Optional Axios request configuration.
 
@@ -212,7 +234,3 @@ apiClient.put('/users/123', { name: 'Jane Doe' })
   .then(response => console.log(response.data))
   .catch(error => console.error(error));
 ```
-
-#### Defined in
-
-[src/lib/axios.ts:153](https://github.com/ZelCore-io/rates-api/blob/6ee8192dea404fd0a0f6ba9b7352f3b7673523eb/src/lib/axios.ts#L153)
diff --git a/docs/src/lib/objects/README.md b/docs/src/lib/objects/README.md
@@ -1,13 +1,12 @@
-[**rates-api v3.0.0**](../../../README.md) • **Docs**
+[**rates-api v3.0.0**](../../../README.md)
 
 ***
 
-[rates-api v3.0.0](../../../modules.md) / src/lib/objects
+[rates-api](../../../modules.md) / src/lib/objects
 
 # src/lib/objects
 
-## Index
-
-### Functions
+## Functions
 
 - [mergeDeep](functions/mergeDeep.md)
+- [replaceCryptoByKey](functions/replaceCryptoByKey.md)