### Manage Default Chain and Debugging

Source: https://docs.webacy.com/sdk/installation

Examples of setting a default blockchain for requests and configuring granular debug logging levels.

```typescript
const client = new ThreatClient({
  apiKey: process.env.WEBACY_API_KEY,
  defaultChain: Chain.ETH
});

const result = await client.addresses.analyze('0x...');
```

```typescript
const client = new ThreatClient({
  apiKey: process.env.WEBACY_API_KEY,
  debug: 'requests'
});
```

--------------------------------

### Install Webacy SDK via Package Managers

Source: https://docs.webacy.com/sdk/installation

Commands to install the Webacy SDK using popular JavaScript package managers. Choose the one that matches your project's environment.

```bash
npm install @webacy-xyz/sdk
```

```bash
pnpm add @webacy-xyz/sdk
```

```bash
yarn add @webacy-xyz/sdk
```

```bash
bun add @webacy-xyz/sdk
```

--------------------------------

### API Response Example

Source: https://docs.webacy.com/glossary/digital-signature-module

This section provides an example of the API response structure, detailing security issues found in smart contract code.

```APIDOC
## GET /websites/webacy/response-example

### Description
Retrieves an example of the API response, illustrating potential security vulnerabilities such as signature replay and missing chain ID.

### Method
GET

### Endpoint
/websites/webacy/response-example

### Parameters
#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **issues** (array) - A list of security issues found.
  - **tag** (string) - A unique identifier for the type of issue.
  - **severity** (string) - The severity level of the issue (e.g., 'high', 'medium').
  - **description** (string) - A detailed explanation of the security vulnerability.
  - **location** (string) - The specific location within the smart contract code where the issue was detected.

#### Response Example
```json
{
  "issues": [
    {
      "tag": "signature_replay",
      "severity": "high",
      "description": "Signature can be reused - no nonce or invalidation",
      "location": "claim(uint256,bytes)"
    },
    {
      "tag": "missing_chainid",
      "severity": "medium",
      "description": "Signature hash does not include chain ID",
      "location": "execute(address,uint256,bytes)"
    }
  ]
}
```
```

--------------------------------

### Check Blockchain Address Risk Score (cURL, JavaScript, Python)

Source: https://docs.webacy.com/quickstart

Make your first request to the Webacy API to check the risk score of a blockchain address. This example demonstrates how to use cURL, JavaScript (fetch API), and Python (requests library) to interact with the API. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```bash
curl -X GET "https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e?chain=eth" \
    -H "x-api-key: YOUR_API_KEY"
```

```javascript
const response = await fetch(
    'https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e?chain=eth',
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );
  const data = await response.json();
  console.log(data);
```

```python
import requests

response = requests.get(
    'https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    params={'chain': 'eth'},
    headers={'x-api-key': 'YOUR_API_KEY'}
)
print(response.json())
```

--------------------------------

### Stellar API Request Examples (Bash)

Source: https://docs.webacy.com/essentials/stellar

Provides example `curl` commands for interacting with the Webacy API to analyze Stellar addresses and token holders. Includes placeholders for API keys and specific identifiers.

```bash
GET /addresses/{address}?chain=stellar
GET /holder-analysis/{identifier}?chain=stellar
```

--------------------------------

### Trading Workflow Example (JavaScript)

Source: https://docs.webacy.com/api-reference/tradingdd

This JavaScript code snippet demonstrates a typical trading workflow. It first performs a quick risk check using the Trading Lite endpoint, followed by a liquidity check. If both checks pass, the trade proceeds. This example requires an API key and assumes the availability of tokenAddress and API_KEY variables.

```javascript
const quickCheck = await fetch(
  `https://api.webacy.com/trading-lite/${tokenAddress}?chain=sol`,
  { headers: { 'x-api-key': API_KEY } }
).then(r => r.json());

if (quickCheck.overallRisk > 70) {
  console.log('High risk token - skipping');
  return;
}

const pools = await fetch(
  `https://api.webacy.com/tokens/${tokenAddress}/pools?chain=sol`,
  { headers: { 'x-api-key': API_KEY } }
).then(r => r.json());

if (pools.totalLiquidity < 10000) {
  console.log('Low liquidity - high slippage risk');
  return;
}

// 3. Proceed with trade...
```

--------------------------------

### GET /liquidity/metrics

Source: https://docs.webacy.com/api-reference/token-analysis/get-token-pools-with-risk-assessment

Retrieves liquidity migration metrics and success data for a specific project.

```APIDOC
## GET /liquidity/metrics

### Description
Retrieves the migration status and success metrics for liquidity, including the destination and detection methods.

### Method
GET

### Endpoint
/liquidity/metrics

### Parameters
#### Query Parameters
- **api_key** (string) - Required - The x-api-key header must be provided for authentication.

### Request Example
GET /liquidity/metrics
Headers: { "x-api-key": "your_api_key" }

