@rlajous/sdk-threat 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Webacy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# @rlajous/sdk-threat
+
+Threat and risk analysis SDK for the Webacy Risk Score API. Analyze addresses, contracts, and URLs for security risks.
+
+## Installation
+
+```bash
+npm install @rlajous/sdk-threat
+```
+
+Or install the full SDK:
+
+```bash
+npm install @rlajous/sdk
+```
+
+## Quick Start
+
+```typescript
+import { ThreatClient, RiskModule } from '@rlajous/sdk-threat';
+
+const client = new ThreatClient({
+  apiKey: process.env.WEBACY_API_KEY!,
+});
+
+// Analyze address risk
+const risk = await client.addresses.analyze('0x742d35Cc...', {
+  chain: 'eth',
+});
+
+console.log(`Risk Score: ${risk.overallRisk}/100`);
+console.log(`High severity issues: ${risk.high}`);
+```
+
+## Features
+
+### Address Risk Analysis
+
+Comprehensive security analysis for blockchain addresses.
+
+```typescript
+const risk = await client.addresses.analyze('0x742d35Cc...', {
+  chain: 'eth',
+  modules: [RiskModule.FUND_FLOW_SCREENING, RiskModule.SANCTIONS_COMPLIANCE],
+  detailed: true,
+});
+
+console.log(`Overall Risk: ${risk.overallRisk}/100`);
+console.log(`Is Contract: ${risk.isContract}`);
+console.log(`Address Type: ${risk.addressType}`);
+console.log(`High Issues: ${risk.high}`);
+console.log(`Medium Issues: ${risk.medium}`);
+
+// Detailed fund flow analysis
+if (risk.details?.fund_flows?.risk) {
+  const flowRisk = risk.details.fund_flows.risk;
+  if (flowRisk.ofac) console.log('Connected to OFAC addresses');
+  if (flowRisk.tornado) console.log('Used Tornado Cash');
+  if (flowRisk.mixers) console.log('Used mixing services');
+}
+```
+
+### Sanctions Screening
+
+Screen addresses against OFAC and other sanctions lists.
+
+```typescript
+const result = await client.addresses.checkSanctioned('0x...', {
+  chain: 'eth',
+});
+
+if (result.is_sanctioned) {
+  console.log('Address is sanctioned!');
+  console.log(`Source: ${result.sanction_details?.source}`);
+  console.log(`List: ${result.sanction_details?.list_name}`);
+}
+```
+
+### Address Poisoning Detection
+
+Detect dust attack and address poisoning attempts.
+
+```typescript
+const result = await client.addresses.checkPoisoning('0x...', {
+  chain: 'eth',
+});
+
+if (result.is_poisoned) {
+  console.log('Poisoning detected!');
+  console.log(`Similar addresses: ${result.poisoning_details?.similar_addresses?.length}`);
+  console.log(`Dust transactions: ${result.poisoning_details?.dust_tx_count}`);
+}
+```
+
+### Contract Analysis
+
+Analyze smart contracts for vulnerabilities.
+
+```typescript
+const contract = await client.contracts.analyze('0xContract...', {
+  chain: 'eth',
+});
+
+console.log(`Risk Score: ${contract.overallRisk}/100`);
+console.log(`Verified: ${contract.is_verified}`);
+
+// Vulnerabilities
+for (const vuln of contract.vulnerabilities || []) {
+  console.log(`${vuln.severity}: ${vuln.name}`);
+}
+
+// Get source code
+const source = await client.contracts.getSourceCode('0xContract...', {
+  chain: 'eth',
+});
+
+// Get buy/sell taxes
+const taxes = await client.contracts.getTaxes('0xToken...', {
+  chain: 'eth',
+});
+console.log(`Buy Tax: ${taxes.buy_tax}%`);
+console.log(`Sell Tax: ${taxes.sell_tax}%`);
+```
+
+### URL Safety
+
+Check URLs for phishing and malware.
+
+```typescript
+const result = await client.url.check('https://suspicious-site.com');
+
+if (result.is_malicious) {
+  console.log(`Risk Score: ${result.risk_score}/100`);
+  console.log(`Threats: ${result.threat_types?.join(', ')}`);
+}
+
+// Report a malicious URL
+await client.url.add('https://phishing-site.xyz');
+```
+
+### Wallet Analysis
+
+Analyze wallet transactions and token approvals.
+
+```typescript
+// Get recent transactions
+const txs = await client.wallets.getTransactions('0x...', {
+  chain: 'eth',
+  limit: 10,
+});
+
+// Get token approvals
+const approvals = await client.wallets.getApprovals('0x...', {
+  chain: 'eth',
+});
+
+for (const approval of approvals.approvals || []) {
+  console.log(`${approval.token_symbol}: ${approval.amount}`);
+  if (approval.risk_score > 70) {
+    console.log('  ⚠️ High risk approval!');
+  }
+}
+```
+
+### Ledger Scan
+
+Scan hardware wallet transactions for security.
+
+```typescript
+const scan = await client.ledger.scanTransaction('ethereum', {
+  tx: {
+    from: '0x...',
+    to: '0x...',
+    data: '0x...',
+  },
+  chain: 1,
+});
+
+console.log(`Risk Level: ${scan.risk_level}`);
+for (const warning of scan.warnings || []) {
+  console.log(`Warning: ${warning}`);
+}
+```
+
+### Account Trace
+
+Trace fund flows for an address.
+
+```typescript
+const trace = await client.accountTrace.trace('0x...', {
+  chain: 'eth',
+});
+
+console.log(`Traced transactions: ${trace.transactions?.length}`);
+```
+
+### API Usage
+
+Monitor your API usage and quota.
+
+```typescript
+const usage = await client.usage.getCurrent();
+console.log(`Requests used: ${usage.requests_used}`);
+console.log(`Requests limit: ${usage.requests_limit}`);
+```
+
+## API Reference
+
+### ThreatClient
+
+```typescript
+const client = new ThreatClient({
+  apiKey: string;           // Required: Your Webacy API key
+  baseUrl?: string;         // Optional: Custom API URL
+  timeout?: number;         // Optional: Request timeout (ms)
+  retry?: RetryConfig;      // Optional: Retry configuration
+});
+```
+
+### Resources
+
+| Resource | Method | Description |
+|----------|--------|-------------|
+| `addresses` | `analyze(address, options)` | Analyze address risk |
+| `addresses` | `checkSanctioned(address, options)` | Check sanctions status |
+| `addresses` | `checkPoisoning(address, options)` | Check for poisoning |
+| `contracts` | `analyze(address, options)` | Analyze contract risk |
+| `contracts` | `getSourceCode(address, options)` | Get contract source |
+| `contracts` | `getTaxes(address, options)` | Get token taxes |
+| `contracts` | `analyzeSolidity(body)` | Analyze Solidity code |
+| `url` | `check(url)` | Check URL safety |
+| `url` | `add(url)` | Report malicious URL |
+| `wallets` | `getTransactions(address, options)` | Get wallet transactions |
+| `wallets` | `getApprovals(address, options)` | Get token approvals |
+| `ledger` | `scanTransaction(family, body)` | Scan Ledger transaction |
+| `ledger` | `scanEip712(family, body)` | Scan EIP-712 message |
+| `accountTrace` | `trace(address, options)` | Trace fund flows |
+| `usage` | `getUsage(options)` | Get usage history |
+| `usage` | `getCurrent()` | Get current usage |
+| `usage` | `getPlans()` | Get available plans |
+
+## Risk Modules
+
+```typescript
+import { RiskModule } from '@rlajous/sdk-threat';
+
+const modules = [
+  RiskModule.FUND_FLOW_SCREENING,
+  RiskModule.SANCTIONS_COMPLIANCE,
+  RiskModule.CONTRACT_ANALYSIS,
+  RiskModule.TOKEN_SECURITY,
+  // ... and more
+];
+```
+
+## Supported Chains
+
+- Ethereum (`eth`)
+- Base (`base`)
+- BSC (`bsc`)
+- Polygon (`pol`)
+- Arbitrum (`arb`)
+- Optimism (`opt`)
+- Solana (`sol`)
+- TON (`ton`)
+- Sui (`sui`)
+- Stellar (`stellar`)
+- Bitcoin (`btc`)
+
+## Error Handling
+
+```typescript
+import { ThreatClient, RateLimitError, AuthenticationError } from '@rlajous/sdk-threat';
+
+try {
+  const risk = await client.addresses.analyze('0x...', { chain: 'eth' });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/cjs/client.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreatClient = void 0;
+const sdk_core_1 = require("@rlajous/sdk-core");
+const addresses_1 = require("./resources/addresses");
+const contracts_1 = require("./resources/contracts");
+const url_1 = require("./resources/url");
+const wallets_1 = require("./resources/wallets");
+const ledger_1 = require("./resources/ledger");
+const account_trace_1 = require("./resources/account-trace");
+const usage_1 = require("./resources/usage");
+/**
+ * Webacy Threat SDK Client
+ *
+ * Provides access to threat and risk analysis including address risk,
+ * sanctions screening, contract security, URL safety, and more.
+ *
+ * @example
+ * ```typescript
+ * import { ThreatClient, Chain, RiskModule } from '@rlajous/sdk-threat';
+ *
+ * const client = new ThreatClient({
+ *   apiKey: process.env.WEBACY_API_KEY!,
+ * });
+ *
+ * // Address risk analysis
+ * const risk = await client.addresses.analyze('0x...', { chain: 'eth' });
+ *
+ * // Sanctions screening
+ * const sanctioned = await client.addresses.checkSanctioned('0x...', { chain: 'eth' });
+ *
+ * // URL safety check
+ * const urlRisk = await client.url.check('https://suspicious-site.com');
+ * ```
+ */
+class ThreatClient extends sdk_core_1.BaseClient {
+    /**
+     * Addresses resource
+     *
+     * Comprehensive security analysis for blockchain addresses including
+     * risk scoring, sanctions screening, and address poisoning detection.
+     */
+    addresses;
+    /**
+     * Contracts resource
+     *
+     * Smart contract security analysis including vulnerability detection,
+     * source code analysis, and tax detection.
+     */
+    contracts;
+    /**
+     * URL resource
+     *
+     * URL safety analysis to identify phishing sites and malicious domains.
+     */
+    url;
+    /**
+     * Wallets resource
+     *
+     * Wallet activity analysis including transaction risks and token approvals.
+     */
+    wallets;
+    /**
+     * Ledger resource
+     *
+     * Hardware wallet transaction scanning for secure signing.
+     */
+    ledger;
+    /**
+     * Account trace resource
+     *
+     * Fund flow tracing to identify connections to risky entities.
+     */
+    accountTrace;
+    /**
+     * Usage resource
+     *
+     * API usage statistics and quota management.
+     */
+    usage;
+    /**
+     * Create a new ThreatClient instance
+     *
+     * @param config - Client configuration
+     * @throws AuthenticationError if API key is not provided
+     *
+     * @example
+     * ```typescript
+     * // Basic setup
+     * const client = new ThreatClient({
+     *   apiKey: 'your-api-key',
+     * });
+     *
+     * // With default chain (omit chain in API calls)
+     * const client = new ThreatClient({
+     *   apiKey: 'your-api-key',
+     *   defaultChain: Chain.ETH,
+     * });
+     *
+     * // With custom configuration
+     * const client = new ThreatClient({
+     *   apiKey: 'your-api-key',
+     *   timeout: 60000,
+     *   retry: {
+     *     maxRetries: 5,
+     *   },
+     * });
+     * ```
+     */
+    constructor(config) {
+        super(config);
+        // Initialize resources with the HTTP client and default chain
+        this.addresses = new addresses_1.AddressesResource(this.httpClient, this.defaultChain);
+        this.contracts = new contracts_1.ContractsResource(this.httpClient, this.defaultChain);
+        this.url = new url_1.UrlResource(this.httpClient);
+        this.wallets = new wallets_1.WalletsResource(this.httpClient, this.defaultChain);
+        this.ledger = new ledger_1.LedgerResource(this.httpClient);
+        this.accountTrace = new account_trace_1.AccountTraceResource(this.httpClient, this.defaultChain);
+        this.usage = new usage_1.UsageResource(this.httpClient);
+    }
+    /**
+     * Add a request interceptor
+     *
+     * @example
+     * ```typescript
+     * client.addRequestInterceptor((url, config) => {
+     *   console.log(`Making request to ${url}`);
+     *   return config;
+     * });
+     * ```
+     */
+    addRequestInterceptor(interceptor) {
+        super.addRequestInterceptor(interceptor);
+    }
+    /**
+     * Add a response interceptor
+     *
+     * @example
+     * ```typescript
+     * client.addResponseInterceptor((response) => {
+     *   console.log(`Received ${response.status} response`);
+     *   return response;
+     * });
+     * ```
+     */
+    addResponseInterceptor(interceptor) {
+        super.addResponseInterceptor(interceptor);
+    }
+    /**
+     * Add an error interceptor
+     *
+     * @example
+     * ```typescript
+     * client.addErrorInterceptor((error) => {
+     *   console.error(`Request failed: ${error.message}`);
+     *   return error;
+     * });
+     * ```
+     */
+    addErrorInterceptor(interceptor) {
+        super.addErrorInterceptor(interceptor);
+    }
+}
+exports.ThreatClient = ThreatClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";;;AAAA,gDAM2B;AAC3B,qDAA0D;AAC1D,qDAA0D;AAC1D,yCAA8C;AAC9C,iDAAsD;AACtD,+CAAoD;AACpD,6DAAiE;AACjE,6CAAkD;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,YAAa,SAAQ,qBAAU;IAC1C;;;;;OAKG;IACa,SAAS,CAAoB;IAE7C;;;;;OAKG;IACa,SAAS,CAAoB;IAE7C;;;;OAIG;IACa,GAAG,CAAc;IAEjC;;;;OAIG;IACa,OAAO,CAAkB;IAEzC;;;;OAIG;IACa,MAAM,CAAiB;IAEvC;;;;OAIG;IACa,YAAY,CAAuB;IAEnD;;;;OAIG;IACa,KAAK,CAAgB;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAAY,MAA0B;QACpC,KAAK,CAAC,MAAM,CAAC,CAAC;QAEd,8DAA8D;QAC9D,IAAI,CAAC,SAAS,GAAG,IAAI,6BAAiB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3E,IAAI,CAAC,SAAS,GAAG,IAAI,6BAAiB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3E,IAAI,CAAC,GAAG,GAAG,IAAI,iBAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,GAAG,IAAI,yBAAe,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,GAAG,IAAI,uBAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClD,IAAI,CAAC,YAAY,GAAG,IAAI,oCAAoB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACjF,IAAI,CAAC,KAAK,GAAG,IAAI,qBAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;OAUG;IACM,qBAAqB,CAAC,WAA+B;QAC5D,KAAK,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;OAUG;IACM,sBAAsB,CAAC,WAAgC;QAC9D,KAAK,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;OAUG;IACM,mBAAmB,CAAC,WAA6B;QACxD,KAAK,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;CACF;AA1ID,oCA0IC"}

package/dist/cjs/index.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkError = exports.NotFoundError = exports.ValidationError = exports.RateLimitError = exports.AuthenticationError = exports.WebacyError = exports.TokenStandard = exports.TypeOfAddress = exports.RiskLevel = exports.RiskScore = exports.RiskModule = exports.CHAIN_NAMES = exports.isEvmChain = exports.ChainCompatibility = exports.Chain = exports.UsageResource = exports.AccountTraceResource = exports.LedgerResource = exports.WalletsResource = exports.UrlResource = exports.ContractsResource = exports.AddressesResource = exports.ThreatClient = void 0;
+// Client
+var client_1 = require("./client");
+Object.defineProperty(exports, "ThreatClient", { enumerable: true, get: function () { return client_1.ThreatClient; } });
+// Resources
+var resources_1 = require("./resources");
+Object.defineProperty(exports, "AddressesResource", { enumerable: true, get: function () { return resources_1.AddressesResource; } });
+Object.defineProperty(exports, "ContractsResource", { enumerable: true, get: function () { return resources_1.ContractsResource; } });
+Object.defineProperty(exports, "UrlResource", { enumerable: true, get: function () { return resources_1.UrlResource; } });
+Object.defineProperty(exports, "WalletsResource", { enumerable: true, get: function () { return resources_1.WalletsResource; } });
+Object.defineProperty(exports, "LedgerResource", { enumerable: true, get: function () { return resources_1.LedgerResource; } });
+Object.defineProperty(exports, "AccountTraceResource", { enumerable: true, get: function () { return resources_1.AccountTraceResource; } });
+Object.defineProperty(exports, "UsageResource", { enumerable: true, get: function () { return resources_1.UsageResource; } });
+// Re-export commonly used types from core
+var sdk_core_1 = require("@rlajous/sdk-core");
+Object.defineProperty(exports, "Chain", { enumerable: true, get: function () { return sdk_core_1.Chain; } });
+Object.defineProperty(exports, "ChainCompatibility", { enumerable: true, get: function () { return sdk_core_1.ChainCompatibility; } });
+Object.defineProperty(exports, "isEvmChain", { enumerable: true, get: function () { return sdk_core_1.isEvmChain; } });
+Object.defineProperty(exports, "CHAIN_NAMES", { enumerable: true, get: function () { return sdk_core_1.CHAIN_NAMES; } });
+Object.defineProperty(exports, "RiskModule", { enumerable: true, get: function () { return sdk_core_1.RiskModule; } });
+Object.defineProperty(exports, "RiskScore", { enumerable: true, get: function () { return sdk_core_1.RiskScore; } });
+Object.defineProperty(exports, "RiskLevel", { enumerable: true, get: function () { return sdk_core_1.RiskLevel; } });
+Object.defineProperty(exports, "TypeOfAddress", { enumerable: true, get: function () { return sdk_core_1.TypeOfAddress; } });
+Object.defineProperty(exports, "TokenStandard", { enumerable: true, get: function () { return sdk_core_1.TokenStandard; } });
+Object.defineProperty(exports, "WebacyError", { enumerable: true, get: function () { return sdk_core_1.WebacyError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return sdk_core_1.AuthenticationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return sdk_core_1.RateLimitError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return sdk_core_1.ValidationError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return sdk_core_1.NotFoundError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return sdk_core_1.NetworkError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,SAAS;AACT,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAErB,YAAY;AACZ,yCAQqB;AAPnB,8GAAA,iBAAiB,OAAA;AACjB,8GAAA,iBAAiB,OAAA;AACjB,wGAAA,WAAW,OAAA;AACX,4GAAA,eAAe,OAAA;AACf,2GAAA,cAAc,OAAA;AACd,iHAAA,oBAAoB,OAAA;AACpB,0GAAA,aAAa,OAAA;AAkEf,0CAA0C;AAC1C,8CAqB2B;AApBzB,iGAAA,KAAK,OAAA;AACL,8GAAA,kBAAkB,OAAA;AAClB,sGAAA,UAAU,OAAA;AACV,uGAAA,WAAW,OAAA;AACX,sGAAA,UAAU,OAAA;AACV,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,yGAAA,aAAa,OAAA;AACb,yGAAA,aAAa,OAAA;AACb,uGAAA,WAAW,OAAA;AACX,+GAAA,mBAAmB,OAAA;AACnB,0GAAA,cAAc,OAAA;AACd,2GAAA,eAAe,OAAA;AACf,yGAAA,aAAa,OAAA;AACb,wGAAA,YAAY,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/resources/account-trace.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountTraceResource = void 0;
+const sdk_core_1 = require("@rlajous/sdk-core");
+/**
+ * Resource for account fund flow tracing
+ *
+ * Traces fund flows to and from addresses to identify
+ * connections to risky entities.
+ *
+ * @example
+ * ```typescript
+ * const trace = await client.accountTrace.trace('0x...', { chain: Chain.ETH });
+ * console.log(`Sanctioned connections: ${trace.summary.sanctioned_connections}`);
+ *
+ * // With default chain configured, chain can be omitted
+ * const client = new ThreatClient({ apiKey: '...', defaultChain: Chain.ETH });
+ * const trace = await client.accountTrace.trace('0x...'); // Uses ETH
+ * ```
+ */
+class AccountTraceResource {
+    httpClient;
+    defaultChain;
+    constructor(httpClient, defaultChain) {
+        this.httpClient = httpClient;
+        this.defaultChain = defaultChain;
+    }
+    /**
+     * Resolve the chain to use for a request
+     * @throws ValidationError if no chain is specified and no default is set
+     */
+    resolveChain(options) {
+        const chain = options?.chain ?? this.defaultChain;
+        if (!chain) {
+            throw new sdk_core_1.ValidationError('Chain is required. Either specify chain in options or set defaultChain in client configuration.');
+        }
+        return chain;
+    }
+    /**
+     * Trace account fund flows
+     *
+     * Analyzes connections to identify:
+     * - Direct counterparties
+     * - Sanctioned address connections
+     * - Mixer usage
+     * - High-risk entities
+     *
+     * @param address - Address to trace
+     * @param options - Trace options (chain is optional if defaultChain is set)
+     * @returns Fund flow trace result
+     *
+     * @example
+     * ```typescript
+     * const trace = await client.accountTrace.trace('0x...', {
+     *   chain: Chain.ETH,
+     *   depth: 2, // Trace 2 hops
+     * });
+     *
+     * // With default chain configured
+     * const trace = await client.accountTrace.trace('0x...');
+     *
+     * console.log(`Total connections: ${trace.summary.total_connections}`);
+     * console.log(`High risk: ${trace.summary.high_risk_connections}`);
+     * console.log(`Sanctioned: ${trace.summary.sanctioned_connections}`);
+     * console.log(`Mixers: ${trace.summary.mixer_connections}`);
+     *
+     * // Check individual connections
+     * for (const conn of trace.connections) {
+     *   if (conn.risk_flags?.length) {
+     *     console.warn(`Risky connection: ${conn.address}`);
+     *     console.warn(`Flags: ${conn.risk_flags.join(', ')}`);
+     *   }
+     * }
+     * ```
+     */
+    async trace(address, options = {}) {
+        const chain = this.resolveChain(options);
+        // Validate address format before making API call
+        if (!(0, sdk_core_1.isValidAddress)(address, chain)) {
+            const chainName = sdk_core_1.CHAIN_NAMES[chain] || chain;
+            throw new sdk_core_1.ValidationError(`Invalid ${chainName} address: "${address}". Please provide a valid address format for the ${chainName} blockchain.`);
+        }
+        const queryParams = new URLSearchParams();
+        queryParams.append('chain', chain);
+        if (options.depth !== undefined) {
+            queryParams.append('depth', String(options.depth));
+        }
+        const response = await this.httpClient.get(`/account-trace/${encodeURIComponent(address)}?${queryParams.toString()}`, {
+            timeout: options.timeout,
+            signal: options.signal,
+        });
+        return response.data;
+    }
+}
+exports.AccountTraceResource = AccountTraceResource;
+//# sourceMappingURL=account-trace.js.map

package/dist/cjs/resources/account-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-trace.js","sourceRoot":"","sources":["../../../src/resources/account-trace.ts"],"names":[],"mappings":";;;AAAA,gDAO2B;AAG3B;;;;;;;;;;;;;;;GAeG;AACH,MAAa,oBAAoB;IAEZ;IACA;IAFnB,YACmB,UAAsB,EACtB,YAAoB;QADpB,eAAU,GAAV,UAAU,CAAY;QACtB,iBAAY,GAAZ,YAAY,CAAQ;IACpC,CAAC;IAEJ;;;OAGG;IACK,YAAY,CAAC,OAA2B;QAC9C,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QAClD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,0BAAe,CACvB,iGAAiG,CAClG,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,UAA+B,EAAE;QAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAEzC,iDAAiD;QACjD,IAAI,CAAC,IAAA,yBAAc,EAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,SAAS,GAAG,sBAAW,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YAC9C,MAAM,IAAI,0BAAe,CACvB,WAAW,SAAS,cAAc,OAAO,oDAAoD,SAAS,cAAc,CACrH,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QAC1C,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAEnC,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC;QAED,MAAM,QAAQ,GAAuC,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAC5E,kBAAkB,kBAAkB,CAAC,OAAO,CAAC,IAAI,WAAW,CAAC,QAAQ,EAAE,EAAE,EACzE;YACE,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;CACF;AArFD,oDAqFC"}