HiveTechDev · HiveTechDev · Oct 18, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,16 @@
+# Bitcore Monorepo Documentation
+
+This folder aggregates public APIs, SDKs, and UI components across packages.
+
+- API
+  - [Bitcore Node REST API](./api/bitcore-node.md)
+  - [Bitcore Wallet Service API](./api/bitcore-wallet-service.md)
+- SDK
+  - [bitcore-wallet-client](./sdk/bitcore-wallet-client.md)
+  - [crypto-wallet-core](./sdk/crypto-wallet-core.md)
+- UI
+  - [Insight components](./ui/insight-components.md)
+
+Notes:
+- Base repository scripts are in `package.json`.
+- Existing package-specific docs remain under their packages (e.g., `packages/bitcore-node/docs/`). This folder consolidates and links cross-package usage.
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -0,0 +1,4 @@
+# API Documentation Index
+
+- [Bitcore Node REST API](./bitcore-node.md)
+- [Bitcore Wallet Service API](./bitcore-wallet-service.md)
diff --git a/docs/api/bitcore-node.md b/docs/api/bitcore-node.md
@@ -0,0 +1,92 @@
+# Bitcore Node REST API
+
+Base URL pattern: `/api/:chain/:network/...`
+- `:chain`: BTC | BCH | ETH | MATIC | XRP | DOGE | LTC
+- `:network`: mainnet | testnet (lowercase)
+
+Authentication: Most endpoints are public; wallet endpoints require JWT via `Auth.authenticateMiddleware`.
+
+## Address
+- GET `/:chain/:network/address/:address` — UTXOs
+  - Query: `unspent=true`, `limit`, `since`
+- GET `/:chain/:network/address/:address/txs` — transactions (stream)
+- GET `/:chain/:network/address/:address/coins` — coins (stream)
+- GET `/:chain/:network/address/:address/balance` — { confirmed, unconfirmed, balance }
+
+Example:
+```bash
+curl "http://localhost:3000/api/BTC/mainnet/address/12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX/balance"
+```
+
+## Transactions
+- GET `/:chain/:network/tx` — list by `blockHeight` or `blockHash`
+  - Query: `blockHeight` or `blockHash`, `limit`, `since`, `direction`, `paging`
+- GET `/:chain/:network/tx/:txId`
+- GET `/:chain/:network/tx/:txId/populated` — includes input/output coins
+- GET `/:chain/:network/tx/:txId/authhead`
+- GET `/:chain/:network/tx/:txid/coins`
+- POST `/:chain/:network/tx/send` — broadcast raw tx
+  - Body: `{ "rawTx": "<hex>" }`
+
+Example broadcast:
+```bash
+curl -X POST "http://localhost:3000/api/BTC/mainnet/tx/send" \
+  -H 'Content-Type: application/json' \
+  -d '{"rawTx":"<hex>"}'
+```
+
+## Blocks
+- GET `/:chain/:network/block` — stream blocks (query: `sinceBlock`, `date`, `limit`, `since`, `direction`, `paging`)
+- GET `/:chain/:network/block/tip` — current height
+- GET `/:chain/:network/block/:blockId`
+- GET `/:chain/:network/block/:blockHash/coins/:limit/:pgnum` — txids, inputs, outputs for block
+- GET `/:chain/:network/block/before-time/:time` — block prior to timestamp
+
+Example:
+```bash
+curl "http://localhost:3000/api/BTC/mainnet/block/tip"
+```
+
+## Fees
+- GET `/:chain/:network/fee/:target` — dynamic fee for target blocks (0–100)
+
+## Stats
+- GET `/:chain/:network/stats/daily-transactions` — daily tx counts
+
+## Status
+Base: `/api/status`
+- GET `/enabled-chains` — enabled {chain,network}
+- GET `/performance` — performance tracker info
+- GET `/:chain/:network/sync` — { initialSyncComplete }
+
+## EVM chain helpers (ETH)
+Base: defined in `modules/ethereum/api/eth-routes.ts`
+- GET `/api/ETH/:network/address/:address/txs/count` — current nonce
+- POST `/api/ETH/:network/gas` — estimate gas
+  - Body: `{ from, to, value, data, gasPrice }`
+- GET `/api/ETH/:network/token/:tokenAddress` — ERC20 token info
+- GET `/api/ETH/:network/token/:tokenAddress/allowance/:ownerAddress/for/:spenderAddress`
+- Multisig (Gnosis Safe):
+  - GET `/api/ETH/:network/ethmultisig/info/:multisigContractAddress`
+  - GET `/api/ETH/:network/ethmultisig/:sender/instantiation/:txId`
+  - GET `/api/ETH/:network/ethmultisig/txps/:multisigContractAddress`
+  - GET `/api/ETH/:network/ethmultisig/transactions/:multisigContractAddress` (stream)
+
+Example estimateGas:
+```bash
+curl -X POST "http://localhost:3000/api/ETH/mainnet/gas" \
+  -H 'Content-Type: application/json' \
+  -d '{"from":"0x...","to":"0x...","value":"0x0","data":"0x","gasPrice":"0x3b9aca00"}'
+```
+
+## EVM chain helpers (MATIC)
+Base: `modules/matic/api/matic-routes.ts` — same shapes as ETH with chain `MATIC`.
+- Nonce, gas, token info
+- Multisig info, instantiation, txps, transactions (stream)
+
+## XRP helpers
+- GET `/api/XRP/:network/address/:address/txs/count` — account nonce
+
+## Notes
+- Full examples for many endpoints exist in `packages/bitcore-node/docs/api-documentation.md`.
+- Streaming routes keep connections open to push data; prefer a client that can handle chunked responses.
diff --git a/docs/api/bitcore-wallet-service.md b/docs/api/bitcore-wallet-service.md
@@ -0,0 +1,118 @@
+# Bitcore Wallet Service (BWS) API
+
+Base URL: `/bws/api`
+Auth: Most endpoints require headers `x-identity`, `x-signature`, optional `x-session`. See client SDK for signing.
+
+## Common headers
+- `x-client-version`: client version string
+- `User-Agent`: propagated to service
+
+## Version and Status
+- GET `/v1/version/` — service version
+- GET `/latest-version` — latest Copay/Wallet app version (cached)
+
+## Wallet lifecycle
+- POST `/v2/wallets/` — create wallet
+- POST `/v2/wallets/:id/copayers/` — join wallet
+- GET `/v3/wallets/` — get status for current wallet
+- GET `/v1/wallets/all/` — batch status for multiple identities (header `x-identities`)
+- GET `/v1/wallets/:identifier/` — support-staff lookup
+
+Example create wallet:
+```bash
+curl -X POST "$BWS/v2/wallets/" \
+  -H 'Content-Type: application/json' \
+  -H "x-identity: <pubkey>" -H "x-signature: <sig>" \
+  -d '{"name":"My Wallet","m":1,"n":1,"network":"livenet","coin":"btc"}'
+```
+
+## Preferences
+- GET `/v1/preferences/`
+- PUT `/v1/preferences`
+
+## Addresses
+- POST `/v4/addresses/` — create address
+- GET `/v1/addresses/` — list addresses (`limit`, `reverse`)
+- POST `/v1/addresses/scan/` — start gap-limit scan
+
+## Balance and UTXOs
+- GET `/v1/balance/` — optional `coin`, `tokenAddress`, `multisigContractAddress`, `twoStep`
+- GET `/v1/utxos/` — optional `addresses=comma,separated`
+- GET `/v1/txcoins/` — `txId`
+- GET `/v1/sendmaxinfo/` — compute send-max with fee options
+
+## Fee levels and gas
+- GET `/v2/feelevels/` — `coin|chain`, `network`
+- POST `/v3/estimateGas/` — EVM gas estimation via wallet context
+
+## Tx proposals (TXPs)
+- POST `/v3/txproposals/` — create txp
+- POST `/v2/txproposals/:id/publish/`
+- POST `/v1/txproposals/:id/signatures/` — deprecated
+- POST `/v2/txproposals/:id/signatures/` — sign (supports BCH Schnorr)
+- POST `/v1/txproposals/:id/broadcast/`
+- DELETE `/v1/txproposals/:id/`
+- GET `/v1/txproposals/:id/`
+- GET `/v2/txproposals/` — pending txps
+- GET `/v1/txhistory/` — history (`skip`, `limit`, `tokenAddress`, `multisigContractAddress`, `includeExtendedInfo`)
+- POST `/v1/broadcast_raw/` — broadcast raw tx
+
+Example create+sign+publish (flow outline):
+```bash
+# 1) create
+curl -X POST "$BWS/v3/txproposals/" -H "x-identity: ..." -H "x-signature: ..." \
+  -H 'Content-Type: application/json' -d '{"toAddress":"...","amount":10000,"coin":"btc","message":"test"}'
+# 2) sign (client generates signatures and posts)
+curl -X POST "$BWS/v2/txproposals/<txpId>/signatures/" -H "x-identity: ..." -H "x-signature: ..." \
+  -H 'Content-Type: application/json' -d '{"signatures":["<hex>"],"maxTxpVersion":3,"supportBchSchnorr":true}'
+# 3) publish/broadcast
+curl -X POST "$BWS/v1/txproposals/<txpId>/publish/" -H "x-identity: ..." -H "x-signature: ..."
+```
+
+## Notifications and notes
+- GET `/v1/notifications/` — poll with `timeSpan`, `notificationId`
+- GET `/v1/txnotes/:txid`
+- PUT `/v1/txnotes/:txid/`
+- GET `/v1/txnotes/` — optional `minTs`
+
+## Auth and sessions
+- POST `/v1/login/`
+- POST `/v1/logout/`
+
+## Rates
+- GET `/v1/fiatrates/:code/`
+- GET `/v2/fiatrates/:code/`
+- GET `/v3/fiatrates/`
+- GET `/v3/fiatrates/:coin/`
+
+## Utilities
+- GET `/v1/nonce/:address` — EVM nonce
+- POST `/v1/clearcache/`
+
+## Third-party services
+- OneInch DEX: GET `/v1/service/oneInch/getReferrerFee`, POST `/v1/service/oneInch/getSwap/:chain?`, GET `/v1/service/oneInch/getTokens/:chain?`
+- Moonpay: POST `/v1/service/moonpay/*`
+- Ramp: POST `/v1/service/ramp/*`
+- Simplex: POST `/v1/service/simplex/*`, GET `/v1/service/simplex/events`
+- Wyre: POST `/v1/service/wyre/*`
+- Changelly: POST `/v1/service/changelly/*`
+- PayId: GET `/v1/service/payId/:payId`
+- DEX spender whitelist: GET `/v1/services/dex/getSpenderApprovalWhitelist`
+- Services data: GET `/v1/services`
+- Availability: POST `/v1/service/checkAvailability`
+
+## Advertisements (staff)
+- POST `/v1/advertisements/`
+- GET `/v1/advertisements/`
+- GET `/v1/advertisements/:adId/`
+- GET `/v1/advertisements/country/:country`
+- POST `/v1/advertisements/:adId/activate`
+- POST `/v1/advertisements/:adId/deactivate`
+- DELETE `/v1/advertisements/:adId/`
+
+## Deprecated endpoints
+Numerous v1/v2 routes are retained for legacy clients (e.g., `/v1/feelevels/`, `/v1/addresses/`, `/v1/txproposals/`). Prefer the v2/v3 variants above.
+
+Notes:
+- All authenticated requests must be signed (see client SDK for `x-signature` message format).
+- Rate limiting applies to some endpoints (wallet creation, fee levels).
diff --git a/docs/sdk/bitcore-wallet-client.md b/docs/sdk/bitcore-wallet-client.md
@@ -0,0 +1,52 @@
+# bitcore-wallet-client (BWC)
+
+JavaScript/TypeScript client for Bitcore Wallet Service.
+
+## Key classes
+- `API` — main client, extends EventEmitter (polls notifications)
+- `Key` — HD seed manager (mnemonic/xprv), derives `Credentials`
+- `Credentials` — serializable wallet identity (chain, network, xpub, request keys)
+- `Request` — HTTP wrapper used by API
+- `Verifier`, `Utils`, `PayPro`, `PayProV2`, `BulkClient` — helpers
+
+## Quickstart
+```ts
+import { API, Key } from 'bitcore-wallet-client';
+
+// 1) Point to your BWS instance
+const client = new API({ baseUrl: 'http://localhost:3232/bws/api', logLevel: 'info' });
+
+// 2) Create a new seed and derive credentials (single-sig BTC, livenet, account 0)
+const key = new Key({ seedType: 'new' });
+const credentials = key.createCredentials(undefined, {
+  coin: 'btc', chain: 'btc', network: 'livenet', account: 0, n: 1
+});
+
+// 3) Attach credentials to client
+client.fromObj(credentials.toObj());
+
+// 4) Create a wallet (server enforces auth via headers built by client)
+client['request'].post('/v2/wallets/', { // or use high-level API methods if available
+  name: 'My Wallet', m: 1, n: 1, network: 'livenet', coin: 'btc'
+}, (err, res) => { /* ... */ });
+```
+
+## Notifications
+```ts
+client.initialize({ notificationIncludeOwn: true }, () => {
+  client.on('notification', n => console.log('notification', n));
+});
+```
+
+## Common flows (outline)
+- Create/join wallet: POST `/v2/wallets/`, then `/v2/wallets/:id/copayers/`
+- Create address: POST `/v4/addresses/`
+- Balance: GET `/v1/balance/`
+- UTXOs: GET `/v1/utxos/`
+- Create TXP: POST `/v3/txproposals/`
+- Sign TXP: POST `/v2/txproposals/:id/signatures/` (signatures generated using `Key` + `Utils`)
+- Publish/broadcast: POST `/v1/txproposals/:id/publish/` then `/v1/txproposals/:id/broadcast/`
+
+Notes:
+- See `Credentials.FIELDS` for serializable fields and `Key` for encryption helpers.
+- The client sets required headers/signatures automatically using the attached credentials.
diff --git a/docs/sdk/crypto-wallet-core.md b/docs/sdk/crypto-wallet-core.md
@@ -0,0 +1,56 @@
+# crypto-wallet-core (CWC)
+
+Utility SDK for derivation, validation, and transaction building.
+
+## Modules and key exports
+- `DeriverProxy` — derive addresses/keys across chains
+- `ValidationProxy` — address and URI validators per chain
+- `TransactionsProxy` — create/sign/get hash/apply signature for chain-specific transactions
+- `Paths` — derivation base paths per chain/network
+
+Chains supported: BTC, BCH, ETH, XRP, DOGE, LTC, MATIC (and ERC20/MULTISIG variants via providers)
+
+## Derivation
+```ts
+import Deriver from 'crypto-wallet-core/dist/derivation';
+
+const xpub = 'xpub...';
+const address = Deriver.deriveAddress('BTC', 'livenet', xpub, 0, false);
+
+const xpriv = 'xprv...';
+const { privKey, pubKey, address: ethAddr } = Deriver.derivePrivateKey(
+  'ETH', 'livenet', xpriv, 0, false
+);
+```
+
+## Validation
+```ts
+import Validation from 'crypto-wallet-core/dist/validation';
+
+const ok = Validation.validateAddress('BTC', 'mainnet', '12c6DSiU4Rq3P4Zx...');
+const validUri = Validation.validateUri('ETH', 'ethereum:0xabc...?value=1e18');
+```
+
+## Transactions
+```ts
+import Tx from 'crypto-wallet-core/dist/transactions';
+
+// Create a BTC tx
+const btcHex = Tx.create({
+  chain: 'BTC',
+  inputs: [{ txid: '...', vout: 0, script: '...', satoshis: 10000 }],
+  outputs: [{ toAddress: '1abc...', satoshis: 9000 }],
+  change: { address: '1chg...' }
+});
+
+// Sign EVM tx
+const sig = Tx.getSignature({
+  chain: 'ETH',
+  tx: '0x02f8...',
+  key: { privKey: '<hex>', pubKey: '<hex>' }
+});
+```
+
+Notes:
+- For ERC20/MULTISIG/MATIC variants, set `chain` to the appropriate key listed in `transactions/index.ts`.
+- Address derivation base paths are exposed via `Deriver.pathFor(chain, network, account)`.
diff --git a/docs/ui/insight-components.md b/docs/ui/insight-components.md
@@ -0,0 +1,35 @@
+# Insight UI Components
+
+Public React components/pages exported by `packages/insight`.
+
+## Pages
+- `pages/index.tsx` — Home
+- `pages/search.tsx` — Search results
+- `pages/address.tsx` — Address view
+- `pages/block.tsx` — Block view
+- `pages/blocks.tsx` — Recent blocks
+- `pages/transaction.tsx` — Transaction view
+
+Usage (React Router example):
+```tsx
+<Route path=":" element={<Layout />}> {/* layout wrapper */}
+  <Route index element={<Home />} />
+  <Route path=":currency/:network/address/:address" element={<Address />} />
+  <Route path=":currency/:network/block/:block" element={<Block />} />
+  <Route path=":currency/:network/tx/:txid" element={<TransactionHash />} />
+</Route>
+```
+
+## Components
+- Layout: default export `components/layout.tsx` (wraps header/footer, parallax background)
+- BlockDetails: default export `components/block-details.tsx`
+  - Props: `{ currency: string; network: string; block: string }`
+- TransactionDetails: default export `components/transaction-details.tsx`
+  - Props: `{ transaction: Transaction; currency: string; network: string; refTxid?: string; refVout?: number }`
+- EthBlockDetails, TransactionDetailsEth — ETH-specific views
+- Header, Footer, Body, Search, Info, ThemeChanger
+- Utility components: CopyText, InfiniteScrollLoadSpinner, Coin, CoinList, TransactionSummary
+
+Notes:
+- Data is fetched from Bitcore Node API via `packages/insight/src/api/api.ts` fetcher (axios + SWR patterns).
+- Styled components in `assets/styles/*` provide theming (light/dark) and layout primitives.