### Response
#### Success Response (200)
- **achievedValue** (number) - Achieved value
- **successPercentage** (number) - Success percentage
- **liquidityAmount** (number) - Liquidity amount
- **migrationDestination** (string) - Where liquidity was migrated to
- **additionalMetrics** (object) - Additional success metrics

#### Response Example
{
  "achievedValue": 69000,
  "successPercentage": 100,
  "liquidityAmount": 12000,
  "migrationDestination": "raydium",
  "additionalMetrics": {
    "detectionMethod": "market_cap"
  }
}
```

--------------------------------

### GET /analysis/developer/{developerAddress}

Source: https://docs.webacy.com/api-reference/pool-analysis/get-pool-ohlcv-data-with-risk-assessment

Retrieves multi-platform token launch analysis for developer migration risk assessment.

```APIDOC
## GET /analysis/developer/{developerAddress}

### Description
Provides a risk assessment for a developer's wallet address, focusing on migration risks across multiple platforms.

### Method
GET

### Endpoint
/analysis/developer/{developerAddress}

### Parameters
#### Path Parameters
- **developerAddress** (string) - Required - The developer's wallet address.

### Response
#### Success Response (200)
- **developerAddress** (string) - The developer's wallet address
- **analyzedAt** (string) - Timestamp of the analysis

#### Response Example
{
  "developerAddress": "ESoMiyuJ1ksL5L99LjYCcwjt7XR2B7hdn6mkbBDFbadV",
  "analyzedAt": "2023-11-15T10:30:00Z"
}
```

--------------------------------

### GET /contracts/{contractAddress}

Source: https://docs.webacy.com/essentials/supported-blockchains

Analyze a smart contract for potential security risks.

```APIDOC
## GET /contracts/{contractAddress}

### Description
Performs a risk assessment on a smart contract address.

### Method
GET

### Endpoint
/contracts/{contractAddress}

### Parameters
#### Path Parameters
- **contractAddress** (string) - Required - The smart contract address to analyze.

### Request Example
GET /contracts/0xabc...123

### Response
#### Success Response (200)
- **risk_level** (string) - The assessed risk level of the contract.

#### Response Example
{
  "contract": "0xabc...123",
  "risk_level": "low"
}
```

--------------------------------

### Get Documentation Index

Source: https://docs.webacy.com/api-reference/transaction-risks/risk-details-for-a-transaction

Fetches the complete documentation index, which can be used to discover all available API pages.

```APIDOC
## GET /websites/webacy/documentation/index

### Description
Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
Use this file to discover all available pages before exploring further.

### Method
GET

### Endpoint
/websites/webacy/documentation/index

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **documentation_url** (string) - The URL to the documentation index file.

#### Response Example
{
  "documentation_url": "https://docs.webacy.com/llms.txt"
}
```

--------------------------------

### GET /quick-profile/{walletAddress}

Source: https://docs.webacy.com/api-reference/exposure-risk/understand-the-risk-profile-risk-exposure-of-an-address

Retrieves a summarized risk profile for a given wallet address, including exposure to known threats and malicious entities.

```APIDOC
## GET /quick-profile/{walletAddress}

### Description
Get a summarized risk profile including exposure to known threats and malicious entities.

### Method
GET

### Endpoint
/quick-profile/{walletAddress}

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The wallet address to analyze.

#### Query Parameters
- **chain** (string) - Optional - Selected chain. This includes 'eth', 'base', 'bsc', 'pol', 'opt', 'sol', 'arb' EVM addresses, 'sol' for SVM addresses, and 'hedera' for Hedera addresses (0.0.X native or EVM format).
  - Enum: `eth`, `base`, `bsc`, `pol`, `opt`, `sol`, `arb`, `hedera`
- **withApprovals** (boolean) - Optional - Fetch risk profile with approvals.
- **hide_trust_flags** (boolean) - Optional - Boolean to determine whether to hide trust-related flags from the response.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **count** (integer) - Number of transactions
- **medium** (integer) - Number of medium risk transactions
- **high** (integer) - Number of high risk transactions
- **overallRisk** (number) - Overall risk score
- **issues** (array) - List of issues found
  - **transaction** (object)
    - **transaction_hash** (string) - Hash of the transaction
    - **transaction_id** (string) - ID of the transaction
    - **from_to_address** (string) - From/To address of the transaction
    - **is_contract** (boolean) - Whether the transaction refers to a contract address
    - **contract_address** (string) - The contract address if `is_contract` is true

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### GET /contracts/{contractAddress}

Source: https://docs.webacy.com/api-reference/contract-risk/get-a-real-time-analysis-for-a-given-contract-address

Retrieves a real-time security analysis for a given smart contract address, including vulnerability detection.

```APIDOC
## GET /contracts/{contractAddress}

### Description
Perform real-time security analysis on a smart contract including vulnerability detection.

### Method
GET

### Endpoint
/contracts/{contractAddress}

### Parameters
#### Path Parameters
- **contractAddress** (string) - Required - The address of the smart contract to analyze.

#### Query Parameters
- **chain** (EVMChainType) - Optional - Selected chain. This includes 'eth', 'base', 'bsc', 'pol', 'opt' and 'arb'.
- **fromBytecode** (boolean) - Optional - Does full bytecode analysis on unverified contracts. The full scan can take up to several minutes. To retrieve the final results, either refresh this endpoint, or supply a callback URL for which results will be posted every 5 seconds.
- **refreshCache** (boolean) - Optional - Re-analyze contract address and retrieve fresh data.
- **callback** (string) - Optional - Returns asynchronous response from bytecode analysis. This callback will be called every 5 seconds with any new data found until the full analysis has been completed. If an analysis is already completed, the callback will not be called.
- **deployer_risk** (boolean) - Optional - Analyze the deployer address for risks and include a flag if the deployer is risky.
- **hide_trust_flags** (boolean) - Optional - Boolean to determine whether to hide trust-related flags from the response.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **score** (integer) - Overall risk score for the contract.
- **tags** (array) - List of tags associated with the contract.
  - **key** (string) - The unique identifier for the tag.
  - **name** (string) - The display name of the tag.
  - **description** (string) - A detailed explanation of the tag.

#### Response Example
```json
{
  "score": 3,
  "tags": [
    {
      "key": "centralized_risk_high",
      "name": "Centralized Risk High",
      "description": "High risk associated with centralization."
    }
  ]
}
```
```

--------------------------------

### GET /tokens

Source: https://docs.webacy.com/sdk/trading-client

Endpoints for retrieving liquidity pool information, trending tokens, and detailed token economics.

```APIDOC
## GET /tokens

### Description
Retrieve token-related data including liquidity pools, trending tokens, and historical economics.

### Method
GET

### Endpoints
- `client.tokens.getPools(address, options)`
- `client.tokens.getTrending(options)`
- `client.tokens.getToken(address, options)`

### Parameters
#### Query Parameters
- **chain** (Chain) - Required - Blockchain to query (ETH, BASE, BSC, POL, OPT, ARB, SOL).
- **metricsDate** (string) - Optional - Date in DD-MM-YYYY format for historical data.

### Response
#### Success Response (200)
- **metrics** (object) - Includes priceUsd, marketCap, volume24h, and holderCount.

### Response Example
{
  "name": "Example Token",
  "symbol": "EXT",
  "metrics": {
    "priceUsd": 1.25,
    "marketCap": 1000000,
    "holderCount": 500
  }
}
```

--------------------------------

### GET /analysis/platform-breakdown

Source: https://docs.webacy.com/api-reference/pool-analysis/get-pool-ohlcv-data-with-risk-assessment

Retrieves the analysis breakdown for a developer's token launches across various platforms like pump_fun, moonshot, and jupiter_lfg.

```APIDOC
## GET /analysis/platform-breakdown

### Description
Retrieves a detailed breakdown of token launches associated with a specific developer address, categorized by platform.

### Method
GET

### Endpoint
/analysis/platform-breakdown

### Parameters
#### Query Parameters
- **developerAddress** (string) - Required - The blockchain address of the developer to analyze.

### Request Example
{
  "developerAddress": "0x123...abc"
}

### Response
#### Success Response (200)
- **developerAddress** (string) - The address analyzed.
- **analyzedAt** (string) - Timestamp of the analysis.
- **platformBreakdown** (object) - Map of platform names to PlatformAnalysisResult objects.

#### Response Example
{
  "developerAddress": "0x123...abc",
  "analyzedAt": "2025-09-05T18:28:55.907Z",
  "platformBreakdown": {
    "pump_fun": {
      "platform": "pump_fun",
      "chains": ["sol"],
      "totalLaunches": 74,
      "successfulLaunches": 10
    }
  }
}
```

--------------------------------

### Initialize Webacy Clients

Source: https://docs.webacy.com/sdk/installation

Shows how to instantiate the ThreatClient and TradingClient using an API key. These clients provide access to security and trading analysis tools respectively.

```typescript
import { ThreatClient, Chain } from '@webacy-xyz/sdk';

const client = new ThreatClient({
  apiKey: process.env.WEBACY_API_KEY,
});
```

```typescript
import { TradingClient, Chain } from '@webacy-xyz/sdk';

const client = new TradingClient({
  apiKey: process.env.WEBACY_API_KEY,
});
```

--------------------------------

### Get Maximum RPS for an Organization (OpenAPI)

Source: https://docs.webacy.com/api-reference/api-usage/get-maximum-rps-for-an-organization

This OpenAPI definition describes the GET /usage/max-rps endpoint. It allows you to retrieve the maximum requests per second (RPS) for a specified organization within a given time interval. The interval is limited to a maximum of 30 minutes. It requires organization name, start timestamp, and end timestamp as query parameters. Responses include success (200) with a numeric RPS value, or various error codes (400, 404) for invalid input or non-existent organizations.

```yaml
openapi: 3.0.1
info:
  title: Risk Score API
  description: API definition for Webacy Risk Scores
  version: 1.0.3
servers:
  - url: https://api.webacy.com
    description: Webacy Risk Score API (Production)
  - url: https://api-development.webacy.com
    description: Webacy Risk Score API (Development)
  - url: http://0.0.0.0:3030/api/v1/risk-score
    description: Webacy Risk Score API - Local
security:
  - api_key: []
tags:
  - name: Threat Risks
    description: Analyze addresses for security threats and malicious activity
  - name: Sanction Checks
    description: Check addresses against OFAC and other sanction lists
  - name: Approval Risks
    description: Analyze token approvals and associated risks
  - name: Transaction Risks
    description: Assess risk details for blockchain transactions
  - name: Exposure Risk
    description: Understand risk profile and exposure of addresses
  - name: Contract Risk
    description: Real-time smart contract security analysis
  - name: URL Risks
    description: Analyze URLs for phishing and security threats
  - name: API Usage
    description: Monitor and manage API consumption
  - name: Holder Analysis
    description: Token holder distribution and sniper detection
  - name: Address Poisoning
    description: Detect address poisoning attack patterns
  - name: Token Analysis
    description: Comprehensive token security and market analysis
  - name: Pool Analysis
    description: Liquidity pool data and analysis
  - name: Transaction Scanning
    description: Scan and simulate transactions for risks
  - name: trading-lite
    description: Lightweight trading risk assessment
paths:
  /usage/max-rps:
    get:
      tags:
        - API Usage
      summary: Get maximum RPS for an organization
      description: >-
        Retrieves the maximum requests per second (RPS) for a given organization
        within a specified interval, limited to a maximum of 30 minutes.
      operationId: getMaxRps
      parameters:
        - name: organization
          in: query
          required: true
          description: The name of the organization to filter logs by.
          schema:
            type: string
        - name: from
          in: query
          required: true
          description: >-
            The start date of the interval to query logs (timestamp in
            milliseconds).
          schema:
            type: integer
            format: int64
        - name: to
          in: query
          required: true
          description: >-
            The end date of the interval to query logs (timestamp in
            milliseconds).
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: number
                nullable: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                intervalTooLong:
                  summary: Interval too long
                  value:
                    message: The interval should not be more than 30 minutes.
                endDateInFuture:
                  summary: End date in future
                  value:
                    message: The end date should be in the past.
                startDateAfterEndDate:
                  summary: Start date after end date
                  value:
                    message: The start date should be before the end date.
        '404':
          description: Organization name not found
          content:
            application/json:
              example:
                message: Organization name not found
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

```

--------------------------------

### Import Webacy SDK Modules

Source: https://docs.webacy.com/sdk/installation

Demonstrates how to import the SDK using both ECMAScript Modules (ESM) and CommonJS syntax.

```typescript
import { ThreatClient, TradingClient, Chain } from '@webacy-xyz/sdk';
```

```javascript
const { ThreatClient, TradingClient, Chain } = require('@webacy-xyz/sdk');
```

--------------------------------

### Get Risk Details for a Transaction

Source: https://docs.webacy.com/api-reference/transaction-risks/risk-details-for-a-transaction

Get comprehensive risk analysis for a specific blockchain transaction.

```APIDOC
## GET /websites/webacy/transactions/{transaction_id}/risk

### Description
Get comprehensive risk analysis for a specific blockchain transaction.

### Method
GET

### Endpoint
/websites/webacy/transactions/{transaction_id}/risk

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - The unique identifier of the blockchain transaction.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **risk_score** (integer) - The calculated risk score for the transaction.
- **risk_factors** (array) - A list of factors contributing to the risk score.
  - **factor_name** (string) - The name of the risk factor.
  - **severity** (string) - The severity level of the factor (e.g., 'high', 'medium', 'low').

#### Response Example
{
  "risk_score": 85,
  "risk_factors": [
    {
      "factor_name": "Suspicious contract interaction",
      "severity": "high"
    },
    {
      "factor_name": "Unusual transaction volume",
      "severity": "medium"
    }
  ]
}
```

--------------------------------

### Screen Tokens and Contracts for DeFi Protocols

Source: https://docs.webacy.com/sdk/use-cases

Shows how to utilize ThreatClient and TradingClient to analyze contract safety, holder concentration, and tax structures for token listings.

```typescript
import { ThreatClient, TradingClient, Chain } from '@webacy-xyz/sdk';

const threat = new ThreatClient({ apiKey: process.env.WEBACY_API_KEY });
const trading = new TradingClient({ apiKey: process.env.WEBACY_API_KEY });

// Screen a token before listing
async function screenTokenForListing(tokenAddress: string, chain: Chain) {
  const [contract, holders, tax] = await Promise.all([
    threat.contracts.analyze(tokenAddress, { chain }),
    trading.holderAnalysis.get(tokenAddress, { chain }),
    threat.contracts.getTax(tokenAddress, { chain }),
  ]);

  const redFlags: string[] = [];

  if (contract.overallRisk > 70) redFlags.push('High contract risk');
  if (holders.top10Percentage > 90) redFlags.push('Concentrated holdings');
  if (tax.buyTax > 10 || tax.sellTax > 10) redFlags.push('High tax token');

  return { approved: redFlags.length === 0, redFlags };
}
```

--------------------------------

### GET /usage/max-rps

Source: https://docs.webacy.com/api-reference/api-usage/get-maximum-rps-for-an-organization

Retrieves the maximum requests per second (RPS) for a specified organization within a defined time interval.

```APIDOC
## GET /usage/max-rps

### Description
Retrieves the maximum requests per second (RPS) for a given organization within a specified interval. Note that the requested interval is limited to a maximum of 30 minutes.

### Method
GET

### Endpoint
/usage/max-rps

### Parameters
#### Query Parameters
- **organization** (string) - Required - The name of the organization to filter logs by.
- **from** (integer) - Required - The start date of the interval to query logs (timestamp in milliseconds).
- **to** (integer) - Required - The end date of the interval to query logs (timestamp in milliseconds).

### Request Example
GET /usage/max-rps?organization=my-org&from=1672531200000&to=1672533000000

### Response
#### Success Response (200)
- **rps** (number) - The maximum requests per second recorded for the organization in the given interval.

#### Response Example
{
  "rps": 150.5
}
```

--------------------------------

### Initialize TradingClient

Source: https://docs.webacy.com/sdk/trading-client

Configures the TradingClient instance using an API key and an optional default blockchain. This client serves as the entry point for all trading analysis operations.

```typescript
import { TradingClient, Chain } from '@webacy-xyz/sdk';

const client = new TradingClient({
  apiKey: process.env.WEBACY_API_KEY,
  defaultChain: Chain.SOL, // Optional: set default chain
});
```

--------------------------------

### Successful API Response Example

Source: https://docs.webacy.com/api-reference/introduction

Example of a successful JSON response from the Webacy Risk Score API, containing risk assessment data.

```json
{
  "count": 1,
  "medium": 0,
  "high": 0,
  "overallRisk": 25.99,
  "issues": [],
  "isContract": false
}
```

--------------------------------

### JSON: API Response Example for Vulnerability Detection

Source: https://docs.webacy.com/glossary/hidden-balance-update

An example JSON response illustrating how detected issues, such as 'hidden_balance_update', are reported with severity, description, and location.

```json
{
  "issues": [
    {
      "tag": "hidden_balance_update",
      "severity": "high",
      "description": "Direct balance mapping modification without events",
      "location": "adjustBalance(address,uint256)"
    }
  ]
}
```

--------------------------------

### Error API Response Example

Source: https://docs.webacy.com/api-reference/introduction

Example of an error response from the Webacy Risk Score API, typically indicating an issue like unauthorized access.

```json
{
  "message": "Unauthorized"
}
```

--------------------------------

### API Response Example (JSON)

Source: https://docs.webacy.com/glossary/malicious-external-call

An example JSON response illustrating the structure of API output for detected security issues. It includes fields for `tag`, `severity`, `description`, and `location` of the detected vulnerability.

```json
{
  "issues": [
    {
      "tag": "external_call",
      "severity": "medium",
      "description": "Arbitrary external call with user-controlled target",
      "location": "execute(address,bytes)"
    },
    {
      "tag": "dangerous_delegatecall",
      "severity": "high",
      "description": "Delegatecall to unvalidated address",
      "location": "upgrade(address)"
    }
  ]
}
```

--------------------------------

### Perform Metadata Checks with Webacy API

Source: https://docs.webacy.com/essentials/modules

This example demonstrates how to use the Webacy API to perform metadata checks on addresses. It specifies the chain and modules to include in the analysis. Replace '0x...?' with the actual address and 'YOUR_API_KEY' with your valid API key.

```bash
curl -X GET "https://api.webacy.com/addresses/0x...?chain=eth&modules=security_essentials,fraud_detection" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Import from Individual Packages

Source: https://docs.webacy.com/sdk/installation

Optimized imports for specific SDK modules to reduce bundle size in production environments.

```typescript
import { ThreatClient } from '@webacy-xyz/sdk-threat';
import { TradingClient } from '@webacy-xyz/sdk-trading';
import { Chain, ValidationError } from '@webacy-xyz/sdk-core';
```

--------------------------------

### API Response Example for Burn Issues (JSON)

Source: https://docs.webacy.com/glossary/malicious-burn

Shows an example JSON response from an API that details detected burn-related security issues, including tag, severity, description, and location.

```json
{
  "issues": [
    {
      "tag": "privileged_burn",
      "severity": "high",
      "description": "Owner can burn tokens from any address",
      "location": "burn(address,uint256)"
    }
  ]
}
```

--------------------------------

### Set Up Liquidity Change Webhook

Source: https://docs.webacy.com/glossary/liquidity-risks

Configures a webhook to receive real-time notifications for liquidity-related events for a specific token. This is useful for continuous monitoring.

```APIDOC
## POST /webhooks

### Description
Creates a webhook subscription to receive real-time alerts for specified events related to a token's liquidity. This allows for proactive monitoring of liquidity changes.

### Method
POST

### Endpoint
`/webhooks`

### Parameters
#### Request Body
- **token** (string) - Required - The contract address of the token to monitor.
- **chain** (string) - Required - The blockchain network (e.g., 'eth', 'bsc').
- **events** (array of strings) - Required - A list of events to subscribe to. Supported events include: `LIQUIDITY_CHANGE`.

### Request Example
```bash
curl -X POST "https://api.webacy.com/webhooks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "0x123...",
    "chain": "eth",
    "events": ["LIQUIDITY_CHANGE"]
  }'
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the webhook was set up successfully.
- **webhook_id** (string) - The unique identifier for the created webhook.

#### Response Example
```json
{
  "message": "Webhook created successfully for LIQUIDITY_CHANGE events.",
  "webhook_id": "wh_abc123xyz"
}
```
```

--------------------------------

### GET /addresses/sanctioned/{walletAddress}

Source: https://docs.webacy.com/essentials/supported-blockchains

Check if a specific wallet address is on a sanctions list.

```APIDOC
## GET /addresses/sanctioned/{walletAddress}

### Description
Determines if the provided wallet address is flagged as sanctioned.

### Method
GET

### Endpoint
/addresses/sanctioned/{walletAddress}

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The wallet address to check against sanction lists.

### Request Example
GET /addresses/sanctioned/0x123...abc

### Response
#### Success Response (200)
- **is_sanctioned** (boolean) - True if the address is sanctioned.

#### Response Example
{
  "is_sanctioned": false
}
```

--------------------------------

### Security Best Practices

Source: https://docs.webacy.com/glossary/digital-signature-module

A list of recommended best practices for securing smart contract interactions, particularly concerning signature handling.

```APIDOC
## Best Practices for Smart Contract Security

### Description
This section outlines essential security measures to prevent common vulnerabilities related to transaction signing and execution.

### Method
N/A (Informational)

### Endpoint
N/A (Informational)

### Parameters
N/A

### Best Practices List
* Include nonce in all signed messages
* Include `block.chainid` to prevent cross-chain replay
* Include contract address to prevent cross-contract replay
* Use EIP-712 for structured, typed signing
* Use OpenZeppelin's ECDSA library
* Mark used signatures/nonces as consumed
* Consider signature expiration timestamps
```

--------------------------------

### Configure Webacy Client Options

Source: https://docs.webacy.com/sdk/installation

Advanced configuration for the Webacy client, including setting default chains, enabling debug logging, and defining request timeouts.

```typescript
const client = new ThreatClient({
  apiKey: 'your-api-key',
  defaultChain: Chain.ETH,
  debug: true,
  baseUrl: 'https://api-development.webacy.com',
  timeout: 30000
});
```

--------------------------------

### GET /addresses/{address}

Source: https://docs.webacy.com/essentials/supported-blockchains

Retrieve threat risk information for a specific blockchain address.

```APIDOC
## GET /addresses/{address}

### Description
Fetches threat risk analysis for a given wallet address across supported chains.

### Method
GET

### Endpoint
/addresses/{address}

### Parameters
#### Path Parameters
- **address** (string) - Required - The blockchain address to analyze.

### Request Example
GET /addresses/0x123...abc

### Response
#### Success Response (200)
- **risk_score** (integer) - The calculated risk level for the address.
- **threats** (array) - List of identified security threats.

#### Response Example
{
  "address": "0x123...abc",
  "risk_score": 0,
  "threats": []
}
```

--------------------------------

### Fetch Pool Data for a Token (Bash)

Source: https://docs.webacy.com/api-reference/tradingdd

Retrieves liquidity pool data, TVL, and trading pair information for a given token on a specified chain. Requires an API key.

```bash
# Get pools for a token
curl -X GET "https://api.webacy.com/tokens/0x123.../pools?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

# Get specific pool data
curl -X GET "https://api.webacy.com/tokens/pools/0xpool...?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

# Get trending pools
curl -X GET "https://api.webacy.com/tokens/pools/trending?chain=sol" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /usage/current

Source: https://docs.webacy.com/api-reference/api-usage/get-current-api-usage

Retrieves the current billing period API usage statistics for the authenticated organization.

```APIDOC
## GET /usage/current

### Description
Get current billing period API usage statistics for the authenticated user or organization.

### Method
GET

### Endpoint
https://api.webacy.com/usage/current

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None (Requires `x-api-key` in header)

### Request Example
GET /usage/current
Host: api.webacy.com
x-api-key: YOUR_API_KEY

### Response
#### Success Response (200)
- **usage_data** (object) - A map of usage metrics where keys are metric names and values are numeric counts.

#### Response Example
{
  "total_requests": 1500,
  "remaining_quota": 8500
}
```

--------------------------------

### Fetch Token Holder Analysis (Bash)

Source: https://docs.webacy.com/glossary/snipers-bundlers

This command-line interface (CLI) example demonstrates how to retrieve holder analysis data for a specific token using the Webacy API. It requires your API key for authentication and specifies the token and chain for the analysis.

```bash
# Get holder analysis for a token
curl -X GET "https://api.webacy.com/holder-analysis/So111...?chain=sol" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /analysis/{contract_address}

Source: https://docs.webacy.com/api-reference/pool-analysis/get-pool-ohlcv-data-with-risk-assessment

Retrieves the security analysis report for a specific contract address on a given blockchain.

```APIDOC
## GET /analysis/{contract_address}

### Description
Retrieves a comprehensive security analysis report for a specified contract address, including status, findings, and associated URLs.

### Method
GET

### Endpoint
/analysis/{contract_address}

### Parameters
#### Path Parameters
- **contract_address** (string) - Required - The address of the contract to analyze.

#### Query Parameters
- **chain** (string) - Required - The blockchain network (e.g., eth).

### Response
#### Success Response (200)
- **contract_address** (string) - Address of the analyzed contract
- **chain** (string) - Blockchain network
- **analysis_date** (string) - Date when the analysis was performed
- **status** (string) - Status of the analysis (completed, in_progress, failed, pending)
- **findings** (array) - Security analysis findings
- **urls** (array) - Associated URLs related to the analysis

#### Response Example
{
  "contract_address": "0x1234567890123456789012345678901234567890",
  "chain": "eth",
  "analysis_date": "2023-11-15T10:30:00Z",
  "status": "completed",
  "findings": [],
  "urls": []
}
```

--------------------------------

### GET /tokens/pools/{poolAddress}

Source: https://docs.webacy.com/api-reference/pool-analysis/get-pool-ohlcv-data-with-risk-assessment

Retrieves OHLCV data and risk assessment metrics for a specific liquidity pool.

```APIDOC
## GET /tokens/pools/{poolAddress}

### Description
Retrieves OHLCV (Open, High, Low, Close, Volume) data for a liquidity pool along with risk assessment information for the pool and associated tokens.

### Method
GET

### Endpoint
/tokens/pools/{poolAddress}

### Parameters
#### Path Parameters
- **poolAddress** (string) - Required - Address of the liquidity pool to analyze

#### Query Parameters
- **chain** (string) - Required - Blockchain network (eth, base, bsc, pol, opt, arb, sol, ton, sei, btc, sui)
- **timeFrame** (string) - Required - Timeframe granularity (minute, hour, day)
- **beforeTimestamp** (integer) - Optional - Unix timestamp to retrieve data before a specific point in time
- **limit** (integer) - Optional - Limit on the number of OHLCV data points to return

### Request Example
GET /tokens/pools/0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8?chain=eth&timeFrame=day

### Response
#### Success Response (200)
- **data** (object) - Returns OHLCV data with risk assessments for the pool and associated tokens

#### Response Example
{
  "ohlcv": [...],
  "riskAssessment": {
    "poolRiskScore": 15,
    "tokenRisks": {}
  }
}
```

--------------------------------

### Fetch Token Liquidity Pool Data - Bash API Example

Source: https://docs.webacy.com/glossary/rug-pulls

This bash script shows how to use the Webacy API to fetch detailed information about the liquidity pools associated with a given token. This is crucial for analyzing the safety and lock status of the token's liquidity. It requires an API key and the token's address.

```bash
# Check liquidity pools for a token
curl -X GET "https://api.webacy.com/tokens/0x123.../pools?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Implement Sell Restriction in Solidity

Source: https://docs.webacy.com/glossary/malicious-bool-checks

Demonstrates a honeypot pattern where users are permitted to buy tokens but are restricted from selling them, effectively locking liquidity.

```solidity
// DANGEROUS: One-way trading
bool public sellEnabled = true;

function _transfer(address from,, address to, uint256 amount) internal override {
    if (to == uniswapPair) {  // Selling to DEX
        require(sellEnabled || from == owner, "Selling disabled");
    }
    super._transfer(from, to, amount);
}
```

--------------------------------

### GET /token/analysis

Source: https://docs.webacy.com/api-reference/holder-analysis/get-detailed-early-holder-analysis-for-a-token

Retrieves a comprehensive analysis of a token's holder distribution, first-buyer behavior, and developer activity.

```APIDOC
## GET /token/analysis

### Description
Fetches detailed analytical data for a specific token, including top 10 holders, first buyer statistics, and developer minting history.

### Method
GET

### Endpoint
/token/analysis

### Parameters
#### Query Parameters
- **address** (string) - Required - The contract address of the token to analyze.
- **chain** (string) - Required - The blockchain network (e.g., solana, ethereum).

### Request Example
GET /token/analysis?address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&chain=solana

### Response
#### Success Response (200)
- **token_address** (string) - Address of the analyzed token
- **top_10_holders_analysis** (object) - Ownership distribution data for top 10 holders
- **metadata** (object) - Token name, symbol, and decimals

#### Response Example
{
  "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "top_10_holders_analysis": {
    "totalSupply": "1557599999965",
    "percentageHeldByTop10": 57.58,
    "totalHoldersCount": 19
  },
  "metadata": {
    "name": "WSamsung",
    "symbol": "WSamsung",
    "decimals": 7
  }
}
```

--------------------------------

### Configure Liquidity Monitoring Webhooks

Source: https://docs.webacy.com/glossary/liquidity-risks

Registers a webhook to receive notifications for liquidity events related to a specific token. This allows for real-time monitoring of liquidity changes.

```bash
curl -X POST "https://api.webacy.com/webhooks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "0x123...",
    "chain": "eth",
    "events": ["LIQUIDITY_CHANGE"]
  }'
```

--------------------------------

### GET /token-analysis

Source: https://docs.webacy.com/api-reference/holder-analysis/get-detailed-early-holder-analysis-for-a-token

Retrieves comprehensive holder analysis for a specific token, including optional background refresh and holder limits.

```APIDOC
## GET /token-analysis

### Description
Retrieves holder analysis data for a specified token. Supports cached data retrieval, background refetching, and limiting the number of holders analyzed.

### Method
GET

### Endpoint
/token-analysis

### Parameters
#### Query Parameters
- **useCache** (boolean) - Optional - Whether to use cached data if available (default: true)
- **refetchData** (boolean) - Optional - Whether to schedule a background refresh of analysis (default: false)
- **maxHolders** (integer) - Optional - Maximum number of holders to analyze (default: 10000, max: 50000)

### Request Example
GET /token-analysis?useCache=true&maxHolders=5000

### Response
#### Success Response (200)
- **token_address** (string) - The address of the analyzed token
- **metadata** (object) - Token name, symbol, and decimals
- **top_10_holders_analysis** (object) - Distribution metrics for top holders
- **first_buyers_analysis** (object) - Analysis of early buyer behavior and retention

#### Response Example
{
  "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "metadata": {
    "name": "USD Coin",
    "symbol": "USDC"
  }
}
```

--------------------------------

### GET /transactions/{txHash}

Source: https://docs.webacy.com/essentials/hedera

Analyze a specific Hedera transaction for risk indicators.

```APIDOC
## GET /transactions/{txHash}

### Description
Analyze a specific Hedera transaction for risk indicators using the transaction hash or ID format.

### Method
GET

### Endpoint
/transactions/{txHash}?chain=hedera

### Parameters
#### Path Parameters
- **txHash** (string) - Required - The Hedera transaction ID or hash.

#### Query Parameters
- **chain** (string) - Required - Must be set to "hedera".

### Request Example
curl -X GET "https://api.webacy.com/transactions/0.0.3229-1769183809-123000647?chain=hedera" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **risk_level** (string) - The assessed risk level of the transaction.

#### Response Example
{
  "txHash": "0.0.3229-1769183809-123000647",
  "risk_level": "low"
}
```

--------------------------------

### Manage Address Blacklisting in Solidity

Source: https://docs.webacy.com/glossary/malicious-bool-checks

Shows a standard blacklist mechanism and a safer implementation using a timelock to prevent immediate, arbitrary blocking of user addresses.

```solidity
// DANGEROUS: Arbitrary blacklisting
mapping(address => bool) public blacklisted;

function transfer(address to, uint256 amount) public override returns (bool) {
    require(!blacklisted[msg.sender], "Blacklisted");
    require(!blacklisted[to], "Blacklisted recipient");
    return super.transfer(to, amount);
}

function setBlacklist(address account, bool status) public onlyOwner {
    blacklisted[account] = status;
}
```

```solidity
// SAFER: Timelock on blacklist changes
mapping(address => bool) public blacklisted;
mapping(address => uint256) public blacklistPending;

function proposeBlacklist(address account) public onlyOwner {
    blacklistPending[account] = block.timestamp + 2 days;
    emit BlacklistProposed(account);
}

function executeBlacklist(address account) public onlyOwner {
    require(blacklistPending[account] != 0, "Not proposed");
    require(block.timestamp >= blacklistPending[account], "Timelock");
    blacklisted[account] = true;
    emit Blacklisted(account);
}
```