# Detect address poisoning for a specific wallet address
Source: https://docs.webacy.com/api-reference/address-poisoning/detect-address-poisoning-for-a-specific-wallet-address
openapi.json get /addresses/{address}/poisoning
Checks if a given wallet address has been targeted by similar-looking addresses in potential poisoning attacks.
# Get API usage for specified dates
Source: https://docs.webacy.com/api-reference/api-usage/get-api-usage-for-specified-dates
openapi.json get /usage
Retrieve API usage statistics for a specified date range
# Get current API usage
Source: https://docs.webacy.com/api-reference/api-usage/get-current-api-usage
openapi.json get /usage/current
Get current billing period API usage statistics
# Get maximum RPS for an organization
Source: https://docs.webacy.com/api-reference/api-usage/get-maximum-rps-for-an-organization
openapi.json get /usage/max-rps
Retrieves the maximum requests per second (RPS) for a given organization within a specified interval, limited to a maximum of 30 minutes.
# Approvals with threat risks
Source: https://docs.webacy.com/api-reference/approval-risks/approvals-with-threat-risks
openapi.json get /addresses/{address}/approvals
Retrieve token approvals for an address with associated threat risk analysis
# Authentication
Source: https://docs.webacy.com/api-reference/authentication
Learn how to authenticate with the Webacy API
## API Keys
All API requests require authentication using an API key passed in the `x-api-key` header.
### Getting Your API Key
1. Visit [developers.webacy.co](https://developers.webacy.co/) to sign up
2. Generate your API key
3. Copy and securely store your key
Keep your API key secure. Do not expose it in client-side code or public repositories.
## Using Your API Key
Include your API key in the `x-api-key` header with every request:
```bash theme={null}
x-api-key: YOUR_API_KEY
```
### Example Requests
```bash cURL theme={null}
curl -X GET "https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
```javascript JavaScript theme={null}
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 Python theme={null}
import requests
response = requests.get(
'https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
params={'chain': 'eth'},
headers={'x-api-key': 'YOUR_API_KEY'}
)
print(response.json())
```
```go Go theme={null}
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
req, _ := http.NewRequest("GET",
"https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e?chain=eth",
nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
## Authentication Errors
| Status Code | Description |
| ----------- | ---------------------------------------------------------------- |
| 401 | Missing or invalid API key |
| 403 | API key lacks required permissions |
| 429 | Rate limit exceeded (see [Rate Limits](/essentials/rate-limits)) |
### Example Error Response
```json theme={null}
{
"message": "Unauthorized"
}
```
## Best Practices
Store your API key in environment variables, not in your code.
* **Rotate keys periodically** - Generate new keys and deprecate old ones on a regular schedule
* **Use separate keys** - Maintain different keys for development, staging, and production
* **Monitor usage** - Check the [API Usage](/api-reference/endpoint/get-usage-current) endpoint regularly
* **Revoke compromised keys** - If a key is exposed, revoke it immediately in your dashboard
* **Server-side only** - Never expose your API key in client-side code or mobile apps
# Get a real-time analysis for a given contract address
Source: https://docs.webacy.com/api-reference/contract-risk/get-a-real-time-analysis-for-a-given-contract-address
openapi.json get /contracts/{contractAddress}
Perform real-time security analysis on a smart contract including vulnerability detection
# Get source code analysis for a contract
Source: https://docs.webacy.com/api-reference/contract-risk/get-source-code-analysis-for-a-contract
openapi.json get /contracts/{contractAddress}/code-analysis
Retrieves source code security analysis results for a given contract address. If analysis is not yet available but verified source exists, the source will be queued for processing.
# Get verified source code for a contract
Source: https://docs.webacy.com/api-reference/contract-risk/get-verified-source-code-for-a-contract
openapi.json get /contracts/{contractAddress}/source-code
Returns verified source code payload from the respective block explorer (EVM) or sources data (TON) if available. Caches results.
# Understand the Risk Profile / Risk Exposure of an Address
Source: https://docs.webacy.com/api-reference/exposure-risk/understand-the-risk-profile-risk-exposure-of-an-address
openapi.json get /quick-profile/{walletAddress}
Get a summarized risk profile including exposure to known threats and malicious entities
# Get detailed early holder analysis for a token
Source: https://docs.webacy.com/api-reference/holder-analysis/get-detailed-early-holder-analysis-for-a-token
openapi.json get /holder-analysis/{address}
Analyzes token holders, buying patterns, and detects suspicious activity such as sniper bots and coordinated buys. This endpoint provides comprehensive insights into token ownership distribution, early investor behavior, and potential risk factors.
**Supported Chains:**
- **Solana** (`sol`): Data reflects initial 10-hours window after mint with sniper detection
- **EVM chains** (`eth`, `bsc`, `pol`, `arb`, `opt`, `base`): Top holders and sniper detection
- **Stellar** (`stellar`): Address must be in `CODE:ISSUER` format
- **Sui** (`sui`): First buyers analysis with bundler detection
- **Hedera** (`hedera`): Accepts native `0.0.X` format (HTS token ID) or EVM address format. Includes token admin keys analysis (admin, freeze, wipe, pause, supply, KYC, fee schedule keys), custom fee schedules, and pause status. Sniper/bundling analysis is excluded (Hedera has deterministic transaction ordering, no MEV).
# API Introduction
Source: https://docs.webacy.com/api-reference/introduction
Overview of the Webacy Risk Score API
The Webacy Risk Score API provides comprehensive security analysis for blockchain addresses, transactions, smart contracts, tokens, and URLs. Protect your users from threats, fraud, and malicious activity across multiple blockchain networks.
## Base URL
All API requests are made to:
```text theme={null}
https://api.webacy.com
```
A development environment is also available at `https://api-development.webacy.com`.
## Supported Chains
The API supports 13 blockchain networks including Ethereum, Solana, TON, Hedera, and more.
Complete list of supported chains with their identifiers and endpoint availability
## API Categories
Analyze addresses for security threats and malicious activity
Check addresses against OFAC and other sanction lists
Real-time smart contract security analysis
Comprehensive token security and market analysis
Scan and simulate transactions for risks
Token holder distribution and sniper detection
## Response Format
Successful responses return JSON with relevant risk data:
```json theme={null}
{
"count": 1,
"medium": 0,
"high": 0,
"overallRisk": 25.99,
"issues": [],
"isContract": false
}
```
### Error Responses
```json theme={null}
{
"message": "Unauthorized"
}
```
## Rate Limits
API requests are rate-limited based on your plan. See [Rate Limits](/essentials/rate-limits) for details on limits and quotas. Use the API Usage endpoint to monitor your consumption.
## Support
Need help? Contact us at [info@webacy.com](mailto:info@webacy.com) or get your API key at [developers.webacy.co](https://developers.webacy.co/).
# Get Pool OHLCV Data with Risk Assessment
Source: https://docs.webacy.com/api-reference/pool-analysis/get-pool-ohlcv-data-with-risk-assessment
openapi.json get /tokens/pools/{poolAddress}
Retrieves OHLCV (Open, High, Low, Close, Volume) data for a liquidity pool along with risk assessment information for the pool and associated tokens. This endpoint enables comprehensive analysis of trading patterns and potential risks within a specific liquidity pool.
# Get Trending Pools with Risk Analysis
Source: https://docs.webacy.com/api-reference/pool-analysis/get-trending-pools-with-risk-analysis
openapi.json get /tokens/pools/trending
Retrieves current trending liquidity pools with comprehensive risk analysis for the pools and their associated tokens. Data is refreshed every 24 hours.
# Risk Due Diligence
Source: https://docs.webacy.com/api-reference/riskdd
Comprehensive risk analysis endpoints for addresses, tokens, and contracts
## Overview
Risk DD endpoints provide comprehensive risk due diligence for blockchain entities. Use these endpoints to analyze addresses, tokens, smart contracts, and more for security threats, fraud indicators, and compliance risks.
## Core Analysis
Fundamental risk assessment endpoints for any blockchain entity.
Analyze any address (wallet, token, or contract) for security threats, fraud indicators, and risk factors
Real-time smart contract security analysis and vulnerability detection
Comprehensive token security, market data, and manipulation detection
Token holder distribution, whale concentration, and sniper detection
Analyze URLs for phishing, malware, and security threats
Assess risk details for completed blockchain transactions
***
## Wallet Risks
Specialized endpoints for wallet-level risk assessment and compliance.
Screen addresses against OFAC and global sanction lists
Detect address poisoning attack patterns and contaminated addresses
Analyze token approvals and identify risky allowances
Quick risk profile and exposure assessment for any address
***
## When to Use Risk DD
| Use Case | Recommended Endpoints |
| ------------------------ | -------------------------------------------- |
| **Wallet screening** | Threat Risks, Sanction Checks, Exposure Risk |
| **Token due diligence** | Token Analysis, Holder Analysis |
| **Smart contract audit** | Contract Risk, Threat Risks |
| **Compliance checks** | Sanction Checks, Threat Risks |
| **Approval auditing** | Approval Risks |
| **Phishing prevention** | URL Risks |
## Example Workflow
### Screen a New Token
```bash theme={null}
# 1. Check the token contract for risks
curl -X GET "https://api.webacy.com/tokens/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
# 2. Analyze holder distribution
curl -X GET "https://api.webacy.com/holder-analysis/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
# 3. Check deployer/owner for threats
curl -X GET "https://api.webacy.com/addresses/0xdeployer...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
### Compliance Screening
```bash theme={null}
# Check address against sanctions
curl -X GET "https://api.webacy.com/addresses/sanctioned/0x123..." \
-H "x-api-key: YOUR_API_KEY"
# Full threat analysis
curl -X GET "https://api.webacy.com/addresses/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
## Related Resources
Complete list of all risk tags returned by Risk DD endpoints
Configure which risk modules to include in analysis
# Check if Wallet Address is Sanctioned
Source: https://docs.webacy.com/api-reference/sanction-checks/check-if-wallet-address-is-sanctioned
openapi.json get /addresses/sanctioned/{walletAddress}
Verify if a wallet address appears on OFAC or other sanctions lists
# Threat Considerations for an Address
Source: https://docs.webacy.com/api-reference/threat-risks/threat-considerations-for-an-address
openapi.json get /addresses/{address}
Analyze any address for security threats, fraud indicators, and risk factors across supported blockchains.
**Supported Address Types:**
- Wallet addresses (EOA)
- Token/coin addresses
- Smart contract addresses
The API automatically detects the address type and returns relevant risk analysis. You do not need to use separate endpoints for different address types.
# Get Token Economic History
Source: https://docs.webacy.com/api-reference/token-analysis/get-token-economic-history
openapi.json get /tokens/{tokenAddress}
Retrieves historical token economics data for a specific date, including price, market cap, and trading volume across multiple currencies. This endpoint also provides risk assessment and token metadata to enable comprehensive analysis of token performance at a specified point in time.
# Get Token Pools with Risk Assessment
Source: https://docs.webacy.com/api-reference/token-analysis/get-token-pools-with-risk-assessment
openapi.json get /tokens/{tokenAddress}/pools
Retrieves liquidity pools associated with a token and provides risk assessments for each related token in those pools. This endpoint helps in understanding the liquidity landscape and potential risks within the token's ecosystem.
# Get Trending Cryptocurrencies with Risk Analysis
Source: https://docs.webacy.com/api-reference/token-analysis/get-trending-cryptocurrencies-with-risk-analysis
openapi.json get /tokens/trending
We index new trending tokens every 10 minutes and provide comprehensive risk analysis, token economics, and metadata for each. This endpoint returns a complete view of trending tokens and their associated risks.
# Get simplified token analysis with security indicators
Source: https://docs.webacy.com/api-reference/trading-lite/get-simplified-token-analysis-with-security-indicators
openapi.json get /trading-lite/{address}
Returns simplified token analysis including bundler detection, sniper detection, top holder distribution, developer activity, and token authority status (mintable/freezable). Optimized for repeat calls. Currently supports Solana (sol) only.
**Security Indicators:**
- `mintable: false` = Mint authority renounced (supply is fixed) ✅
- `mintable: true` = Token supply can still be increased ⚠️
- `freezable: false` = Freeze authority renounced (accounts cannot be frozen) ✅
- `freezable: true` = Accounts can be frozen by issuer ⚠️
**Performance:**
- First call: Full analysis (~2-5 seconds)
- Cached calls: Fast response (~0.5 seconds)
- Cache TTL: 5 minutes
# Trading Due Diligence
Source: https://docs.webacy.com/api-reference/tradingdd
Trading-focused analysis endpoints for real-time market intelligence
## Overview
Trading DD endpoints provide real-time trading intelligence and market analysis. Use these endpoints for trading bots, portfolio management, and DEX integrations that require fast, actionable data.
## Trading Endpoints
Lightweight, fast risk assessment optimized for trading applications
Liquidity pool data, TVL, and trading pair information
Token holder distribution, whale concentration, and sniper detection
Scan and simulate transactions before signing
***
## Endpoint Details
### Trading Lite
Fast, lightweight risk checks optimized for trading workflows. Returns essential risk signals without the full analysis overhead.
**Best for:**
* Trading bots requiring sub-second responses
* Quick screening before trades
* High-volume applications
```bash theme={null}
curl -X GET "https://api.webacy.com/trading-lite/So111...?chain=sol" \
-H "x-api-key: YOUR_API_KEY"
```
***
### Pool Analysis
Get detailed liquidity pool information including TVL, trading pairs, and pool health metrics.
**Best for:**
* DEX aggregators
* Liquidity analysis
* Price impact estimation
* Slippage calculation
```bash theme={null}
# 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"
```
***
### Holder Analysis
Analyze token holder distribution to identify concentration risks, whale movements, and sniper activity.
**Best for:**
* Detecting insider concentration
* Identifying sniper wallets
* Whale watching
* Token distribution analysis
```bash theme={null}
curl -X GET "https://api.webacy.com/holder-analysis/So111...?chain=sol" \
-H "x-api-key: YOUR_API_KEY"
```
***
### Transaction Scanning
Simulate and analyze transactions before they're signed. Essential for wallet security and transaction preview features.
**Best for:**
* Wallet transaction previews
* dApp transaction validation
* Phishing detection
* Approval screening
```bash theme={null}
# Scan a pending transaction
curl -X POST "https://api.webacy.com/scan/0xfrom.../transactions" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "0xto...",
"data": "0x...",
"value": "1000000000000000000",
"chain": "eth"
}'
# Scan EIP-712 typed data
curl -X POST "https://api.webacy.com/scan/0xfrom.../eip712" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"typedData": {
"domain": { "name": "Example", "version": "1", "chainId": 1 },
"types": { "Message": [{ "name": "content", "type": "string" }] },
"primaryType": "Message",
"message": { "content": "Hello" }
},
"chain": "eth"
}'
```
***
## When to Use Trading DD
| Use Case | Recommended Endpoints |
| ---------------------- | ----------------------------------- |
| **Trading bots** | Trading Lite, Pool Analysis |
| **DEX integrations** | Pool Analysis, Transaction Scanning |
| **Wallet security** | Transaction Scanning |
| **Liquidity analysis** | Pool Analysis |
| **Pre-trade checks** | Trading Lite, Transaction Scanning |
| **Token analysis** | Holder Analysis, Pool Analysis |
| **Whale watching** | Holder Analysis |
## Trading DD vs Risk DD
| Aspect | Trading DD | Risk DD |
| ----------------- | ------------------------- | ---------------------- |
| **Speed** | Optimized for low latency | Comprehensive analysis |
| **Depth** | Essential signals | Full risk breakdown |
| **Use case** | Real-time trading | Due diligence |
| **Response size** | Minimal | Detailed |
For trading applications, start with **Trading Lite** for speed. Use **Risk DD** endpoints when you need deeper analysis or compliance checks.
## Example Trading Workflow
```javascript theme={null}
// 1. Quick risk check before trade
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;
}
// 2. Check liquidity
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...
```
## Related Resources
Full risk due diligence endpoints for deeper analysis
Real-time push notifications for trading events
# Risk Details for a Transaction
Source: https://docs.webacy.com/api-reference/transaction-risks/risk-details-for-a-transaction
openapi.json get /transactions/{txHash}
Get comprehensive risk analysis for a specific blockchain transaction
# Scan EIP-712 Signed Message for Security Risks
Source: https://docs.webacy.com/api-reference/transaction-scanning/scan-eip-712-signed-message-for-security-risks
openapi.json post /scan/{fromAddress}/eip712
Analyzes an EIP-712 typed data signature for security risks including malicious domains, suspicious contracts, and potential phishing attempts. Supports Ethereum (1), BSC (56), Polygon (137), Optimism (10), Arbitrum (42161), and Base (8453). The chain is determined by the chainId field in the EIP-712 domain.
# Scan Raw EVM Transaction for Security Risks
Source: https://docs.webacy.com/api-reference/transaction-scanning/scan-raw-evm-transaction-for-security-risks
openapi.json post /scan/{fromAddress}/transactions
Analyzes a raw EVM transaction for security risks including malicious contracts, suspicious addresses, and potential threats. Supports Ethereum (1), BSC (56), Polygon (137), Optimism (10), Arbitrum (42161), and Base (8453).
# Project URL Risk Analysis
Source: https://docs.webacy.com/api-reference/url-risks/project-url-risk-analysis
openapi.json post /url
Analyze a URL for phishing, malware, and other security threats
# API Considerations
Source: https://docs.webacy.com/essentials/considerations
Important considerations for using the Webacy API effectively
## Overview
The Webacy API is designed for high performance and accuracy. Understanding these considerations will help you get the most out of your integration.
## Speed & Latency
Initial scans may take up to **3 seconds** while our Risk Engine analyzes the address. Subsequent requests for the same address return much faster.
### How It Works
1. **First Request** - Full analysis runs, may take 1-3 seconds
2. **Subsequent Requests** - Returns cached results instantly
3. **Background Refresh** - System automatically re-analyzes addresses over time
### Optimization Tips
* Cache results on your end for frequently queried addresses
* Use webhooks for real-time updates instead of polling
* Batch your initial queries during off-peak hours if possible
## Pre-Loading
For high-traffic applications, we offer custom pre-loading of specific token and address lists.
Pre-loading eliminates cold-start latency by ensuring addresses are already analyzed before your users query them.
### Request Pre-Loading
Contact our team at [info@webacy.com](mailto:info@webacy.com) to set up pre-loading for:
* Token contract addresses you frequently analyze
* Watchlists of addresses your users interact with
* New token launches you want to monitor
## Failures & Retries
When an endpoint fails, the address is automatically queued for retry analysis.
### Handling Failures
```javascript theme={null}
async function getAddressRisk(address, chain, retries = 3) {
for (let i = 0; i < retries; i++) {
try {
const response = await fetch(
`https://api.webacy.com/addresses/${address}?chain=${chain}`,
{ headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
if (response.ok) {
return await response.json();
}
// Wait before retry (exponential backoff)
await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
} catch (error) {
if (i === retries - 1) throw error;
}
}
}
```
If you hit a failure, retry the request. Our system queues failed addresses for background processing, so a retry often succeeds.
## Data Freshness
The API balances speed and accuracy through intelligent caching.
### Cache Behavior
| Scenario | Behavior |
| ------------------- | -------------------------------- |
| First request | May return cached data for speed |
| Subsequent requests | Triggers background refresh |
| Maximum cache age | **24 hours** |
### Forcing Fresh Data
For critical operations, you can request fresh analysis:
```bash theme={null}
# Use refreshCache parameter where available
curl -X GET "https://api.webacy.com/addresses/0x...?chain=eth&refreshCache=true" \
-H "x-api-key: YOUR_API_KEY"
```
Our data is regularly updated and never retains a cache longer than 24 hours. For most use cases, cached data is sufficiently current.
## Best Practices Summary
1. **Expect initial latency** - First scans take longer, plan your UX accordingly
2. **Implement retries** - Use exponential backoff for failed requests
3. **Cache strategically** - Store results for frequently queried addresses
4. **Request pre-loading** - For high-traffic use cases, contact us for pre-loading
5. **Trust the cache** - 24-hour cache is sufficient for most risk assessments
## Need Help?
Our team is continuously improving these endpoints. If you have feedback or need custom solutions, contact us at [info@webacy.com](mailto:info@webacy.com).
# Hedera
Source: https://docs.webacy.com/essentials/hedera
Hedera blockchain support and risk analysis
## Overview
The Webacy API provides risk assessment for the Hedera blockchain ecosystem. Analyze Hedera accounts, tokens, and transactions for security threats, malicious activity, and risk factors.
Hedera support includes native Hedera Token Service (HTS) analysis with admin key detection, custom fee analysis, and account status monitoring.
## Supported Endpoints
### Address Risk Analysis
Analyze any Hedera account for security threats and risk factors. Sanction checks are included in the response.
```bash theme={null}
GET /addresses/{address}?chain=hedera
```
### Transaction Risk Analysis
Analyze a specific Hedera transaction for risk indicators.
```bash theme={null}
GET /transactions/{txHash}?chain=hedera
```
### Holder Analysis
Analyze token holder distribution and detect suspicious activity for HTS tokens.
```bash theme={null}
GET /holder-analysis/{address}?chain=hedera
```
## Address Formats
Hedera supports two address formats:
| Type | Format | Example |
| ------------- | ------------------------- | -------------------------------------------- |
| Native | `0.0.X` (shard.realm.num) | `0.0.731861` |
| EVM Long-Zero | 0x + 24 zeros + hex | `0x00000000000000000000000000000000000b2ad5` |
Both formats are accepted across all Hedera endpoints.
For holder analysis, use the native HTS token ID format (`0.0.X`), for example `0.0.731861`.
## Transaction ID Formats
Hedera transaction IDs use a unique format with the payer account and timestamp:
| Format | Example |
| ---------------- | ------------------------------- |
| `-` separator | `0.0.3229-1769183809-123000647` |
| `@` separator | `0.0.3229@1769183809.123000647` |
| Transaction hash | Base64-encoded hash |
All three formats are accepted by the transactions endpoint.
## Example Requests
### Address Risk Analysis
```bash theme={null}
curl -X GET "https://api.webacy.com/addresses/0.0.731861?chain=hedera" \
-H "x-api-key: YOUR_API_KEY"
```
### Transaction Risk Analysis
```bash theme={null}
curl -X GET "https://api.webacy.com/transactions/0.0.3229-1769183809-123000647?chain=hedera" \
-H "x-api-key: YOUR_API_KEY"
```
### Holder Analysis
```bash theme={null}
curl -X GET "https://api.webacy.com/holder-analysis/0.0.731861?chain=hedera" \
-H "x-api-key: YOUR_API_KEY"
```
## Hedera-Specific Risk Tags
### Token Risk Tags
These risk tags analyze HTS token admin keys, fees, and state:
| Tag | Severity | Description |
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `hedera-token-has-freeze` | Critical | Token has an active freeze key. Issuer can freeze any holder's balance. |
| `hedera-token-has-wipe` | Critical | Token has an active wipe key. Issuer can wipe tokens from any account. |
| `hedera-token-pausable` | Critical | Token has an active pause key. Issuer can pause all token operations. |
| `hedera-token-currently-paused` | Critical | Token is currently paused. No transfers or operations are possible. |
| `hedera-token-excessive-fees` | Critical | Custom fee percentage exceeds 25%. Strong honeypot indicator. |
| `hedera-token-high-fees` | High | Custom fee percentage exceeds 10%. May indicate a fee-based trap. |
| `hedera-token-has-supply-key` | Medium | Token has an active supply key with no max supply cap. Issuer can mint unlimited tokens. |
| `hedera-token-modifiable-fees` | Medium | Token fees can be changed by the issuer via fee schedule key. |
| `hedera-token-keys-renounced` | Positive | All admin keys have been renounced. Token is fully decentralized. |
### Account Risk Tags
| Tag | Severity | Description |
| ------------------------------ | -------- | ------------------------------------------------------ |
| `hedera-account-deleted` | High | Account has been deleted from the network. |
| `hedera-account-expired` | High | Account has expired due to insufficient HBAR for rent. |
| `hedera-account-expiring-soon` | Low | Account expiry timestamp is approaching. |
## Additional Risk Tags
Standard risk tags also apply to Hedera addresses:
* `sanctioned` - Address appears on sanction lists (OFAC, OpenSanctions)
* `insufficient_wallet_age` - Account is very new
* `insufficient_wallet_balance` - Low account balance
* `insufficient_wallet_transactions` - Limited transaction history
* Holder concentration tags (top holders owning significant percentages)
## Example Responses
### Transaction Risk Response
```json theme={null}
[
{
"partyRisk": {
"high": 1,
"count": 2,
"issues": [
{
"tags": [
{
"key": "hedera-account-expired",
"name": "Account Expired",
"type": "hedera_account_status_risk",
"severity": 8,
"description": "This Hedera account has expired due to insufficient HBAR for rent."
}
],
"score": 8,
"riskScore": "High Risk"
}
],
"medium": 0,
"details": {
"address_info": {
"balance": 370969324948,
"sanctioned": false,
"ofac_sanctioned": false,
"transaction_count": 0,
"hedera_account_expired": true
}
},
"overallRisk": 63.24,
"address": "0.0.3229"
},
"counterpartyRisk": {
"high": 0,
"count": 1,
"overallRisk": 0,
"address": "0.0.801"
},
"assetRisk": {
"address": "HBAR"
},
"txData": {
"transaction_id": "0.0.3229-1769183809-123000647",
"consensus_timestamp": "1769183819.484953000",
"type": "CRYPTOTRANSFER",
"result": "SUCCESS",
"fee_charged": 94133,
"scheduled": false,
"transfers": [
{ "account": "0.0.801", "amount": 90309 },
{ "account": "0.0.3229", "amount": -94134 }
],
"token_transfers": [],
"nft_transfers": []
}
}
]
```
### Holder Analysis Response
```json theme={null}
{
"token_address": "0.0.731861",
"metadata": {
"name": "SAUCE",
"symbol": "SAUCE"
},
"first_buyers_analysis": {
"initially_acquired_percentage": 2.29,
"buyers_analyzed_count": 48,
"unique_buyers": 48,
"buyers_still_holding": 37,
"dev_holdings_percentage": 0.7
},
"top_10_holders_analysis": {
"totalHoldersCount": 33050,
"topHolders": [
{ "ownerAddress": "0.0.1460199", "percentage": 15.24 },
{ "ownerAddress": "0.0.3951117", "percentage": 14.88 },
{ "ownerAddress": "0.0.1461945", "percentage": 12.52 }
],
"top_5_concentration": 68.94,
"top_10_concentration": 73.61,
"top_20_concentration": 79.49
},
"token_keys": {
"admin_key_present": true,
"freeze_key_present": false,
"wipe_key_present": false,
"pause_key_present": false,
"supply_key_present": true,
"kyc_key_present": false,
"fee_schedule_key_present": false
},
"custom_fees": [],
"pause_status": "UNPAUSED",
"is_deleted": false
}
```
## Holder Analysis Details
Hedera holder analysis includes features specific to the Hedera Token Service:
* **Token admin keys analysis** - Checks for admin, freeze, wipe, pause, supply, KYC, and fee schedule keys
* **Custom fee schedules** - Detects fixed fees, fractional fees, and royalty fees on tokens
* **Pause status** - Whether the token is currently paused (`PAUSED`, `UNPAUSED`, or `NOT_APPLICABLE`)
* **No MEV/sniper detection** - Hedera has deterministic transaction ordering, so sniper and bundling analysis is excluded
## Best Practices
1. **Check token admin keys** - Tokens with active freeze, wipe, or pause keys carry higher risk. Look for `hedera-token-keys-renounced` as a positive signal.
2. **Watch for custom fees** - High or excessive custom fees (>10%) are a common honeypot pattern on Hedera.
3. **Use native format for tokens** - Use the `0.0.X` HTS token ID format for holder analysis rather than EVM addresses.
4. **Account status matters** - Check for deleted or expired accounts before transacting.
5. **No MEV on Hedera** - Unlike EVM chains, Hedera has deterministic transaction ordering, so sniper/bundler detection is not applicable.
# Label Types
Source: https://docs.webacy.com/essentials/label-types
Address label classifications and subtypes
## Overview
The Webacy API categorizes blockchain addresses into label types to help identify the nature and purpose of addresses.
## Primary Label Types
| Type | Description |
| ---------- | ------------------------------------- |
| `cex` | Centralized Exchange |
| `dex` | Decentralized Exchange |
| `operator` | Chain Operations (validators, miners) |
| `chadmin` | Chain Administration |
| `defi` | Decentralized Finance Applications |
| `nft` | NFT Contracts & Applications |
| `bridge` | Layer 2/Alt L1 Bridge Dapps |
| `dapp` | Decentralized Applications |
| `games` | Gaming Dapps |
| `token` | Token Contracts |
| `flotsam` | Junk or Uncategorized |
***
## Label Subtypes
### Centralized Exchange (cex)
| Subtype | Description |
| ------------------- | ------------------------------------------------------------ |
| `hot_wallet` | Addresses that collect funds from deposits, send withdrawals |
| `deposit_wallet` | Exchange deposit addresses |
| `cold_wallet` | Rarely-used fund storage |
| `chadmin` | Exchange administration |
| `contract_deployer` | Contract creation contracts |
| `general_contract` | General-purpose contracts |
| `multisig` | Multi-signature wallets |
| `token_contract` | Exchange-owned tokens |
### Decentralized Exchange (dex)
| Subtype | Description |
| -------------------- | --------------------------------- |
| `swap_contract` | Token exchange facilitation |
| `token_contract` | DEX-associated tokens |
| `pool` | Farming, staking, liquidity pools |
| `vault` | DEX-controlled vaults |
| `fee_wallet` | Fee collection |
| `dao` | DAO control addresses |
| `chadmin` | Administrative addresses |
| `contract_deployer` | Contract creators |
| `foundation` | Foundation addresses |
| `governance` | Governance contracts |
| `rewards` | Reward distribution |
| `strategy` | Strategy contracts |
| `token_distribution` | Token distribution contracts |
| `token_sale` | Token sale contracts |
| `general_contract` | General contracts |
| `multisig` | Multi-signature wallets |
### Operator
| Subtype | Description |
| ------------- | -------------------------------------------- |
| `validator` | Addresses that run nodes and validate blocks |
| `mining_pool` | Known mining pools |
| `solo_miner` | Individual block reward recipients |
### Chain Admin (chadmin)
| Subtype | Description |
| ------------------ | -------------------------- |
| `genesis` | Mint/burn addresses |
| `foundation` | Chain foundation addresses |
| `general_contract` | Other chadmin contracts |
### DeFi
| Subtype | Description |
| ------------------- | -------------------- |
| `token_contract` | DeFi tokens |
| `pool` | Liquidity pools |
| `vault` | Vaults |
| `fee_wallet` | Fee collection |
| `dao` | DAO addresses |
| `voting` | Voting contracts |
| `chadmin` | Admin addresses |
| `contract_deployer` | Contract deployers |
| `treasury` | Treasury addresses |
| `governance` | Governance contracts |
| `rewards` | Reward contracts |
| `oracle` | Price oracles |
| `token_sale` | Token sales |
| `general_contract` | General contracts |
| `multisig` | Multi-sig wallets |
### NFT
| Subtype | Description |
| ------------------- | ------------------ |
| `token_contract` | Fungible tokens |
| `nf_token_contract` | NFT contracts |
| `contract_deployer` | Contract deployers |
| `fee_contract` | Fee contracts |
| `marketplace` | NFT marketplaces |
| `general_contract` | General contracts |
### Flotsam (Risky/Junk)
| Subtype | Description |
| ------- | ----------------------------------- |
| `toxic` | Scams, attacks, malicious addresses |
| Other | Uncategorized addresses |
***
## Using Labels in Risk Assessment
Labels provide context for risk evaluation:
```javascript theme={null}
function assessRisk(address, labels) {
// Known exchanges are generally lower risk
if (labels.type === 'cex' && labels.subtype === 'hot_wallet') {
return 'low';
}
// Toxic flotsam is high risk
if (labels.type === 'flotsam' && labels.subtype === 'toxic') {
return 'high';
}
return 'medium';
}
```
## Response Example
```json theme={null}
{
"address": "0x...",
"labels": {
"type": "cex",
"subtype": "hot_wallet",
"name": "Binance",
"confidence": 0.99
}
}
```
Need more granular labels? Contact our team at [info@webacy.com](mailto:info@webacy.com) to discuss custom label solutions.
# Modules
Source: https://docs.webacy.com/essentials/modules
Risk assessment modules for targeted analysis
## Overview
The Webacy API uses a modular approach to risk assessment. Select specific modules to optimize performance and focus on relevant risk categories.
When selecting specific modules, the risk score reflects only the selected modules, not a comprehensive view of the address's risk profile.
## Available Modules
### Security Essentials
Essential security checks for real-time applications.
**Risk Tags:** `not-renounced`, `freezeable`, `mintable`
**Use Cases:** Trading interfaces, wallet integrations, real-time screening
***
### Governance Analysis
Contract ownership, upgradeability, and access controls.
**Risk Tags:** `hidden_owner`, `can_take_back_ownership`, `is_proxy`, `access_control`, `unprotected_upgrade`, `anti_whale_modifiable`, `slippage_modifiable`, `upgradeable_contract`, `trust_list`
**Use Cases:** DeFi protocol analysis, smart contract auditing, governance evaluation
***
### Token Security
Token manipulation capabilities and restrictions.
**Risk Tags:** `freezeable`, `mintable`, `is_blacklisted`, `is_whitelisted`, `owner_change_balance`, `transfer_without_approval`, `privileged_burn`, `oversupply_minting`, `trading_cooldown`, `transfer_pausable`, `buy_tax`, `sell_tax`, `is_anti_whale`, `non-transferable`, `is_burnable`
**Use Cases:** Token screening, DEX listings, portfolio management, trading bot integration
***
### Contract Analysis
Static and dynamic code analysis with vulnerability detection.
**Risk Tags:** `is_closed_source`, `selfdestruct`, `external_call`, reentrancy vulnerabilities, integer overflow/underflow, front-running variants, mint risks, `centralized_risk`, `price_manipulation`, `locked_ether`, `weak_prng`, timestamp issues, 50+ additional vulnerability tags
**Use Cases:** Security audits, DeFi risk assessment, smart contract due diligence
***
### Market Data
Price, volatility, market cap, and liquidity analysis.
**Risk Tags:** `volatility`, `market_cap`, `is_in_dex`, `cannot_buy`, `is_honeypot`, `honeypot_with_same_creator`
**Use Cases:** Trading algorithms, market analysis, portfolio optimization
***
### Holder Analysis
Token distribution and concentration risks.
**Risk Tags:** Top-10-holders percentages (10%-100%), minter/owner/update-authority ownership percentages
**Use Cases:** Investment research, rugpull prevention, tokenomics analysis, whale monitoring
***
### Liquidity Analysis
Pool data, unlock schedules, and LP analysis.
**Risk Tags:** `unlocked-liquidity`, `lp_holder_count`, `lp_total_supply`, `creator_balance`, `creator_percent`, `owner_balance`, `owner_percent`
**Use Cases:** DeFi investments, yield farming, liquidity provision, rugpull prevention
***
### Fraud Detection
Malicious actor and rugpull detection.
**Risk Tags:** `hacker`, `drainer`, associated variants, `rugged`, `stealing_attack`, `financial_crime`, `cybercrime`, `exploitation`, fundflow associations
**Use Cases:** AML compliance, fraud prevention, risk screening, security monitoring
***
### Sanctions Compliance
Regulatory compliance and sanctions screening.
**Risk Tags:** `sanctioned`, `associated_sanctioned`, `ofac_sanctioned`, OFAC associations, `fundflow_ofac`
**Use Cases:** Compliance programs, regulatory reporting, KYC/AML, institutional trading
***
### Mixer Detection
Privacy coin and mixer usage detection.
**Risk Tags:** `mixer`, `associated_mixer`, `tornado`, `associated_tornado`, mixer services, `fixedfloat`, `simpleswap`, fundflow variants
**Use Cases:** AML compliance, transaction monitoring, regulatory reporting
***
### Address Behavior
Trading patterns and behavioral analysis.
**Risk Tags:** `wash_trading`, `automated_trading`, `money_laundering`, `darkweb_transactions`, `malicious_mining_activities`, `blackmail_activities`, `phishing_activities`, `deployed_high_volatility_token`, `malicious_contracts_created`
**Use Cases:** Behavioral analysis, fraud detection, compliance monitoring, bot detection
***
### Transaction Analysis
Transaction-level risk detection.
**Risk Tags:** `address_poisoning`
**Use Cases:** Wallet security, transaction monitoring, attack prevention
***
### Reputation Analysis
Community reports and reputation scoring.
**Risk Tags:** `blacklist_doubt`, `spam_domain`, `spam`, `valid_report`, `fake_kyc`, `is_fake_token`, `is_true_token`, `is_scam`, `illegal_unicode`, `is_airdrop_scam`
**Use Cases:** Community-driven security, reputation systems, scam prevention
***
## Chain-Specific Modules
### Solana Specific
**Risk Tags:** `has_been_sniped`, `bundled_token`, `mutable-metadata`, recently minted tokens, `impersonator`, `known-malicious-token`
### TON Specific
**Risk Tags:** `is_nonstandard_jetton`, `is_nonstandard_jetton_wallet`
### Basic Info
Fast metadata checks for quick screening.
**Risk Tags:** `insufficient_wallet_age`, `insufficient_wallet_balance`, `insufficient_wallet_transactions`
***
## Recommended Combinations
| Use Case | Modules |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Real-Time Trading | `security_essentials` |
| Security Analysis | `token_security`, `fraud_detection`, `sanctions_compliance`, `contract_analysis` |
| Investment Research | `market_data`, `liquidity_analysis`, `holder_analysis`, `governance_analysis` |
| AML Compliance | `sanctions_compliance`, `fraud_detection`, `mixer_detection`, `address_behavior` |
| Comprehensive | `security_essentials`, `token_security`, `fraud_detection`, `sanctions_compliance`, `market_data`, `liquidity_analysis` |
## Usage Example
```bash theme={null}
curl -X GET "https://api.webacy.com/addresses/0x...?chain=eth&modules=security_essentials,fraud_detection" \
-H "x-api-key: YOUR_API_KEY"
```
# Rate Limits
Source: https://docs.webacy.com/essentials/rate-limits
API rate limits and quotas for Webacy API
## Rate Limit Tiers
**Need higher limits?** Production and enterprise tiers offer significantly increased rate limits. Contact us at [info@webacy.com](mailto:info@webacy.com) to upgrade your plan.
| Tier | Requests/sec | Burst Capacity | Monthly Quota |
| ---------- | ------------ | -------------- | ------------- |
| Demo | 2 | 5 requests | 2,000 |
| Production | 10 | 20 requests | 100,000 |
| Enterprise | Custom | Custom | Unlimited |
### Demo Tier
For demo API keys, the following restrictions apply:
| Limit Type | Value |
| ------------------- | -------------- |
| Requests per second | 2 |
| Burst capacity | 5 requests |
| Monthly quota | 2,000 requests |
### Production Tier
Production API keys provide increased limits suitable for live applications:
| Limit Type | Value |
| ------------------- | ---------------- |
| Requests per second | 10 |
| Burst capacity | 20 requests |
| Monthly quota | 100,000 requests |
### Enterprise Tier
Enterprise customers receive fully customizable limits:
* **Requests per second**: Up to 100+ (custom)
* **Monthly quota**: Unlimited
* **Dedicated support**: Priority response times
* **SLA**: 99.9% uptime guarantee
## Rate Limit Headers
The API returns rate limit information in response headers:
| Header | Description |
| ----------------------- | ------------------------------------ |
| `X-RateLimit-Limit` | Maximum requests allowed |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the limit resets |
## Handling Rate Limits
When you exceed the rate limit, the API returns a `429 Too Many Requests` response:
```json theme={null}
{
"message": "Rate limit exceeded"
}
```
### Best Practices
Implement exponential backoff when you receive a 429 response.
* **Cache responses** - Avoid redundant API calls for the same data
* **Batch requests** - Use batch endpoints where available
* **Monitor usage** - Use the [API Usage](/api-reference/api-usage/get-current-api-usage) endpoint to track consumption
* **Implement queuing** - Queue requests during high-traffic periods
## Increasing Your Limits
When your integration is production-ready and you need higher limits:
1. **Developer Portal** - Upgrade at [developers.webacy.co](https://developers.webacy.co/)
2. **Account Manager** - Contact your account manager for enterprise plans
3. **Support** - Email [info@webacy.com](mailto:info@webacy.com)
## Enterprise Plans
Enterprise customers receive:
* Higher requests per second limits
* Increased monthly quotas
* Priority support
* Custom rate limit configurations
# Risk Levels
Source: https://docs.webacy.com/essentials/risk-levels
Understanding risk scores and classifications in Webacy API
## Risk Score Overview
The Webacy API returns an `overallRisk` score from 0 to 100, where higher scores indicate greater risk.
Risk levels are guidelines and may need adjustment for your specific use case. We recommend examining the response fields and specific issue tags to build more robust, customized risk policies.
## Risk Classifications
| Overall Risk Range | Classification | Meaning |
| ------------------ | -------------- | -------------------------------------- |
| 0 - 23 | Low Risk | Address shows minimal risk indicators |
| 23.1 - 50 | Medium Risk | Address has some concerning signals |
| 50.1 - 100 | High Risk | Address shows significant risk factors |
## Response Fields
The API returns several risk-related fields:
```json theme={null}
{
"overallRisk": 25.99,
"count": 3,
"medium": 2,
"high": 1,
"issues": [
{
"tag": "wash_trading",
"severity": "medium",
"description": "Address has engaged in wash trading"
}
]
}
```
| Field | Description |
| ------------- | ----------------------------------------- |
| `overallRisk` | Aggregate risk score (0-100) |
| `count` | Total number of risk flags detected |
| `medium` | Count of medium-severity issues |
| `high` | Count of high-severity issues |
| `issues` | Array of specific risk flags with details |
## Issue Severity Levels
Individual risk issues have their own severity:
| Severity | Weight | Examples |
| ---------- | ---------------- | -------------------------------------------------------- |
| **Low** | Minor impact | `insufficient_wallet_age`, `insufficient_wallet_balance` |
| **Medium** | Moderate concern | `wash_trading`, `is_proxy`, `freezeable` |
| **High** | Significant risk | `sanctioned`, `hacker`, `drainer`, `rugged` |
## Calculating Custom Risk Scores
You can build custom risk logic using the raw data:
```javascript theme={null}
function calculateCustomRisk(response) {
const { count, medium, high, issues } = response;
// Custom weighting
let score = 0;
score += high * 30; // High severity issues
score += medium * 15; // Medium severity issues
score += (count - high - medium) * 5; // Low severity
return Math.min(score, 100);
}
```
## Using Modules for Targeted Analysis
Use [modules](/essentials/modules) to request specific risk categories:
* **Security-focused**: `security_essentials`, `token_security`, `fraud_detection`
* **Compliance-focused**: `sanctions_compliance`, `mixer_detection`
* **Investment-focused**: `holder_analysis`, `liquidity_analysis`, `market_data`
When using modules, the risk score reflects only the selected modules, not a comprehensive assessment.
## Best Practices
1. **Don't rely solely on `overallRisk`** - Review individual `issues` for context
2. **Consider the use case** - Trading apps may weight different risks than compliance tools
3. **Use appropriate modules** - Select modules relevant to your risk assessment needs
4. **Combine with other signals** - Use risk scores alongside your own business logic
# Risk Tags Reference
Source: https://docs.webacy.com/essentials/risk-tags
Complete reference of all risk tags returned by the Webacy API
## Overview
Risk tags are specific indicators returned by the API that identify potential security issues, fraud patterns, or risk factors. Each tag includes a severity level and description.
Use the [modules parameter](/essentials/modules) to filter which risk tags are analyzed for your specific use case.
***
## Token Risk Tags
Tags related to token contract security and manipulation risks.
| Tag | Name | Description |
| ---------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `is_closed_source` | Closed Source | Closed-sourced contracts may hide various unknown mechanisms and are extremely risky. It might also be a fake token, since most major tokens are open sourced. |
| `hidden_owner` | Hidden Owner | Hidden ownership is used by developers to maintain ownership ability even after abandoning ownership, and is often an indicator of malicious intent. |
| `is_honeypot` | Honeypot | A honeypot contract may prevent sale or transfer of tokens, or non-standard code, some honeypots contain seemingly vulnerable code to lure hackers. |
| `honeypot_with_same_creator` | Honeypot | A honeypot contract may prevent sale or transfer of tokens, created by a known honeypot creator. |
| `buy_tax` | Buy Tax | When buying a token, a buy tax will cause the actual token value received to be less than the amount paid. An excessive buy tax may lead to heavy losses. |
| `sell_tax` | Sell Tax | A sell tax will cause the actual value received when selling a token to be less than expected. Too much sell tax may lead to large losses. |
| `slippage_modifiable` | Slippage Modifiable | The contract owner can modify the buy tax or sell tax of the token. Some contracts have unlimited modifiable tax rates, which would make the token untradeable. |
| `is_blacklisted` | Blacklisting | A blacklist function is included. The contract owner may add any address to the blacklist, preventing them from trading. |
| `is_whitelisted` | Whitelisting | Whitelisting functionality allows specific addresses to make early transactions, tax-free, and not affected by transaction suspension. |
| `can_take_back_ownership` | Reclaim Ownership | Ownership can be reclaimed after being abandoned, allowing risky functions to be reactivated. |
| `owner_change_balance` | Change Balance | The owner can modify anyone's balance, resulting in assets being changed or a massive minting and sell-off. |
| `is_airdrop_scam` | Airdrop Scam | An airdrop scam attempts to get you to visit a fake project site and connect your wallet to steal your funds. |
| `trust_list` | Trusted | This asset is a trusted, widely known project, and is verified as authentic. |
| `is_fake_token` | Fake Token | This asset is an unauthentic knockoff for an existing project. |
| `illegal_unicode` | Deceptive Token | The name or symbol contains unicode characters that appear deceptively similar to letters. Often used to spoof real tokens. |
| `exploitation` | Exploitation | This asset has been exploited in the past and may be vulnerable to future exploits. |
| `anti_whale_modifiable` | Anti Whale Modifiable | The maximum transaction amount or token position for a single address can be modified at any time. |
| `is_anti_whale` | Anti Whale | The contract limits the maximum transaction amount or token position, often to prevent price manipulation. |
| `non-transferable` | Non Transferable | Tokens cannot be transferred between addresses, limiting utility and liquidity. |
| `not-renounce` | Not Renouncable | The owner cannot renounce ownership, limiting decentralization. |
| `freezeable` | Freezeable | Token transfers can be frozen by a central authority, posing censorship or manipulation risk. |
| `mintable` | Mintable | Tokens can be created by the minter, introducing inflationary risks if not properly controlled. |
| `mutable-metadata` | Mutable Metadata | Token metadata can be modified, potentially leading to misinformation or manipulation. |
### Token Age Tags
| Tag | Name | Description |
| ----------------------------- | ------------- | -------------------------------------------------------- |
| `minted-less-than-10-minutes` | Token Too New | Tokens minted within 10 minutes, potentially suspicious. |
| `minted-less-than-1-hour` | Token Too New | Tokens minted within 1 hour, potentially suspicious. |
| `minted-less-than-1-day` | Token Too New | Tokens minted within 1 day, potentially suspicious. |
### Ownership Concentration Tags
| Tag | Name | Description |
| --------------------------------- | ------------------------------ | ----------------------------------------------------------------- |
| `top-10-holders-own-90-percent` | Unbalanced Ownership | Top 10 holders control 90% of supply, high manipulation risk. |
| `top-10-holders-own-50-percent` | Unbalanced Ownership | Top 10 holders control 50% of supply, moderate manipulation risk. |
| `top-10-holders-own-20-percent` | Unbalanced Ownership | Top 10 holders control 20% of supply, some concentration risk. |
| `minter-own-90-percent` | Unbalanced Ownership (Minter) | Minter holds 90% of supply. |
| `minter-own-50-percent` | Unbalanced Ownership (Minter) | Minter holds 50% of supply. |
| `minter-own-20-percent` | Unbalanced Ownership (Minter) | Minter holds 20% of supply. |
| `owner-own-90-percent` | Unbalanced Ownership (Owner) | Owner holds 90% of supply. |
| `owner-own-50-percent` | Unbalanced Ownership (Owner) | Owner holds 50% of supply. |
| `owner-own-20-percent` | Unbalanced Ownership (Owner) | Owner holds 20% of supply. |
| `update-authority-own-90-percent` | Unbalanced Ownership (Updater) | Update authority holds 90% of supply. |
| `update-authority-own-50-percent` | Unbalanced Ownership (Updater) | Update authority holds 50% of supply. |
| `update-authority-own-20-percent` | Unbalanced Ownership (Updater) | Update authority holds 20% of supply. |
### Rugpull Tags
| Tag | Name | Description |
| ---------------------------------- | --------------------------- | --------------------------------------------- |
| `minter-rugged` | Minter is Rugpuller | The minter has executed a rugpull. |
| `minter-multiple-rugged` | Minter is Repeat Rugpuller | Multiple rugpulls associated with the minter. |
| `owner-rugged` | Owner is Rugpuller | The owner has executed a rugpull. |
| `owner-multiple-rugged` | Owner is Repeat Rugpuller | Multiple rugpulls by the owner. |
| `update-authority-rugged` | Updater is Rugpuller | The update authority has conducted a rugpull. |
| `update-authority-multiple-rugged` | Updater is Repeat Rugpuller | Multiple rugpulls by update authorities. |
| `top-10-holders-rugged` | Top Holders are Rugpullers | Top holders have executed rugpulls. |
| `top-10-holders-multiple-rugged` | Top Holders are Rugpullers | Top holders have executed multiple rugpulls. |
### Associated Risk Tags (Minter)
| Tag | Name | Description |
| ------------------------- | ----------------------- | ---------------------------------------------- |
| `minter-hacker` | Minter is Hacker | The minter has been compromised by hackers. |
| `minter-ofac` | Minter is Sanctioned | Minter involved with OFAC-sanctioned entities. |
| `minter-drainer` | Minter is Drainer | The minter is draining funds or assets. |
| `minter-mixer` | Minter is Mixer | Minter involved in mixing/tumbling schemes. |
| `minter-fixedfloat` | Minter is Mixer | Minter has unusual FixedFloat volume. |
| `minter-simpleswap` | Minter is Mixer | Minter has unusual SimpleSwap volume. |
| `minter-fundflow-hacker` | Minter Funds Hackers | Minter fund flow linked to hackers. |
| `minter-fundflow-ofac` | Minter Funds Sanctioned | Minter fund flow involves sanctioned entities. |
| `minter-fundflow-drainer` | Minter Funds Drainers | Minter fund flow involves drainers. |
| `minter-fundflow-mixer` | Minter Funds Mixers | Minter fund flow involves mixers. |
### Associated Risk Tags (Owner)
| Tag | Name | Description |
| ------------------------ | ---------------------- | --------------------------------------------- |
| `owner-hacker` | Owner is Hacker | The owner has been compromised by hackers. |
| `owner-ofac` | Owner is Sanctioned | Owner involved with OFAC-sanctioned entities. |
| `owner-drainer` | Owner is Drainer | The owner is draining funds or assets. |
| `owner-mixer` | Owner is Mixer | Owner involved in mixing/tumbling schemes. |
| `owner-fundflow-hacker` | Owner Funds Hackers | Owner fund flow linked to hackers. |
| `owner-fundflow-ofac` | Owner Funds Sanctioned | Owner fund flow involves sanctioned entities. |
| `owner-fundflow-drainer` | Owner Funds Drainers | Owner fund flow involves drainers. |
| `owner-fundflow-mixer` | Owner Funds Mixers | Owner fund flow involves mixers. |
### Associated Risk Tags (Update Authority)
| Tag | Name | Description |
| ----------------------------------- | ------------------------ | -------------------------------------------------------- |
| `update-authority-hacker` | Updater is Hacker | Update authority compromised by hackers. |
| `update-authority-ofac` | Updater is Sanctioned | Update authority involved with sanctioned entities. |
| `update-authority-drainer` | Updater is Drainer | Update authority is draining funds. |
| `update-authority-mixer` | Updater is Mixer | Update authority involved in mixing schemes. |
| `update-authority-fundflow-hacker` | Updater Funds Hackers | Update authority fund flow linked to hackers. |
| `update-authority-fundflow-ofac` | Updater Funds Sanctioned | Update authority fund flow involves sanctioned entities. |
| `update-authority-fundflow-drainer` | Updater Funds Drainers | Update authority fund flow involves drainers. |
| `update-authority-fundflow-mixer` | Updater Funds Mixers | Update authority fund flow involves mixers. |
### Associated Risk Tags (Top Holders)
| Tag | Name | Description |
| --------------------------------- | --------------------------- | --------------------------------------------------- |
| `top-10-holders-hacker` | Top Holders are Hackers | Top holders may be hackers. |
| `top-10-holders-ofac` | Top Holders are Sanctioned | Top holders involved with sanctioned entities. |
| `top-10-holders-drainer` | Top Holders are Drainers | Top holders involved in draining funds. |
| `top-10-holders-fundflow-hacker` | Top Holders Fund Hackers | Top holders fund flow linked to hackers. |
| `top-10-holders-fundflow-ofac` | Top Holders Fund Sanctioned | Top holders fund flow involves sanctioned entities. |
| `top-10-holders-fundflow-drainer` | Top Holders Fund Drainers | Top holders fund flow involves drainers. |
| `top-10-holders-fundflow-mixer` | Top Holders Fund Mixers | Top holders fund flow involves mixers. |
***
## Address Risk Tags
Tags related to wallet address behavior and associations.
| Tag | Name | Description |
| --------------------------------------- | ------------------- | ------------------------------------------------------------------------- |
| `drainer` | Drainer | Address related to drainer activity that automates draining assets. |
| `hacker` | Hacker | Address associated with hacking or at risk of being a hacker. |
| `mixer` | Mixer | Coin mixer address. Interacting may result in your address being flagged. |
| `sanctioned` | Sanctioned | Sanctioned activity reported by world authorities. |
| `cybercrime` | Cybercrime | Address has committed cybercrimes reported by authorities. |
| `financial_crime` | Financial Crime | Connected with financial crime. Avoid DEX interaction. |
| `stealing_attack` | Theft | Involved in theft. Do not send anything to this address. |
| `money_laundering` | Money Laundering | Involved in money laundering and may be attached to criminal activity. |
| `phishing_activities` | Phishing | Involved in phishing activities. Proceed with extreme caution. |
| `blackmail_activities` | Blackmail | Potentially involved in illegal blackmail activity. |
| `darkweb_transactions` | Darkweb | Spotted interacting with darkweb actors. |
| `honeypot_related_address` | Honeypot | Honeypot address that traps unsuspecting wallets. |
| `malicious_mining_activities` | Malicious Miner | Miner that has performed malicious mining and AMM activity. |
| `number_of_malicious_contracts_created` | Malicious Contracts | Associated with malicious smart contracts. Avoid at all costs. |
| `fake_kyc` | KYC Fail | Fails to meet KYC standards (too new, too few transactions). |
| `blacklist_doubt` | Possible Blacklist | Reported numerous times as dangerous. Proceed with caution. |
***
## Contract Risk Tags
Tags related to smart contract vulnerabilities and security issues.
### Reentrancy Vulnerabilities
| Tag | Name | Description |
| --------------------------------- | ------------------------------- | -------------------------------------------------------------------------- |
| `reentrancy_with_eth_transfer` | Reentrancy With ETH Transfer | Allows reentrancy attacks capable of withdrawing more ETH than deposited. |
| `reentrancy_without_eth_transfer` | Reentrancy Without ETH Transfer | Vulnerable to reentrancy attacks on token transfers. |
| `reentrancy_same_effect` | Reentrancy | Vulnerable to reentrancy attacks. |
| `pess_readonly_reentrancy` | Readonly Reentrancy | Getter functions return values that could be manipulated during execution. |
### Price Manipulation
| Tag | Name | Description |
| --------------------------- | ------------------------------ | ------------------------------------------------------------------ |
| `price_manipulation_high` | High Price Manipulation Risk | Contract has logic with high potential for price manipulation. |
| `price_manipulation_medium` | Medium Price Manipulation Risk | Contract has logic with moderate potential for price manipulation. |
| `price_manipulation_low` | Low Price Manipulation Risk | Contract has logic with low potential for price manipulation. |
### Front Running
| Tag | Name | Description |
| ---------------------- | ------------------------- | ------------------------------------------------- |
| `front_running_high` | High Front Running Risk | Contract logic could be subject to front running. |
| `front_running_medium` | Medium Front Running Risk | Contract logic could be subject to front running. |
| `front_running_low` | Low Front Running Risk | Contract logic could be subject to front running. |
### Centralization Risks
| Tag | Name | Description |
| ------------------------- | -------------------------- | ------------------------------------- |
| `centralized_risk_high` | High Centralization Risk | Contract may have drainer-like logic. |
| `centralized_risk_medium` | Medium Centralization Risk | Contract may have drainer-like logic. |
| `centralized_risk_low` | Minor Centralization Risk | Contract may have drainer-like logic. |
### Minting Risks
| Tag | Name | Description |
| ----------- | --------------------------- | ------------------------------------------------------ |
| `mint_high` | High Arbitrary Minting Risk | Logic could be manipulated to arbitrarily mint tokens. |
| `mint_low` | Low Arbitrary Minting Risk | Logic could be manipulated to arbitrarily mint tokens. |
| `burn` | Arbitrary Burning Risk | Logic could be manipulated to arbitrarily burn tokens. |
### Integer Issues
| Tag | Name | Description |
| ------------------- | ----------------- | ------------------------------------------ |
| `integer_overflow` | Integer Overflow | Contract susceptible to integer overflow. |
| `integer_underflow` | Integer Underflow | Contract susceptible to integer underflow. |
### Unchecked Operations
| Tag | Name | Description |
| -------------------- | ------------------------ | ------------------------------------------- |
| `unchecked_lowlevel` | Unchecked Low Level Call | Return value of low level call not checked. |
| `unchecked_send` | Unchecked Send | Return value of send not checked. |
| `unchecked_transfer` | Unchecked Transfer | Return value of transfer not checked. |
### Self Destruct
| Tag | Name | Description |
| -------------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
| `selfdestruct` | Self Destruct | Contract is self destructible. All functions become unavailable and assets erased. Susceptible to rug-pulls. |
| `suicidal` | Self Destruct | Contract is self destructible. |
### Arbitrary Operations
| Tag | Name | Description |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------- |
| `arbitrary_send_erc20` | Arbitrary Send ERC20 | Approval allows attacker to take tokens directly to their wallet. |
| `arbitrary_send_erc20_permit` | Arbitrary Send ERC20 with Permit | TransferFrom allows attacker to transfer all approved tokens. |
| `arbitrary_send_eth` | Arbitrary Send ETH | Unprotected call sending ETH to arbitrary address. |
### Signature Issues
| Tag | Name | Description |
| ---------------- | ------------------------------ | ------------------------------------------------ |
| `SWC_117` | Signature Malleability | Signature could be reused in unauthorized ways. |
| `SWC_121` | Replay Attack Vulnerability | Attackers can reuse your signature. |
| `SWC_122` | Lack of Signature Verification | Missing proper signature verification. |
| `pess_ecrecover` | ECRecover Issue | Ecrecover returns 0 on error, must check result. |
### Storage & State Issues
| Tag | Name | Description |
| ----------------------- | ----------------------- | ---------------------------------------------------- |
| `uninitialized_state` | Uninitialized State | State variables are uninitialized. |
| `uninitialized_storage` | Uninitialized Storage | Storage variables are uninitialized. |
| `unprotected_upgrade` | Unprotected Upgrade | Contract can be self destructed and funds withdrawn. |
| `SWC_124` | Arbitrary Storage Write | Attacker can write to arbitrary storage locations. |
| `locked_ether` | Locked Ether | Contract takes payment but has no withdraw function. |
### Access Control
| Tag | Name | Description |
| -------------------------------- | ------------------------- | -------------------------------------------------------------- |
| `controlled_delegatecall` | Controlled Delegatecall | Attacker can delegate to malicious contract. |
| `delegatecall_loop` | Delegatecall Loop | Logic could be harmful on repeat. |
| `pess_unprotected_initialize` | Unprotected Initialize | Initialize could be hijacked by attacker. |
| `pess_unprotected_setter` | Unprotected Setter | Setter changes parameters without protection. |
| `pess_call_forward_to_protected` | Call Forward to Protected | Low level calls to custom address could bypass access control. |
### Other Contract Vulnerabilities
| Tag | Name | Description |
| ------------------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `weak_prng` | Weak PRNG | Randomness generation is weak and could be gamed by miners. |
| `rtlo` | Right To Left Override | Unicode characters used to manipulate contract logic. No legitimate use case. |
| `shadowing_state` | Shadowing State | Variable naming prevents setting certain variables. |
| `encode_packed_collision` | Encode Packed Collision | Possibility of collisions overwriting data. |
| `incorrect_shift` | Incorrect Shift | Incorrectly using bitshifting. |
| `k_value_error` | K Value Error | K value error in swap/mint/burn functions. |
| `missing_zero_check` | Missing Zero Check | No check for zero address, potentially bricking contract. |
| `pess_token_fallback` | Token Fallback | Fallback function indicates potential reentrancy. |
| `pess_double_entry_token_alert` | Double Entry Token | Token has two entry points that may cause misfunction. |
| `controlled_array_length` | Controlled Array Length | Array length can be resized, allowing access to critical information. |
| `msg_value_loop` | Msg.Value in Loop | Use of msg.value inside a loop. |
***
## Wallet History Tags
Tags related to wallet age and activity.
| Tag | Name | Description |
| ---------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------- |
| `insufficient_wallet_age` | Insufficient Age | Wallet is too new to pass KYW (Know Your Wallet) criteria. May indicate malicious creation. |
| `insufficient_wallet_balance` | Insufficient Balance | Balance is below KYW criteria. May indicate a new wallet. |
| `insufficient_wallet_transactions` | Insufficient Transactions | Too few transactions to pass KYW criteria. |
***
## Chain-Specific Tags
### Solana
| Tag | Name | Description |
| ----------------------- | --------------------- | -------------------------------------------------------- |
| `impersonator` | Impersonator | Someone is impersonating an entity related to the token. |
| `known-malicious-token` | Known Malicious Token | Token is recognized as malicious. |
| `mutable-metadata` | Mutable Metadata | Token metadata can be modified. |
### TON
| Tag | Name | Description |
| ------------------------------ | -------------------------- | ------------------------------------------------------ |
| `is_nonstandard_jetton` | Non-standard Jetton | Jetton does not follow standard implementation. |
| `is_nonstandard_jetton_wallet` | Non-standard Jetton Wallet | Jetton wallet does not follow standard implementation. |
***
## Report Tags
| Tag | Name | Description |
| -------------- | -------- | ------------------------------------------------------------ |
| `valid_report` | Reported | This address or contract has been reported by the community. |
# Stellar
Source: https://docs.webacy.com/essentials/stellar
Stellar blockchain support and risk analysis
## Overview
The Webacy API provides risk assessment for the Stellar blockchain ecosystem. Analyze Stellar addresses and tokens for security threats, malicious activity, and risk factors.
Stellar support is currently in beta. Contact us at [info@webacy.com](mailto:info@webacy.com) for feedback or questions.
## Supported Endpoints
### Address Risk Analysis
Analyze any Stellar address for security threats and risk factors.
```bash theme={null}
GET /addresses/{address}?chain=stellar
```
### Holder Analysis
Analyze token holder distribution and detect suspicious activity.
```bash theme={null}
GET /holder-analysis/{identifier}?chain=stellar
```
## Address Formats
Stellar uses different address formats depending on the entity type:
| Type | Format | Example |
| ------- | -------------------- | --------------------------------------------------------------- |
| Account | G... (56 characters) | `GA223OFHVKVAH2NBXP4AURJRVJTSOVHGBMKJNL6GRJWNN4SARVGSITYG` |
| Token | CODE:ISSUER | `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` |
For token analysis, use the `CODE:ISSUER` format. The code is the asset code (e.g., `USDC`) and the issuer is the account that created the token.
## Test Addresses
Use these addresses to test the API:
```bash theme={null}
# Known malicious address
curl -X GET "https://api.webacy.com/addresses/GA223OFHVKVAH2NBXP4AURJRVJTSOVHGBMKJNL6GRJWNN4SARVGSITYG?chain=stellar" \
-H "x-api-key: YOUR_API_KEY"
# Token holder analysis
curl -X GET "https://api.webacy.com/holder-analysis/WillowDollar:GAFKQXZYW32INZMX3N4CPB73P3ZYTPHYEZF2HYBHVL6LFPSLLOWPTJVS?chain=stellar" \
-H "x-api-key: YOUR_API_KEY"
```
## Stellar-Specific Risk Tags
These risk tags are unique to the Stellar ecosystem:
| Tag | Severity | Description |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `clawback` | Medium | A clawback operation has been detected on this account or token. |
| `multiple_clawback` | High | Multiple clawback operations detected, indicating potential pattern of fund recovery or manipulation. |
| `malicious_account` | High | Account flagged as malicious by StellarExpert or community reports. |
| `unsafe_account` | Medium | Account flagged as potentially unsafe by StellarExpert. |
| `malicious_issuer` | High | Token issuer has been flagged as malicious. |
| `unsafe_issuer` | Medium | Token issuer has been flagged as potentially unsafe. |
## Additional Risk Tags
Standard risk tags also apply to Stellar addresses:
* `wash_trading` - Suspicious trading patterns detected
* `sanctioned` - Address appears on sanction lists
* `insufficient_wallet_age` - Account is very new
* `insufficient_wallet_balance` - Low account balance
* `insufficient_wallet_transactions` - Limited transaction history
* Holder concentration tags (top holders owning significant percentages)
## Example Response
```json theme={null}
{
"count": 2,
"medium": 1,
"high": 1,
"overallRisk": 65.5,
"issues": [
{
"tag": "malicious_account",
"severity": "high",
"description": "Account flagged as malicious by StellarExpert"
},
{
"tag": "clawback",
"severity": "medium",
"description": "Clawback operation detected on this account"
}
]
}
```
## Best Practices
1. **Always use the correct format** - Use `CODE:ISSUER` format for tokens, not just the asset code
2. **Check holder distribution** - Use the holder analysis endpoint to understand token concentration
3. **Monitor for clawback** - Clawback-enabled tokens can have funds recalled by the issuer
# Supported Blockchains
Source: https://docs.webacy.com/essentials/supported-blockchains
List of blockchain networks supported by Webacy API
## Overview
The Webacy API supports multiple blockchain networks. Use the chain identifier in your API requests to specify which network to query.
Not all endpoints support all chains. Check individual endpoint documentation for specific chain coverage.
## Supported Networks
| Blockchain | Identifier | Status |
| ---------- | ---------- | ------------ |
| Ethereum | `eth` | Full Support |
| Polygon | `pol` | Full Support |
| Optimism | `opt` | Full Support |
| Arbitrum | `arb` | Full Support |
| Base | `base` | Full Support |
| BSC | `bsc` | Full Support |
| Solana | `sol` | Full Support |
| TON | `ton` | Full Support |
| Sei | `sei` | Full Support |
| Sui | `sui` | Full Support |
| Stellar | `stellar` | Full Support |
| Hedera | `hedera` | Full Support |
| Bitcoin | `btc` | Limited |
## Chain Coverage by Endpoint
### Threat Risks
`/addresses/{address}`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`, `sol`, `ton`, `sei`, `sui`, `stellar`, `hedera`, `btc`
### Sanction Checks
`/addresses/sanctioned/{walletAddress}`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`, `sol`, `ton`, `sei`, `sui`, `stellar`, `btc`
For Hedera, sanction checks are included in the `/addresses/{address}` response rather than a separate endpoint.
### Contract Risk
`/contracts/{contractAddress}`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`
### Approval Risks
`/addresses/{address}/approvals`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`
### Transaction Scanning
`/scan/{fromAddress}/transactions`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`
### Transaction Risk Analysis
`/transactions/{txHash}`
`eth`, `base`, `bsc`, `pol`, `opt`, `sol`, `arb`, `stellar`, `hedera`
### Quick Profile
`/addresses/{address}/quick-profile`
`eth`, `base`, `bsc`, `pol`, `opt`, `sol`, `arb`
### Holder Analysis
`/holder-analysis/{address}`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`, `sol`, `stellar`, `sui`, `hedera`
### Address Poisoning
`/addresses/{address}/poisoning`
`eth`, `pol`, `opt`, `arb`, `base`, `bsc`
### Trading Lite
`/trading/...`
`sol`
## Default Chain
When no chain is specified, the API defaults to **Ethereum** (`eth`).
## Requesting Additional Chains
Need support for a blockchain not listed? Contact us at [info@webacy.com](mailto:info@webacy.com).
# Webhooks (Beta)
Source: https://docs.webacy.com/essentials/webhooks
Real-time push notifications for risk analysis events
## Overview
Webacy Webhooks provide a push-model delivery of risk analysis data. Instead of polling our API, receive real-time notifications when events occur.
Webhooks are currently in **beta** with limited access. Contact us at [info@webacy.com](mailto:info@webacy.com) to request early access.
## Why Use Webhooks?
| Pull Model (API) | Push Model (Webhooks) |
| -------------------------- | ----------------------------- |
| You poll for updates | We notify you instantly |
| Higher latency | Sub-second delivery |
| More API calls | Efficient, event-driven |
| Good for on-demand queries | Ideal for monitoring & alerts |
## Event Types
### TOKEN\_LAUNCH\_ANALYSIS
Triggered immediately when a new token is created. Receive risk analysis within milliseconds of minting.
**Use Cases:**
* Early token screening for trading bots
* New token alerts for monitoring dashboards
* Automated listing decisions for DEX aggregators
```json theme={null}
{
"event": "TOKEN_LAUNCH_ANALYSIS",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"tokenAddress": "So11111111111111111111111111111111111111112",
"chain": "sol",
"launchTimestamp": "2024-01-15T10:29:58.000Z",
"riskScore": 45.5,
"issues": [
{
"tag": "mintable",
"severity": "medium",
"description": "Token supply can still be increased"
},
{
"tag": "minted-less-than-10-minutes",
"severity": "low",
"description": "Token was minted within the last 10 minutes"
}
],
"metadata": {
"name": "Example Token",
"symbol": "EXT",
"decimals": 9,
"totalSupply": "1000000000000000"
}
}
}
```
***
### TOKEN\_TRANSACTION
Fires instantly for each buy/sell transaction on monitored tokens.
**Use Cases:**
* Real-time trading alerts
* Instant bundler/sniper activity detection
* Live portfolio tracking
* Automated trading signals
```json theme={null}
{
"event": "TOKEN_TRANSACTION",
"timestamp": "2024-01-15T10:35:22.000Z",
"data": {
"tokenAddress": "So11111111111111111111111111111111111111112",
"chain": "sol",
"transactionSignature": "5K8vJkLm9nPqRsTuVwXyZ123AbCdEfGhIjKlMnOpQr",
"type": "BUY",
"trader": "Abc123DefGhi456JklMno789PqrStu012VwxYz345",
"amount": "1500000000",
"priceUsd": "0.00125",
"totalValueUsd": "1875.00",
"traderAnalysis": {
"isSniper": true,
"isBundler": false,
"sniperConfidence": 85,
"previousRugpulls": 0
},
"poolAddress": "PoolABC123DefGhi456JklMno789PqrStu012Vwx"
}
}
```
***
### HOLDER\_ANALYSIS\_UPDATE
Delivers updates at 15 scheduled checkpoints after token launch, tracking how the holder distribution evolves.
**Checkpoints:** Analysis is delivered at key intervals post-launch to track:
* How bundler/sniper activity evolves
* Holder concentration changes
* Whale accumulation patterns
* Distribution normalization
**Use Cases:**
* Track manipulation patterns over time
* Monitor holder distribution health
* Identify late-stage accumulation
* Research token lifecycle patterns
```json theme={null}
{
"event": "HOLDER_ANALYSIS_UPDATE",
"timestamp": "2024-01-15T11:00:00.000Z",
"data": {
"tokenAddress": "So11111111111111111111111111111111111111112",
"chain": "sol",
"checkpoint": 3,
"checkpointLabel": "30_minutes",
"timeSinceLaunch": 1800,
"analysis": {
"totalHolders": 156,
"top10HoldersPercentage": 68.5,
"sniperPercentageHolding": 42.3,
"bundlerPercentageHolding": 15.8,
"devHoldingPercentage": 5.2,
"uniqueWallets": 142
},
"changes": {
"holdersDelta": 48,
"top10Delta": -12.5,
"sniperDelta": -8.2
},
"previousCheckpoint": {
"checkpoint": 2,
"checkpointLabel": "15_minutes"
}
}
}
```
## Current Limitations
As a beta feature, webhooks have the following limitations:
| Limitation | Details |
| --------------- | ------------------------------------------- |
| **Access** | Limited beta access - requires approval |
| **Chains** | Solana only (additional chains coming soon) |
| **Rate Limits** | Custom limits based on your plan |
## Getting Early Access
To request webhook access:
1. **Email us** at [info@webacy.com](mailto:info@webacy.com)
2. Include your use case and expected volume
3. Our team will reach out to discuss setup
We'll provide:
* Webhook endpoint configuration
* Authentication details
* Detailed payload documentation
* Integration support
## Coming Soon
* Support for additional blockchains (EVM chains, TON, etc.)
* Custom event filtering
* Webhook management dashboard
* Retry and delivery guarantees
Interested in helping shape the webhooks feature? We welcome feedback from beta users. Contact us to share your requirements.
# Address Poisoning
Source: https://docs.webacy.com/glossary/address-poisoning
Understanding address poisoning attacks and prevention
## Overview
**Address poisoning** is a social engineering attack where attackers send small transactions from addresses that look similar to ones you've previously interacted with. The goal is to trick you into copying the wrong address when making future transfers.
Address poisoning has caused millions in losses. Always verify the full address, not just the first and last few characters.
## How It Works
1. **Monitoring**: Attacker watches your transaction history
2. **Address Generation**: Creates address with similar start/end characters
3. **Poisoning**: Sends tiny transaction (dust) to your wallet
4. **Deception**: Fake address appears in your transaction history
5. **Theft**: Victim copies poisoned address for next transfer
## Example Attack
Your regular recipient:
```text theme={null}
0x1234...abcd
```
Poisoned address (looks similar):
```text theme={null}
0x1234...abce
```
The attacker generates an address matching the first 4 and last 4 characters, hoping you'll copy from history without verifying the full address.
## Detection Indicators
| Tag | Severity | Description |
| ------------------- | -------- | ------------------------------------- |
| `address_poisoning` | High | Address involved in poisoning attacks |
## Why It's Effective
* **Transaction history UI**: Most wallets show truncated addresses
* **Copy habits**: Users often copy from recent transactions
* **Similar appearance**: Human eyes struggle with hex comparison
* **Low cost**: Generating similar addresses is computationally cheap
## Vulnerable Scenarios
### High Risk
* Copying addresses from transaction history
* Using auto-complete in wallet apps
* Sending large transfers without verification
### Lower Risk
* Using saved address book entries
* Scanning QR codes directly
* Verifying full addresses character by character
## API Example
```bash theme={null}
# Check if an address has been involved in poisoning
curl -X GET "https://api.webacy.com/addresses/0x123.../poisoning?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response example:
```json theme={null}
{
"poisoning_detected": true,
"status": "success",
"summary": {
"total_suspicious": 1,
"high_risk_count": 1
},
"suspicious_transactions": [
{
"from": "0x1234567890abcdef1234567890abcdef12345678",
"to": "0x2e5df068f6cF3A1A3e0A70951c685021CB2954C0",
"tx_hash": "0x79e7b0a45a73b86fe51882d2553355e15bda7bebb6c3e222c09d8fd2f43aa076",
"similar_to": "0x1234567890abcdef1234567890abcdef12345679",
"similarity": 0.95,
"levenshtein": 2,
"suspicion_score": 0.85,
"token_name": "USDT",
"value": "0"
}
]
}
```
## Protection Strategies
1. **Verify full addresses** - Check every character, not just start/end
2. **Use address books** - Save verified addresses in your wallet
3. **Double-check large transfers** - Extra verification for significant amounts
4. **Ignore dust transactions** - Don't interact with unexpected small deposits
5. **Use QR codes** - When available, scan rather than copy/paste
6. **Enable address validation** - Some wallets can warn about similar addresses
## Wallet Best Practices
```javascript theme={null}
// Never trust truncated addresses
const isSameAddress = (addr1, addr2) => {
// Always compare full addresses, case-insensitive
return addr1.toLowerCase() === addr2.toLowerCase();
};
// Bad: Only checking first/last characters
const badCheck = addr.slice(0,6) === saved.slice(0,6); // DON'T DO THIS
```
# Definitions
Source: https://docs.webacy.com/glossary/definitions
### Address
A **blockchain address** is a unique identifier that represents a destination for sending or receiving digital assets on a blockchain network.
***
### Address Clustering
**Address clustering** is a blockchain analysis technique used to group multiple wallet addresses that are likely controlled by the same user or entity based on transaction behavior.
***
### Algorithmic Stablecoin
An **algorithmic stablecoin** maintains its price stability through automated supply adjustments rather than backing by reserves of fiat currency or other assets.
***
### AML (Anti-Money Laundering)
**Anti-Money Laundering (AML)** refers to regulatory frameworks and procedures designed to prevent the use of financial systems for illicit activities such as money laundering or terrorist financing.
***
### Behavioral Risk Signals
**Behavioral risk signals** are patterns in blockchain activity that may indicate suspicious or high-risk behavior. These signals can include unusual transaction patterns, rapid fund movements across multiple addresses, interactions with known illicit services, or coordinated activity across wallets.
***
### Block
A **block** is a group of validated transactions that is added to the blockchain ledger and cryptographically linked to the previous block.
***
### Blockchain
A **blockchain** is a distributed digital ledger that records transactions across a network of computers, ensuring transparency, immutability, and shared verification.
***
### Blockchain Explorer
A **blockchain explorer** is a tool that allows users to view blockchain data including transactions, wallet balances, blocks, and network activity.
***
### Blockchain Forensics
**Blockchain forensics** is the practice of analyzing blockchain transaction data to trace funds, identify suspicious activity, and investigate potential financial crimes.
***
### Bridge
A **blockchain bridge** enables digital assets and data to move between different blockchain networks.
***
### Centralized Exchange (CEX)
A **centralized exchange** is a platform that facilitates the trading of digital assets and is operated by a centralized entity that manages custody, order books, and transactions.
***
### Consensus Mechanism
A **consensus mechanism** is the method by which blockchain networks validate transactions and agree on the current state of the ledger.
***
### Cross-Chain Risk
**Cross-chain risk** refers to potential threats or vulnerabilities that arise when digital assets move between different blockchain networks. These risks may include bridge exploits, liquidity fragmentation, asset wrapping risks, and difficulty tracking the origin or destination of funds across multiple chains.
***
### Custodial Wallet
A **custodial wallet** is a wallet where a third party, such as an exchange or financial institution, controls the private keys and manages assets on behalf of users.
***
### DeFi (Decentralized Finance)
**Decentralized finance (DeFi)** refers to financial services built on blockchain networks that operate without centralized intermediaries such as banks or brokers.
***
### Digital Asset
A **digital asset** is any asset issued and stored digitally on a blockchain or distributed ledger, including cryptocurrencies, tokens, and tokenized financial instruments.
***
### Gas Fee
A **gas fee** is the cost paid to network validators or miners to process and confirm a transaction on a blockchain.
***
### Governance Token
A **governance token** gives holders the ability to participate in decision-making for a protocol, such as voting on upgrades or policy changes.
***
### Honeypot
A **honeypot** is a malicious smart contract that allows users to deposit funds but prevents them from withdrawing them.
***
### KYC (Know Your Customer)
**Know Your Customer (KYC)** refers to the process financial institutions use to verify the identity of their customers as part of regulatory compliance.
***
### Layer 1 (L1)
A **Layer 1 blockchain** is the base network that processes and validates transactions directly, such as Bitcoin or Ethereum.
***
### Layer 2 (L2)
A **Layer 2 solution** is a scaling technology built on top of a Layer 1 blockchain to increase transaction throughput and reduce fees.
***
### Liquidity
**Liquidity** refers to how easily an asset can be bought or sold in a market without significantly affecting its price.
***
### Liquidity Pool
A **liquidity pool** is a pool of digital assets locked in a smart contract to facilitate decentralized trading, lending, or other financial activities.
***
### Liquidity Risk Monitoring
**Liquidity risk monitoring** is the ongoing analysis of the availability and stability of liquidity for a digital asset across trading venues, pools, and markets. Monitoring liquidity helps identify conditions such as sudden liquidity withdrawals, concentration risks, or abnormal trading activity that may impact price stability.
***
### MEV (Maximal Extractable Value)
**Maximal Extractable Value (MEV)** refers to profits that block producers can generate by reordering, inserting, or censoring transactions before they are finalized on the blockchain.
***
### Miner
A **miner** is a participant in a proof-of-work blockchain who uses computational power to validate transactions and create new blocks.
***
### Mixer (Tumbler)
A **crypto mixer** is a service that attempts to obscure the origin and destination of digital assets by combining transactions from multiple users.
***
### Multi-Signature Wallet (Multisig)
A **multisignature wallet** requires multiple private keys to authorize a transaction, improving security and governance over funds.
***
### Node
A **node** is a computer connected to a blockchain network that maintains a copy of the ledger and helps validate and relay transactions.
***
### Off-Chain
**Off-chain** refers to activities or transactions that occur outside the blockchain but may interact with it.
***
### On-Chain
**On-chain** refers to transactions and data that are recorded directly on the blockchain ledger.
***
### Oracle
A **blockchain oracle** provides external data to smart contracts so they can interact with information outside the blockchain.
***
### Private Key
A **private key** is a secret cryptographic key that grants control over a blockchain address and the assets associated with it.
***
### Proof of Reserves
**Proof of Reserves (PoR)** is a verification method used by crypto platforms to demonstrate that customer assets are backed by sufficient reserves.
***
### Proof of Stake (PoS)
**Proof of Stake** is a consensus mechanism where validators secure the network by locking tokens as collateral and participating in transaction validation.
***
### Proof of Work (PoW)
**Proof of Work** is a consensus mechanism where miners solve complex cryptographic puzzles to validate transactions and secure the network.
***
### Public Key
A **public key** is a cryptographic key derived from a private key that can be shared publicly to receive digital assets.
***
### Rug Pull
A **rug pull** occurs when developers abandon a project and withdraw liquidity or funds, leaving investors with worthless tokens.
***
### Risk Intelligence
**Risk intelligence** refers to the collection, analysis, and interpretation of blockchain data to identify potential security, financial, or compliance risks associated with digital assets, transactions, smart contracts, or wallet activity.
***
### Self-Custody
**Self-custody** refers to managing one’s own private keys and digital assets without relying on a third-party custodian.
***
### Smart Contract
A **smart contract** is software deployed on a blockchain that automatically executes predefined actions when certain conditions are met.
***
### Stablecoin
A **stablecoin** is a digital asset designed to maintain a stable value, typically by being pegged to a fiat currency such as the US dollar.
***
### Stablecoin Depeg Risk
**Stablecoin depeg risk** refers to the possibility that a stablecoin loses its intended price stability relative to its reference asset, typically a fiat currency such as the US dollar. Depegs may occur due to liquidity shocks, reserve concerns, market stress, or structural vulnerabilities in the asset’s design.
***
### Token
A **token** is a digital asset issued on a blockchain that can represent currency, utility, ownership rights, or access to services.
***
### Tokenization
**Tokenization** is the process of representing real-world or digital assets as tokens on a blockchain.
***
### Token Risk Analysis
**Token risk analysis** is the evaluation of a digital asset’s technical, financial, and behavioral characteristics to identify potential risks. This may include analysis of smart contract code, liquidity conditions, holder concentration, governance controls, and transaction activity.
***
### Total Value Locked (TVL)
**Total Value Locked** represents the total value of assets deposited in a decentralized finance protocol.
***
### Transaction
A **transaction** is a transfer of digital assets or data recorded on a blockchain.
***
### Transaction Simulation
**Transaction simulation** is the process of analyzing a blockchain transaction before it is executed to predict its outcome. Simulation can reveal potential risks such as malicious contract behavior, unexpected token transfers, excessive fees, or failed transactions.
***
### Validator
A **validator** is a participant in a proof-of-stake blockchain responsible for confirming transactions and maintaining the network.
***
### Wallet
A **wallet** is software or hardware used to store cryptographic keys that allow users to manage digital assets on a blockchain.
***
### Wallet Screening
**Wallet screening** is the process of evaluating a blockchain address to determine whether it may be associated with illicit activity, sanctioned entities, fraud, or other high-risk behavior based on transaction history and known risk indicators.
# Digital Signature Module
Source: https://docs.webacy.com/glossary/digital-signature-module
Understanding digital signature security in smart contracts
## Overview
The Digital Signature Module analyzes how contracts handle cryptographic signatures, detecting vulnerabilities that could allow signature replay attacks, forgery, or unauthorized access.
## What Are Digital Signatures?
Digital signatures in blockchain provide:
* **Authentication**: Proof that a message came from a specific address
* **Integrity**: Assurance the message hasn't been altered
* **Non-repudiation**: Signer cannot deny signing
```solidity theme={null}
// Basic signature verification
function verify(
bytes32 messageHash,
bytes memory signature,
address expectedSigner
) public pure returns (bool) {
return recoverSigner(messageHash, signature) == expectedSigner;
}
```
## Common Vulnerabilities
### Signature Replay Attack
Using the same signature multiple times.
```solidity theme={null}
// VULNERABLE: No replay protection
function claim(uint256 amount, bytes memory signature) public {
bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount));
require(verify(hash, signature, signer), "Invalid signature");
_mint(msg.sender, amount); // Can be called multiple times!
}
```
**Attack:** User claims rewards repeatedly with the same signature.
***
### Cross-Chain Replay
Signature valid on multiple chains.
```solidity theme={null}
// VULNERABLE: No chain ID in signature
function execute(address to, uint256 value, bytes memory signature) public {
bytes32 hash = keccak256(abi.encodePacked(to, value));
require(verify(hash, signature, owner), "Invalid signature");
payable(to).transfer(value);
}
```
**Attack:** Signature from mainnet replayed on testnet or L2.
***
### Missing Nonce
No mechanism to invalidate old signatures.
```solidity theme={null}
// VULNERABLE: Signatures never expire
function withdraw(uint256 amount, bytes memory signature) public {
bytes32 hash = keccak256(abi.encodePacked(msg.sender, amount));
require(verify(hash, signature, admin), "Invalid");
// No nonce - signature is valid forever
_transfer(address(this), msg.sender, amount);
}
```
***
### Signature Malleability
ECDSA signatures can be modified while remaining valid.
```solidity theme={null}
// VULNERABLE: No malleability check
function verifySignature(bytes32 hash, uint8 v, bytes32 r, bytes32 s)
public pure returns (address)
{
return ecrecover(hash, v, r, s); // Malleable!
}
```
## Safe Patterns
### Nonce-Based Replay Protection
```solidity theme={null}
// SAFE: Nonce prevents replay
mapping(address => uint256) public nonces;
function claim(uint256 amount, uint256 nonce, bytes memory signature) public {
require(nonce == nonces[msg.sender], "Invalid nonce");
bytes32 hash = keccak256(abi.encodePacked(
msg.sender,
amount,
nonce,
block.chainid, // Chain-specific
address(this) // Contract-specific
));
require(verify(hash, signature, signer), "Invalid signature");
nonces[msg.sender]++; // Increment nonce
_mint(msg.sender, amount);
}
```
### EIP-712 Typed Data
```solidity theme={null}
// SAFE: Structured, typed signing
bytes32 public constant CLAIM_TYPEHASH =
keccak256("Claim(address recipient,uint256 amount,uint256 nonce)");
function claim(uint256 amount, uint256 nonce, bytes memory signature) public {
bytes32 structHash = keccak256(abi.encode(
CLAIM_TYPEHASH,
msg.sender,
amount,
nonce
));
bytes32 hash = _hashTypedDataV4(structHash); // Includes domain separator
address signer = ECDSA.recover(hash, signature);
require(signer == authorizedSigner, "Invalid signature");
require(nonce == nonces[msg.sender]++, "Invalid nonce");
_mint(msg.sender, amount);
}
```
### OpenZeppelin ECDSA
```solidity theme={null}
// SAFE: Using audited library
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
using ECDSA for bytes32;
function verify(bytes32 hash, bytes memory signature) public view returns (bool) {
// Handles malleability, returns address(0) on failure
return hash.toEthSignedMessageHash().recover(signature) == trustedSigner;
}
```
## Detection Tags
| Tag | Severity | Description |
| ------------------------ | -------- | ----------------------------------- |
| `signature_replay` | High | No replay protection detected |
| `missing_chainid` | Medium | Cross-chain replay possible |
| `missing_nonce` | High | Signatures never invalidated |
| `signature_malleability` | Medium | Raw ecrecover without checks |
| `weak_signature_scheme` | Medium | Non-standard signature verification |
## API Response Example
```json theme={null}
{
"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)"
}
]
}
```
## Best Practices
* [ ] 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
# Drainers
Source: https://docs.webacy.com/glossary/drainers
Understanding wallet draining attacks and protection
## Overview
A **drainer** is a malicious smart contract or script designed to automatically steal assets from connected wallets. Drainers are commonly deployed through phishing sites that trick users into signing malicious transactions.
Drainer attacks have caused hundreds of millions in losses. Never sign transactions on unfamiliar websites or approve unlimited token allowances.
## How Drainers Work
1. **Phishing Site**: Victim visits a fake website mimicking a legitimate project
2. **Wallet Connection**: Site requests wallet connection (appears normal)
3. **Malicious Approval**: User signs a transaction granting unlimited token approvals
4. **Asset Theft**: Drainer contract transfers all approved assets to attacker
5. **Speed**: Entire process can happen in seconds
## Types of Drainer Attacks
### Approval-Based Drainers
* Request ERC-20 token approvals
* Can drain all approved tokens at any time
* Most common type
### NFT Drainers
* Target NFT collections
* Often use `setApprovalForAll` function
* Can steal entire collections in one transaction
### Permit-Based Drainers
* Use EIP-2612 permit signatures
* No on-chain approval transaction required
* Harder to detect before execution
### Native Token Drainers
* Trick users into signing ETH transfers
* Often disguised as minting or claiming functions
## Detection Indicators
| Tag | Severity | Description |
| ------------------------- | -------- | ---------------------------------------------- |
| `drainer` | High | Address associated with known drainer activity |
| `minter-drainer` | High | Token minter involved in drainer operations |
| `owner-drainer` | High | Token owner is a known drainer |
| `minter-fundflow-drainer` | High | Minter fund flow linked to drainers |
| `owner-fundflow-drainer` | High | Owner fund flow linked to drainers |
## Common Drainer Tactics
* **Fake airdrops**: "Claim your free tokens" phishing
* **Fake mints**: Impersonating popular NFT drops
* **Compromised Discord/Twitter**: Links posted from hacked accounts
* **SEO poisoning**: Fake sites ranking for popular project searches
* **Typosquatting**: Domains similar to legitimate projects
## API Example
```bash theme={null}
curl -X GET "https://api.webacy.com/addresses/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response indicating drainer activity:
```json theme={null}
{
"overallRisk": 95.0,
"issues": [
{
"tag": "drainer",
"severity": "high",
"description": "Address related to drainer activity that automates draining assets"
}
]
}
```
## Protection Strategies
1. **Verify URLs** - Always check you're on the official website
2. **Review approvals** - Use our [Approval Risks](/api-reference/riskdd#wallet-risks) endpoint
3. **Limit approvals** - Only approve exact amounts needed
4. **Revoke old approvals** - Regularly audit and revoke unused approvals
5. **Use hardware wallets** - Provides extra signing verification step
6. **Check before signing** - Read transaction details carefully
# Fake Tokens
Source: https://docs.webacy.com/glossary/fake-tokens
Understanding impersonator and counterfeit token scams
## Overview
**Fake tokens** are malicious tokens designed to impersonate legitimate projects. Scammers create tokens with similar names, symbols, or branding to trick users into buying worthless counterfeits.
Always verify the exact contract address of a token before trading. Similar names and symbols are easy to copy.
## How Fake Tokens Work
1. **Target Selection**: Scammer identifies a popular or trending token
2. **Impersonation**: Creates a new token with identical or similar name/symbol
3. **Distribution**: Fake token appears in wallets or DEX searches
4. **Deception**: Users mistake it for the real token and buy
5. **Exit**: Scammer sells or rugs, leaving victims with worthless tokens
## Types of Fake Tokens
### Name Squatting
* Exact or near-exact name copying
* Same symbol as legitimate token
* Different contract address (the key difference)
### Airdrop Scams
* Unsolicited tokens appear in your wallet
* Designed to lure you to malicious websites
* Often have enticing names or values
### Logo/Branding Copies
* Stolen logos and imagery
* Copied website designs
* Fake social media accounts
### Pre-Launch Fakes
* Created before official token launches
* Exploit hype around upcoming projects
* Users think they're getting early access
## Detection Indicators
| Tag | Severity | Description |
| --------------------- | -------- | ----------------------------------------- |
| `fake_token` | Critical | Token identified as impersonating another |
| `airdrop_scam` | High | Unsolicited token likely part of scam |
| `phishing_token` | Critical | Token designed to steal funds |
| `unverified_contract` | Medium | Contract source code not verified |
## API Example
Never share real API keys in screenshots, logs, or client-side code.
```bash theme={null}
curl -X GET "https://api.webacy.com/tokens/{TOKEN_ADDRESS}?chain=eth" \
-H "x-api-key: {API_KEY}"
```
Response indicating fake token:
```json theme={null}
{
"overallRisk": 99.0,
"issues": [
{
"tag": "fake_token",
"severity": "critical",
"description": "Token impersonates a legitimate project"
},
{
"tag": "phishing_token",
"severity": "critical",
"description": "Token designed to lure users to malicious site"
}
]
}
```
## Red Flags
* **Different contract address** - Always verify against official sources
* **No liquidity or minimal liquidity** - Real tokens have established pools
* **No transaction history** - Legitimate tokens have trading activity
* **Appeared in wallet unexpectedly** - You didn't buy or claim it
* **Links to suspicious websites** - Different from official project URLs
* **No social presence** - Not mentioned by official project accounts
## Verification Steps
1. **Check official sources**
* Project's official website
* Verified social media accounts
* CoinGecko/CoinMarketCap listings
2. **Verify contract address**
* Compare exact address character by character
* Use official links, not search results
3. **Check on block explorer**
* Verify contract is verified
* Check creation date and transaction history
* Look for legitimate trading activity
## Protection Strategies
1. **Bookmark official sites** - Don't use search engines to find DEXes
2. **Verify contract addresses** - Always check the exact address
3. **Ignore airdrops** - Don't interact with unsolicited tokens
4. **Use official links** - Get addresses from verified sources only
5. **Check token age** - New tokens impersonating old projects are suspicious
6. **Verify on multiple sources** - Cross-reference contract addresses
## Handling Fake Airdrops
Never interact with suspicious airdropped tokens. Attempting to sell them may trigger wallet draining transactions.
If you receive unexpected tokens:
* **Don't try to sell them** - This can trigger malicious contracts
* **Don't visit linked websites** - These are often phishing sites
* **Hide the token** - Most wallets let you hide unwanted tokens
* **Report if possible** - Help protect others from the same scam
## Related Concepts
* [Phishing](./phishing) - Deceptive attacks to steal credentials
* [Drainers](./drainers) - Wallet-draining attacks
* [Address Poisoning](./address-poisoning) - Similar address scams
# Hidden Balance Update
Source: https://docs.webacy.com/glossary/hidden-balance-update
Detection of covert balance manipulation vulnerabilities
## Overview
Hidden Balance Update vulnerabilities allow malicious contracts to modify token balances without proper authorization or transparency, enabling theft and manipulation.
Balance manipulation attacks are particularly dangerous because they can be difficult to detect - transactions appear normal while balances are secretly altered.
## Types of Hidden Balance Updates
### Direct Balance Manipulation
Modifying the balance mapping directly without proper mint/burn/transfer operations.
```solidity theme={null}
// DANGEROUS: Direct balance manipulation
function adjustBalance(address account, uint256 amount) internal {
_balances[account] = amount; // No events, no checks
}
```
**Risk:** Balances can be changed arbitrarily without any record.
***
### Conditional Balance Modification
Balance changes triggered by hidden conditions.
```solidity theme={null}
// DANGEROUS: Hidden conditional balance update
function transfer(address to, uint256 amount) public returns (bool) {
if (block.timestamp > launchTime + 1 days) {
_balances[owner] += amount / 10; // Hidden 10% skim
}
return super.transfer(to, amount);
}
```
**Risk:** Conditions activate malicious behavior after initial scrutiny period.
***
### Rebasing Without Events
Modifying balances through rebasing mechanics without proper events.
```solidity theme={null}
// DANGEROUS: Silent rebase
function _rebase(uint256 factor) internal {
for (uint i = 0; i < holders.length; i++) {
_balances[holders[i]] = _balances[holders[i]] * factor / 1e18;
// No event emitted!
}
}
```
**Risk:** User balances change without any on-chain record.
***
### Balance Override in View Functions
Returning incorrect balances in view functions.
```solidity theme={null}
// DANGEROUS: Fake balance display
function balanceOf(address account) public view override returns (uint256) {
if (account == owner) {
return _balances[account] + _hiddenReserve; // Inflated balance
}
return _balances[account];
}
```
**Risk:** Displayed balances don't match actual holdings.
## Safe Patterns
### Transparent Balance Updates
```solidity theme={null}
// SAFE: All balance changes through proper functions with events
function _transfer(address from, address to, uint256 amount) internal {
require(from != address(0), "Transfer from zero");
require(to != address(0), "Transfer to zero");
require(_balances[from] >= amount, "Insufficient balance");
_balances[from] -= amount;
_balances[to] += amount;
emit Transfer(from, to, amount); // Always emit events
}
```
### Transparent Rebasing
```solidity theme={null}
// SAFE: Rebase with events
function rebase(uint256 factor) public onlyOwner {
uint256 oldSupply = _totalSupply;
_totalSupply = _totalSupply * factor / 1e18;
_rebaseIndex = _rebaseIndex * factor / 1e18;
emit Rebase(oldSupply, _totalSupply, factor); // Transparent
}
```
## Detection Tags
| Tag | Severity | Description |
| ------------------------- | -------- | ------------------------------------------ |
| `hidden_balance_update` | High | Direct balance manipulation detected |
| `conditional_balance_mod` | High | Balance changes on hidden conditions |
| `silent_rebase` | Medium | Rebase without event emission |
| `balance_view_mismatch` | Medium | View function returns inconsistent balance |
## API Response Example
```json theme={null}
{
"issues": [
{
"tag": "hidden_balance_update",
"severity": "high",
"description": "Direct balance mapping modification without events",
"location": "adjustBalance(address,uint256)"
}
]
}
```
## Red Flags
* [ ] Direct writes to `_balances` mapping outside standard functions
* [ ] Missing `Transfer` events on balance changes
* [ ] Conditional logic that modifies balances
* [ ] `balanceOf` returning different values than stored
* [ ] Time-delayed balance modification logic
# Hidden Mint
Source: https://docs.webacy.com/glossary/hidden-mint
Detection of malicious token minting vulnerabilities
## Overview
Hidden Mint identifies suspicious and malicious token minting activities where additional token supply can be altered in harmful ways.
Hidden mint vulnerabilities can completely devastate token value. In 2021, Levyathan.finance lost approximately \$1.5 million when an attacker exploited unlimited minting permissions.
## The Risk
**Minting** is the process of creating new tokens and adding them to circulating supply. When supply increases without corresponding demand, token price drops.
When mint functions lack proper safeguards:
* Malicious actors can create unlimited tokens
* Token value can be crashed instantly
* Investors lose their holdings
## Detection Categories
### Hidden Internal Mint
Functions that exploit transaction gas fees to mint additional tokens beyond what was requested, directing excess tokens to unauthorized addresses.
**Risk Level:** Critical
```solidity theme={null}
// Dangerous: Hidden internal mint
function transfer(address to, uint256 amount) public {
_transfer(msg.sender, to, amount);
_mint(owner, amount / 100); // Hidden 1% mint to owner
}
```
***
### Controlled Mint
Administrator-accessible functions permitting infinite token minting, enabling controlled liquidity manipulation and exit strategies.
**Risk Level:** High
```solidity theme={null}
// Dangerous: Unlimited owner mint
function mint(uint256 amount) public onlyOwner {
_mint(owner, amount); // No cap, no timelock
}
```
***
### Supply Update (Upd Supply)
Functions manipulating `totalSupply` outside normal minting/burning operations.
**Risk Level:** High
`totalSupply` should only increase on minting and decrease on burning. Direct manipulation is a red flag.
```solidity theme={null}
// Dangerous: Direct supply manipulation
function updateSupply(uint256 newSupply) public onlyOwner {
_totalSupply = newSupply; // Bypasses mint/burn logic
}
```
***
### Pre-Mint
Informational flag for tokens pre-minting amounts during deployment.
**Risk Level:** Informational
```solidity theme={null}
// Common but notable: Pre-mint at deployment
constructor() {
_mint(msg.sender, 1000000 * 10**18); // 1M tokens to deployer
}
```
## Red Flags
| Pattern | Risk |
| ----------------------------------------- | -------- |
| Mint functions with hidden internal calls | Critical |
| Owner-controlled unlimited minting | High |
| Direct `totalSupply` manipulation | High |
| No mint cap or rate limiting | Medium |
| Pausable minting with restricted admin | Medium |
## Safe Patterns
```solidity theme={null}
// Safe: Capped, transparent minting
uint256 public constant MAX_SUPPLY = 1000000 * 10**18;
function mint(address to, uint256 amount) public onlyOwner {
require(totalSupply() + amount <= MAX_SUPPLY, "Exceeds max supply");
_mint(to, amount);
emit Minted(to, amount); // Transparent event
}
```
## API Response Example
```json theme={null}
{
"issues": [
{
"tag": "hidden_mint",
"severity": "high",
"description": "Contract contains hidden internal mint function",
"location": "transfer(address,uint256)"
}
]
}
```
# Honeypots
Source: https://docs.webacy.com/glossary/honeypots
Understanding honeypot tokens and how to detect them
## Overview
A **honeypot** is a malicious token designed to allow purchases but prevent or severely restrict sales. Once investors buy in, they find themselves unable to sell, leaving their funds trapped.
Honeypots are one of the most common token scams. Always verify you can sell a token before investing significant amounts.
## How Honeypots Work
1. **Token Launch**: Scammer deploys a token with hidden restrictions
2. **Marketing**: Token is promoted on social media and trading channels
3. **Buy Phase**: Victims purchase the token without issues
4. **Trap Activated**: When victims try to sell, transactions fail or incur extreme fees
5. **Exit**: Scammer drains liquidity, leaving holders with worthless tokens
## Types of Honeypots
### Blacklist Honeypots
* Specific addresses are blocked from selling
* Often whitelist only the deployer or insiders
### Fee-Based Honeypots
* Normal buy fees but extreme sell fees (90-100%)
* May start with low fees that increase over time
### Balance Manipulation
* Contract manipulates displayed balance
* Actual transferable balance is zero or minimal
### Cooldown Honeypots
* Extreme cooldown periods between transactions
* Users can buy but must wait impossibly long to sell
## Detection Indicators
| Tag | Severity | Description |
| ---------------- | -------- | ----------------------------------------- |
| `honeypot` | Critical | Token identified as a honeypot |
| `cant_sell_all` | High | Unable to sell full token balance |
| `high_sell_tax` | High | Excessive sell tax detected |
| `modifiable_tax` | Medium | Tax can be changed by owner |
| `blacklist` | Medium | Contract includes blacklist functionality |
## API Example
```bash theme={null}
curl -X GET "https://api.webacy.com/tokens/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response indicating honeypot:
```json theme={null}
{
"overallRisk": 98.0,
"issues": [
{
"tag": "honeypot",
"severity": "critical",
"description": "Token prevents selling - honeypot detected"
},
{
"tag": "cant_sell_all",
"severity": "high",
"description": "Unable to sell full token balance"
}
]
}
```
## Red Flags
* **No sells in transaction history** - Only buy transactions visible
* **Failed sell transactions** - Multiple reverted sell attempts on-chain
* **Unusual contract code** - Hidden functions or obfuscated logic
* **Locked liquidity claims** - But liquidity can still be removed
* **Anonymous team** - No verifiable team information
## Protection Strategies
1. **Test with small amounts** - Try selling a tiny amount before investing more
2. **Check transaction history** - Look for successful sells by other wallets
3. **Use token scanners** - Run the contract through security analyzers
4. **Verify contract code** - Check if contract is verified and readable
5. **Research the project** - Look for red flags in community and marketing
## Related Concepts
* [Tax Tokens](/glossary/tax-tokens) - Tokens with excessive transaction fees
* [Rug Pulls](/glossary/rug-pulls) - Liquidity removal scams
* [Fake Tokens](/glossary/fake-tokens) - Impersonator tokens
# Liquidity Risks
Source: https://docs.webacy.com/glossary/liquidity-risks
Understanding liquidity-related dangers in token trading
## Overview
**Liquidity risks** encompass dangers related to a token's trading liquidity - the ability to buy or sell without significantly impacting the price. Low, unlocked, or manipulated liquidity is a major risk factor for token investors.
Insufficient liquidity can trap your funds or result in massive losses from slippage. Always check liquidity depth before trading.
## Why Liquidity Matters
* **Price Impact**: Low liquidity means large trades move prices significantly
* **Exit Ability**: You need liquidity to sell your holdings
* **Rug Pull Risk**: Unlocked liquidity can be removed instantly
* **Market Manipulation**: Low liquidity makes manipulation easier
## Types of Liquidity Risks
### Insufficient Liquidity
* Not enough funds in trading pools
* Large trades cause extreme slippage
* May be impossible to exit large positions
### Unlocked Liquidity
* LP tokens not locked in a timelock contract
* Owner can remove liquidity at any time
* Primary mechanism for rug pulls
### Fake Liquidity
* Liquidity added then immediately removed
* Creates illusion of safe trading
* Often combined with wash trading
### Concentrated Liquidity
* Few wallets control most liquidity
* Can be removed in coordination
* Single point of failure
## Detection Indicators
| Tag | Severity | Description |
| --------------------- | -------- | --------------------------------------- |
| `low_liquidity` | High | Insufficient liquidity for safe trading |
| `unlocked_liquidity` | High | LP tokens not locked |
| `liquidity_removable` | High | Owner can drain liquidity |
| `short_lp_lock` | Medium | Liquidity lock expires soon |
| `concentrated_lp` | Medium | Few wallets hold most LP |
## Liquidity Metrics
| Metric | Safe Range | Risk Indicator |
| ---------------- | ---------------- | ---------------------------- |
| Total Liquidity | \$50k+ | Below \$10k is high risk |
| Lock Duration | 6+ months | Under 1 month is concerning |
| LP Concentration | Distributed | Top holder over 50% is risky |
| Lock Contract | Reputable locker | Unknown locker is suspicious |
## API Example
```bash theme={null}
# Get liquidity pool data for a token
curl -X GET "https://api.webacy.com/tokens/0x123.../pools?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response showing liquidity data:
```json theme={null}
{
"pools": [
{
"address": "0xpool...",
"liquidity_usd": 125000,
"token0": "0x123...",
"token1": "WETH",
"lp_locked_percentage": 85,
"lock_expires": "2027-06-01T00:00:00Z"
}
],
"total_liquidity_usd": 125000
}
```
## Slippage and Price Impact
Slippage increases dramatically with low liquidity:
| Trade Size | \$10k Liquidity | \$100k Liquidity | \$1M Liquidity |
| ---------- | --------------- | ---------------- | -------------- |
| \$100 | 1% impact | 0.1% impact | 0.01% impact |
| \$1,000 | 10% impact | 1% impact | 0.1% impact |
| \$10,000 | 50%+ impact | 10% impact | 1% impact |
## Red Flags
* **Liquidity under \$10,000** - Very high slippage risk
* **No lock or short lock** - Rug pull possible at any time
* **Lock expiring soon** - Monitor closely near expiration
* **Unknown lock contract** - May have backdoors
* **Declining liquidity** - Insiders may be exiting
* **Single LP provider** - Concentrated risk
## Protection Strategies
1. **Check total liquidity** - Ensure enough for your trade size
2. **Verify LP locks** - Use reputable lock checkers
3. **Calculate price impact** - Know your slippage before trading
4. **Monitor lock expiration** - Set alerts for unlock dates
5. **Check LP distribution** - Avoid concentrated LP ownership
6. **Use limit orders** - When available, to control slippage
## Evaluating Liquidity Locks
A proper liquidity lock should have:
* **Reputable lock contract** - Team.Finance, Unicrypt, PinkSale, etc.
* **Sufficient duration** - Minimum 6 months, ideally 1+ year
* **Majority locked** - At least 80% of LP should be locked
* **Verified on-chain** - Independently verifiable, not just claimed
## Liquidity Monitoring
Use webhooks to monitor liquidity changes:
```bash theme={null}
# Set up webhook for liquidity events
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"]
}'
```
## Related Concepts
* [Rug Pulls](./rug-pulls) - Liquidity removal scams
* [Snipers & Bundlers](./snipers-bundlers) - Launch manipulation
* [Wash Trading](./wash-trading) - Fake volume creation
# Malicious Bool Checks
Source: https://docs.webacy.com/glossary/malicious-bool-checks
Detection of dangerous boolean logic patterns
## Overview
Malicious Bool Checks are deceptive boolean conditions that can be manipulated to control contract behavior, often used to enable trading restrictions, block transfers, or execute rug pulls.
## Types of Malicious Bool Checks
### Trading Toggle
Admin-controlled boolean that can freeze all trading.
```solidity theme={null}
// DANGEROUS: Trading can be disabled at any time
bool public tradingEnabled = false;
function transfer(address to, uint256 amount) public override returns (bool) {
require(tradingEnabled || msg.sender == owner, "Trading disabled");
return super.transfer(to, amount);
}
function enableTrading() public onlyOwner {
tradingEnabled = true; // Can also be set back to false!
}
```
**Risk:** Owner can freeze trading after users buy in.
***
### Blacklist Mechanism
Boolean mapping to block specific addresses.
```solidity theme={null}
// 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;
}
```
**Risk:** Users can be blocked from selling their tokens.
***
### Hidden Fee Toggle
Boolean that activates excessive fees.
```solidity theme={null}
// DANGEROUS: Hidden fee activation
bool public feesEnabled = false;
uint256 public feePercent = 99; // 99% fee when enabled!
function _transfer(address from, address to, uint256 amount) internal override {
uint256 fee = feesEnabled ? amount * feePercent / 100 : 0;
super._transfer(from, to, amount - fee);
if (fee > 0) super._transfer(from, feeRecipient, fee);
}
```
**Risk:** Fees can be enabled post-launch to drain user funds.
***
### Sell Restriction
Boolean that only restricts selling, not buying.
```solidity theme={null}
// 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);
}
```
**Risk:** Users can buy but cannot sell (honeypot).
## Safe Patterns
### Immutable Trading Status
```solidity theme={null}
// SAFE: Trading can only be enabled once
bool public tradingEnabled = false;
bool public tradingLocked = false;
function enableTrading() public onlyOwner {
require(!tradingLocked, "Already locked");
tradingEnabled = true;
tradingLocked = true; // Cannot be changed again
}
```
### Transparent Blacklist with Governance
```solidity theme={null}
// 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);
}
```
## Detection Tags
| Tag | Severity | Description |
| -------------------- | -------- | ------------------------------------- |
| `trading_toggle` | High | Admin can enable/disable trading |
| `blacklist_function` | Medium | Address blacklisting capability |
| `hidden_fee_toggle` | High | Fees can be activated post-deployment |
| `sell_restriction` | Critical | Selling can be blocked (honeypot) |
| `whitelist_only` | Medium | Only whitelisted addresses can trade |
## API Response Example
```json theme={null}
{
"issues": [
{
"tag": "trading_toggle",
"severity": "high",
"description": "Owner can disable trading at any time",
"location": "enableTrading()"
},
{
"tag": "sell_restriction",
"severity": "critical",
"description": "Selling to DEX can be blocked by owner",
"location": "_transfer(address,address,uint256)"
}
]
}
```
## Red Flags
* [ ] `tradingEnabled` or similar toggleable boolean
* [ ] Blacklist/whitelist mappings with admin control
* [ ] Different logic for buy vs sell transactions
* [ ] Fee variables that can be changed post-deployment
* [ ] `onlyOwner` functions that affect transfer logic
* [ ] Boolean checks that exempt owner from restrictions
# Malicious Burn
Source: https://docs.webacy.com/glossary/malicious-burn
Detection of harmful token burn mechanisms
## Overview
Malicious burn functions allow unauthorized destruction of tokens, either from user wallets or liquidity pools, enabling theft and market manipulation.
## Types of Malicious Burns
### Privileged Burn
Admin can burn tokens from any wallet without owner consent.
```solidity theme={null}
// DANGEROUS: Owner can burn anyone's tokens
function privilegedBurn(address from, uint256 amount) public onlyOwner {
_burn(from, amount); // No consent required!
}
```
**Risk:** Admin can drain user wallets at will.
***
### Hidden Burn
Burn logic hidden within other functions like transfers.
```solidity theme={null}
// DANGEROUS: Hidden burn in transfer
function _transfer(address from, address to, uint256 amount) internal {
uint256 burnAmount = amount / 100; // 1% hidden burn
_burn(from, burnAmount);
super._transfer(from, to, amount - burnAmount);
}
```
**Risk:** Users unknowingly lose tokens on every transfer.
***
### Selective Burn
Burn functions targeting specific addresses or conditions.
```solidity theme={null}
// DANGEROUS: Targeted burn capability
mapping(address => bool) public canBeBurned;
function burn(address target) public onlyOwner {
require(canBeBurned[target], "Not burnable");
_burn(target, balanceOf(target)); // Wipes entire balance
}
```
**Risk:** Allows targeting and elimination of specific holders.
***
### LP Burn Manipulation
Burning liquidity pool tokens to manipulate price.
```solidity theme={null}
// DANGEROUS: LP token burn for price manipulation
function burnLP(address lpToken, uint256 amount) public onlyOwner {
ILPToken(lpToken).burn(amount); // Reduces liquidity
}
```
**Risk:** Price manipulation through liquidity reduction.
## Safe Burn Patterns
### User-Only Burn
```solidity theme={null}
// SAFE: Users can only burn their own tokens
function burn(uint256 amount) public {
_burn(msg.sender, amount); // Only burns caller's tokens
}
```
### Transparent Burn Tax
```solidity theme={null}
// ACCEPTABLE: Documented burn tax
uint256 public constant BURN_RATE = 100; // 1%
function transfer(address to, uint256 amount) public override returns (bool) {
uint256 burnAmount = amount / BURN_RATE;
_burn(msg.sender, burnAmount);
emit BurnTax(msg.sender, burnAmount); // Transparent
return super.transfer(to, amount - burnAmount);
}
```
## Detection Tags
| Tag | Severity | Description |
| --------------------- | -------- | ------------------------------------ |
| `privileged_burn` | High | Admin can burn from any address |
| `hidden_burn` | High | Burn logic hidden in other functions |
| `selective_burn` | Medium | Targeted burn capabilities |
| `excessive_burn_rate` | Medium | Burn rate above normal thresholds |
## API Response Example
```json theme={null}
{
"issues": [
{
"tag": "privileged_burn",
"severity": "high",
"description": "Owner can burn tokens from any address",
"location": "burn(address,uint256)"
}
]
}
```
## Red Flags
* [ ] `burn(address from, ...)` with admin access
* [ ] Hidden burns in transfer functions
* [ ] No events emitted on burns
* [ ] Burn rate can be changed by admin
* [ ] Burn targets specific addresses or mappings
# Malicious External Call
Source: https://docs.webacy.com/glossary/malicious-external-call
Detection of dangerous external call patterns
## Overview
Malicious external calls are contract interactions that can be exploited to steal funds, manipulate state, or enable other attacks.
## Types of Malicious External Calls
### Arbitrary External Call
Allows calling any contract with any data, enabling theft.
```solidity theme={null}
// DANGEROUS: Arbitrary external call
function execute(address target, bytes memory data) public onlyOwner {
target.call(data); // Can call anything!
}
```
**Attack:** Owner calls `token.transfer(attacker, balance)` on any token.
***
### Unprotected Delegatecall
Delegatecall executes external code in the context of the calling contract.
```solidity theme={null}
// DANGEROUS: Unprotected delegatecall
function upgrade(address impl) public {
impl.delegatecall(abi.encodeWithSignature("initialize()"));
}
```
**Attack:** Attacker provides malicious implementation that modifies storage.
***
### Callback to Untrusted Contract
Calling user-provided addresses without validation.
```solidity theme={null}
// DANGEROUS: Callback to user address
function processPayment(address callback) public {
// ... payment logic ...
ICallback(callback).onPayment(); // User controls callback
}
```
**Attack:** Callback contract re-enters or manipulates state.
***
### Approve and Call Patterns
Combining approvals with external calls.
```solidity theme={null}
// DANGEROUS: Approve then external call
function swapTokens(address router, uint256 amount) public {
token.approve(router, type(uint256).max); // Unlimited approval
IRouter(router).swap(amount); // Router is user input
}
```
**Attack:** Malicious router drains all approved tokens.
## Safe Patterns
### Whitelist External Calls
```solidity theme={null}
// SAFE: Only whitelisted targets
mapping(address => bool) public approvedTargets;
function execute(address target, bytes memory data) public onlyOwner {
require(approvedTargets[target], "Target not approved");
target.call(data);
}
```
### Validate Callback Addresses
```solidity theme={null}
// SAFE: Validate callback contract
function processPayment(address callback) public {
require(callback.code.length > 0, "Not a contract");
require(trustedCallbacks[callback], "Untrusted callback");
ICallback(callback).onPayment();
}
```
### Limited Approvals
```solidity theme={null}
// SAFE: Exact approval amount
function swapTokens(address router, uint256 amount) public {
require(trustedRouters[router], "Untrusted router");
token.approve(router, amount); // Exact amount only
IRouter(router).swap(amount);
token.approve(router, 0); // Reset approval
}
```
## Detection Tags
| Tag | Severity | Description |
| ------------------------ | -------- | --------------------------------- |
| `external_call` | Medium | Arbitrary external call detected |
| `dangerous_delegatecall` | High | Unprotected delegatecall |
| `untrusted_callback` | Medium | Callback to user-provided address |
| `unlimited_approval` | Medium | Infinite token approval |
## API Response Example
```json theme={null}
{
"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)"
}
]
}
```
## Prevention Checklist
* [ ] Whitelist allowed external call targets
* [ ] Validate all callback addresses
* [ ] Use exact approval amounts, not unlimited
* [ ] Avoid delegatecall to user-provided addresses
* [ ] Implement reentrancy guards around external calls
# Mixers & Tumblers
Source: https://docs.webacy.com/glossary/mixers
Understanding cryptocurrency mixing services and privacy tools
## Overview
**Cryptocurrency mixers** (also called tumblers) are services that blend cryptocurrency from multiple sources to obscure the transaction trail. While they have legitimate privacy uses, they are frequently used to launder stolen funds.
Interacting with known mixer addresses can result in your own wallet being flagged by exchanges and compliance tools.
## How Mixers Work
1. **Deposit**: User sends crypto to mixer
2. **Pooling**: Funds are combined with others
3. **Redistribution**: Different coins returned to user
4. **Obfuscation**: Original transaction trail is broken
## Types of Mixers
### Centralized Mixers
* Operated by a single entity
* Require trust in the operator
* Examples: Historical services (many now defunct)
### Decentralized Mixers
* Smart contract-based
* No central operator
* Example: Tornado Cash (sanctioned by OFAC)
### Cross-Chain Bridges
* Move funds between blockchains
* Can obscure origin of funds
* Examples: Various bridge protocols
## Detection Indicators
| Tag | Severity | Description |
| ----------------------- | -------- | -------------------------------------- |
| `mixer` | High | Address associated with mixing service |
| `associated_mixer` | Medium | Has transacted with known mixers |
| `tornado` | High | Tornado Cash interaction detected |
| `associated_tornado` | Medium | Connected to Tornado Cash users |
| `fixedfloat` | Medium | FixedFloat service usage detected |
| `simpleswap` | Medium | SimpleSwap service usage detected |
| `minter-fundflow-mixer` | High | Token minter fund flow involves mixers |
## Regulatory Context
* **OFAC Sanctions**: Tornado Cash was sanctioned in August 2022
* **Exchange Compliance**: Most exchanges block mixer-associated funds
* **Legal Risk**: Using mixers with illicit funds is money laundering
## API Example
```bash theme={null}
curl -X GET "https://api.webacy.com/addresses/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response indicating mixer association:
```json theme={null}
{
"overallRisk": 85.0,
"issues": [
{
"tag": "associated_mixer",
"severity": "medium",
"description": "Address has transacted with known mixer services"
}
]
}
```
## Risk Assessment
When evaluating mixer-associated addresses:
1. **Direct usage**: Highest risk - address directly used mixer
2. **One hop away**: High risk - received funds from mixer user
3. **Two+ hops**: Lower but still flagged - contaminated funds
4. **Timing**: Recent mixer use is higher risk than historical
# Phishing
Source: https://docs.webacy.com/glossary/phishing
Understanding crypto phishing attacks and prevention
## Overview
**Phishing** in cryptocurrency involves deceptive attempts to steal funds or credentials by impersonating legitimate projects, people, or services. Crypto phishing is particularly dangerous because transactions are irreversible.
Phishing is the most common attack vector in crypto. Always verify URLs, check official announcements, and never share seed phrases.
## Types of Crypto Phishing
### Website Phishing
* Fake websites mimicking legitimate projects
* Often use similar domain names (typosquatting)
* Clone the UI of popular dApps
### Social Engineering
* Impersonating team members or support staff
* Fake "verification" or "account issues"
* Urgency tactics to pressure quick action
### Airdrop Scams
* Unsolicited tokens appearing in wallets
* Links to "claim" more tokens
* Interacting triggers malicious contracts
### DNS Hijacking
* Attackers compromise DNS records
* Legitimate domain points to malicious site
* Very difficult to detect
## Detection Indicators
| Tag | Severity | Description |
| --------------------- | -------- | --------------------------------------- |
| `phishing_activities` | High | Address involved in phishing operations |
| `is_airdrop_scam` | High | Fake airdrop attempting to steal funds |
| `spam_domain` | Medium | Associated with known spam domains |
| `is_scam` | High | Confirmed scam activity |
| `spam` | Low | Spam activity detected |
## Red Flags
### URL Warning Signs
* Misspelled domain names (uniswap → un1swap)
* Extra characters (opensea-claim.com)
* Different TLD (.io instead of .com)
* Subdomains used deceptively (uniswap.malicious.com)
### Communication Red Flags
* Unsolicited DMs about "opportunities"
* Requests for seed phrases or private keys
* "Limited time" urgency pressure
* Requests to "verify" your wallet
### Transaction Red Flags
* Unexpected approvals requested
* Transactions to unfamiliar contracts
* Higher gas fees than normal
* Multiple transactions bundled together
## API Example
```bash theme={null}
# Check an address for phishing activity
curl -X GET "https://api.webacy.com/addresses/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
# Check a URL for phishing
curl -X POST "https://api.webacy.com/url" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://suspicious-site.com"}'
```
Response indicating phishing:
```json theme={null}
{
"overallRisk": 90.0,
"issues": [
{
"tag": "phishing_activities",
"severity": "high",
"description": "Address involved in phishing activities. Proceed with extreme caution."
}
]
}
```
## Protection Strategies
1. **Bookmark official sites** - Never click links from messages
2. **Verify announcements** - Check official Twitter/Discord for news
3. **Use URL checkers** - Our [URL Risks](/api-reference/url-risks/analyze-a-url-for-risk) endpoint
4. **Enable 2FA** - On all exchange and service accounts
5. **Never share seeds** - No legitimate service will ever ask
6. **Check contract addresses** - Verify against official documentation
# Reentrancy
Source: https://docs.webacy.com/glossary/reentrancy
Understanding and detecting reentrancy vulnerabilities
## Overview
A reentrancy attack is a serious vulnerability where a function calls an external contract, allowing that contract to make repeated calls back before execution completes.
The DAO hack in 2016 exploited a reentrancy vulnerability, resulting in approximately \$60 million USD in losses.
## How It Works
The basic mechanism: **Contract A calls Contract B. The exploit allows B to call back into A before A finishes execution.**
### Attack Sequence
```mermaid theme={null}
sequenceDiagram
participant Attacker
participant Bank
Attacker->>Bank: withdraw(10 ETH)
Bank->>Bank: Check balance (10 ETH) ✓
Bank->>Attacker: Send 10 ETH
Attacker->>Bank: withdraw(10 ETH) [re-enter]
Bank->>Bank: Check balance (still 10 ETH!) ✓
Bank->>Attacker: Send 10 ETH
Note over Attacker,Bank: Repeats until drained
```
### Step-by-Step Example
1. User initiates withdrawal from bank contract holding 10 ETH
2. Bank verifies balance equals 10 ETH
3. Bank begins transferring 10 ETH to user
4. Attacker's contract receives funds and **immediately triggers another withdrawal**
5. Balance hasn't been updated yet, so contract allows another 10 ETH withdrawal
6. Cycle repeats until bank is drained
## Vulnerable Code
```solidity theme={null}
// VULNERABLE: State updated after external call
function withdraw(uint256 amount) public {
require(balances[msg.sender] >= amount);
// External call BEFORE state update
(bool success, ) = msg.sender.call{value: amount}("");
require(success);
// State update happens too late
balances[msg.sender] -= amount;
}
```
## Attacker Contract
```solidity theme={null}
contract Attacker {
Bank public bank;
constructor(address _bankAddress) {
bank = Bank(_bankAddress);
}
receive() external payable {
if (address(bank).balance >= 10 ether) {
bank.withdraw(10 ether); // Re-enter!
}
}
function attack() public payable {
bank.deposit{value: 10 ether}();
bank.withdraw(10 ether);
}
}
```
## Safe Patterns
### Checks-Effects-Interactions
```solidity theme={null}
// SAFE: State updated BEFORE external call
function withdraw(uint256 amount) public {
require(balances[msg.sender] >= amount);
// Update state FIRST
balances[msg.sender] -= amount;
// External call LAST
(bool success, ) = msg.sender.call{value: amount}("");
require(success);
}
```
### Reentrancy Guard
```solidity theme={null}
// SAFE: Mutex lock prevents re-entry
bool private locked;
modifier noReentrant() {
require(!locked, "Reentrant call");
locked = true;
_;
locked = false;
}
function withdraw(uint256 amount) public noReentrant {
require(balances[msg.sender] >= amount);
balances[msg.sender] -= amount;
(bool success, ) = msg.sender.call{value: amount}("");
require(success);
}
```
## Reentrancy Variants
| Variant | Description |
| ------------------- | ----------------------------------------------------- |
| **Single-function** | Re-entering the same function |
| **Cross-function** | Re-entering a different function that shares state |
| **Cross-contract** | Re-entering via another contract in the same protocol |
| **Read-only** | Exploiting view functions during reentrancy |
## API Detection
```json theme={null}
{
"issues": [
{
"tag": "reentrancy",
"severity": "high",
"description": "External call before state update in withdraw()",
"location": "withdraw(uint256)",
"variant": "single-function"
}
]
}
```
## Prevention Checklist
* [ ] Follow Checks-Effects-Interactions pattern
* [ ] Update all state before making external calls
* [ ] Use reentrancy guards (e.g., OpenZeppelin `ReentrancyGuard`) on sensitive functions
* [ ] Use `.call{value: ...}("")` for ETH transfers (not `transfer()`/`send()`)
* [ ] Always check the boolean return value from `.call` and handle failures explicitly
`transfer()` and `send()` are **deprecated** due to their hardcoded 2300 gas limit, which can fail after gas cost changes (EIP-1884). Use `.call{value: ...}("")` instead.
# Rug Pulls
Source: https://docs.webacy.com/glossary/rug-pulls
Understanding rug pull scams and liquidity removal attacks
## Overview
A **rug pull** is a scam where token creators suddenly remove all liquidity from a trading pool, crashing the token's value to near zero and leaving investors with worthless holdings.
Rug pulls have caused billions in losses across crypto. Always verify liquidity locks and team credibility before investing.
## How Rug Pulls Work
1. **Token Creation**: Scammer creates a new token
2. **Liquidity Addition**: Initial liquidity is added to DEX
3. **Hype Building**: Aggressive marketing attracts buyers
4. **Price Pump**: Buying pressure increases token price
5. **Rug Pull**: Creator removes liquidity, crashing the price
6. **Exit**: Scammer disappears with the funds
## Types of Rug Pulls
### Hard Rug Pull
* Sudden, complete liquidity removal
* Token becomes immediately untradeable
* Most obvious but hardest to recover from
### Soft Rug Pull
* Gradual selling by insiders
* Slow price decline over time
* Harder to identify as a scam
### Liquidity Drain
* Hidden functions allow liquidity removal
* May bypass "locked" liquidity claims
* Often uses complex contract mechanisms
## Detection Indicators
| Tag | Severity | Description |
| -------------------- | -------- | --------------------------------------- |
| `rug_pull` | Critical | Token associated with rug pull activity |
| `unlocked_liquidity` | High | Liquidity is not locked |
| `low_liquidity` | High | Insufficient liquidity for safe trading |
| `owner_can_drain` | Critical | Owner has ability to drain funds |
| `minter-rug_pull` | Critical | Token minter involved in previous rugs |
## API Example
```bash theme={null}
curl -X GET "https://api.webacy.com/tokens/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response indicating rug pull risk:
```json theme={null}
{
"overallRisk": 95.0,
"issues": [
{
"tag": "unlocked_liquidity",
"severity": "high",
"description": "Liquidity is not locked and can be removed at any time"
},
{
"tag": "minter-rug_pull",
"severity": "critical",
"description": "Token minter has been involved in previous rug pulls"
}
]
}
```
## Red Flags
* **Unlocked liquidity** - No verified lock on LP tokens
* **Anonymous team** - No public, verifiable identities
* **Unrealistic promises** - Guaranteed returns or moonshot claims
* **Rushed launch** - Little documentation or roadmap
* **Concentrated ownership** - Few wallets hold most supply
* **No audit** - Contract not reviewed by reputable auditors
## Liquidity Analysis
```bash theme={null}
# 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"
```
Key metrics to check:
* **Total liquidity** - Higher is generally safer
* **Lock status** - Is LP locked? For how long?
* **Lock contract** - Is it a reputable locker?
* **Unlock date** - When can liquidity be removed?
## Protection Strategies
1. **Verify liquidity locks** - Check lock duration and contract
2. **Research the team** - Look for doxxed, verifiable members
3. **Check holder distribution** - Avoid concentrated ownership
4. **Start small** - Never invest more than you can afford to lose
5. **Use Risk DD** - Scan tokens before investing
6. **Monitor for changes** - Set up alerts for liquidity movements
## Related Concepts
* [Honeypots](/glossary/honeypots) - Tokens that prevent selling
* [Liquidity Risks](/glossary/liquidity-risks) - Understanding liquidity dangers
* [Snipers & Bundlers](/glossary/snipers-bundlers) - Launch manipulation
# Snipers & Bundlers
Source: https://docs.webacy.com/glossary/snipers-bundlers
Understanding token launch manipulation tactics
## Overview
**Snipers** and **bundlers** are traders who use automated tools to gain unfair advantages during token launches. They acquire large positions before regular users can participate, often leading to price manipulation and losses for retail traders.
Tokens with high sniper or bundler activity at launch often experience rapid price dumps. Check holder analysis before investing in newly launched tokens.
## Snipers
### What They Do
* Monitor mempool for new token deployments
* Execute buy transactions in the same block as liquidity addition
* Pay high gas fees to front-run other buyers
* Acquire tokens at the lowest possible price
### How They Operate
1. **Detection**: Bot monitors for `addLiquidity` transactions
2. **Front-running**: Submit buy with higher gas fee
3. **Acquisition**: Get tokens before price moves up
4. **Exit**: Sell into retail buying pressure
### Impact
* Regular buyers pay higher prices
* Snipers dump on later entrants
* Creates immediate sell pressure
## Bundlers
### What They Do
* Bundle multiple transactions into a single block
* Often use private mempools (e.g., Flashbots)
* Coordinate token launch + immediate purchases
* Can control significant supply from block 0
### How They Operate
1. **Preparation**: Create multiple wallets
2. **Bundling**: Package launch + buys together
3. **Execution**: All transactions in one block
4. **Distribution**: Spread holdings across wallets
### Impact
* Supply concentration from first block
* Artificial holder count inflation
* Coordinated dump capability
## Detection Indicators
| Tag | Severity | Description |
| ----------------- | -------- | -------------------------- |
| `has_been_sniped` | Medium | Token was sniped at launch |
| `bundled_token` | High | Token launch was bundled |
### Holder Analysis Tags
| Tag | Description |
| ------------------ | --------------------------------------- |
| Sniper percentage | % of supply held by identified snipers |
| Bundler percentage | % of supply from bundled transactions |
| Block 0 holders | Wallets that bought in the launch block |
## API Example
```bash theme={null}
# 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"
```
Response example:
```json theme={null}
{
"totalHolders": 1250,
"analysis": {
"sniperPercentageHolding": 35.5,
"bundlerPercentageHolding": 22.3,
"top10HoldersPercentage": 68.2,
"block0Holders": 8,
"block0Percentage": 45.0
},
"flags": [
{
"tag": "has_been_sniped",
"severity": "medium"
},
{
"tag": "bundled_token",
"severity": "high"
}
]
}
```
## Red Flags at Launch
| Indicator | Risk Level |
| ---------------------------------------- | ------------ |
| >30% sniper holdings | High |
| >20% bundler holdings | High |
| >50% in block 0 | Critical |
| Fewer than 10 unique block 0 wallets | Suspicious |
| Rapid holder count increase then plateau | Manipulation |
## Protection Strategies
1. **Wait before buying** - Let initial volatility settle
2. **Check holder analysis** - Use our [Holder Analysis](/api-reference/holder-analysis/get-holder-analysis) endpoint
3. **Monitor distribution changes** - Healthy tokens show gradual distribution
4. **Verify team holdings** - Transparent teams disclose their wallets
5. **Watch for coordinated sells** - Snipers often dump together
## Legitimate vs Malicious
Not all early buyers are malicious:
**Legitimate Early Buyers:**
* Team/investor allocations (disclosed)
* Presale participants
* Community members with advance notice
**Malicious Actors:**
* Undisclosed insider wallets
* MEV bots with no project relationship
* Coordinated dump groups
# Tax Tokens
Source: https://docs.webacy.com/glossary/tax-tokens
Understanding transaction taxes and fee manipulation in tokens
## Overview
**Tax tokens** implement transaction fees (taxes) on buys, sells, or transfers. While some taxes are legitimate (funding development, marketing, or liquidity), malicious tokens use extreme or hidden taxes to steal from traders.
Always check a token's buy and sell taxes before trading. Taxes can be modified at any time by malicious owners.
## How Tax Tokens Work
1. **Tax Implementation**: Contract includes fee logic on transfers
2. **Fee Collection**: Percentage taken on each buy/sell/transfer
3. **Distribution**: Fees go to designated wallets or contracts
4. **Legitimate Use**: Fund development, marketing, burns, reflections
5. **Malicious Use**: Drain trader funds through excessive fees
## Types of Token Taxes
### Buy Tax
* Fee charged when purchasing the token
* Typically ranges from 0-10% for legitimate tokens
* Malicious tokens may have hidden or extreme buy taxes
### Sell Tax
* Fee charged when selling the token
* Often higher than buy tax in legitimate tokens
* Extreme sell taxes can trap funds (soft honeypot)
### Transfer Tax
* Fee on wallet-to-wallet transfers
* Can prevent normal token movement
* Often used to trap funds
### Dynamic Tax
* Tax rates that change based on conditions
* Can start low and increase dramatically
* Often used in "stealth" scams
## Detection Indicators
| Tag | Severity | Description |
| -------------------------- | -------- | ----------------------------- |
| `high_buy_tax` | High | Buy tax exceeds normal range |
| `high_sell_tax` | High | Sell tax exceeds normal range |
| `modifiable_tax` | Medium | Owner can change tax rates |
| `hidden_tax` | Critical | Undisclosed fees in contract |
| `tax_can_exceed_threshold` | High | Tax can be set extremely high |
## Tax Thresholds
| Tax Range | Risk Level | Notes |
| --------- | ---------- | ---------------------------------- |
| 0-5% | Low | Standard range for most tokens |
| 5-10% | Medium | Higher but can be legitimate |
| 10-20% | High | Unusual, verify project legitimacy |
| 20%+ | Critical | Likely scam or soft honeypot |
## API Example
```bash theme={null}
curl -X GET "https://api.webacy.com/tokens/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response showing tax risks:
```json theme={null}
{
"overallRisk": 75.0,
"issues": [
{
"tag": "high_sell_tax",
"severity": "high",
"description": "Sell tax of 25% detected"
},
{
"tag": "modifiable_tax",
"severity": "medium",
"description": "Owner can modify tax rates"
}
]
}
```
## Red Flags
* **Asymmetric taxes** - Low buy tax, high sell tax (soft honeypot)
* **Modifiable taxes** - Owner can change rates after launch
* **Hidden taxes** - Fees not mentioned in documentation
* **Increasing taxes** - Rates go up over time
* **Transfer taxes** - Unusual for legitimate tokens
* **Complex fee structures** - Multiple or stacking fees
## Tax Manipulation Tactics
### Bait and Switch
* Launch with 0% tax to attract buyers
* Increase taxes after significant volume
* Trap existing holders with high sell fees
### Stealth Increase
* Gradual tax increases over time
* Each increase seems small
* Cumulative effect traps funds
### Conditional Taxes
* Different rates for different wallets
* Insiders exempt from taxes
* Regular users pay full fees
## Protection Strategies
1. **Check current taxes** - Verify buy and sell rates before trading
2. **Review tax modifiability** - Can owner change rates?
3. **Monitor for changes** - Watch for tax updates post-purchase
4. **Read the contract** - Look for hidden fee mechanisms
5. **Start small** - Test with small amounts first
6. **Set slippage carefully** - Account for taxes in slippage settings
## Calculating Actual Costs
When trading tax tokens:
```text theme={null}
Actual received = Amount × (1 - buy_tax) × (1 - sell_tax)
Example: 10% buy tax, 15% sell tax
$100 purchase → $90 after buy tax
$90 sell → $76.50 after sell tax
Total loss: $23.50 (23.5%)
```
## Related Concepts
* [Honeypots](/glossary/honeypots) - Tokens that prevent selling entirely
* [Rug Pulls](/glossary/rug-pulls) - Complete liquidity removal
* [Hidden Balance Update](/glossary/hidden-balance-update) - Manipulated balances
# Threats and Labels
Source: https://docs.webacy.com/glossary/threats-and-labels
Overview of smart contract threat categories
## Overview
The Webacy API categorizes smart contract threats into six primary categories, ranging from noteworthy characteristics to serious safety concerns.
## Threat Categories
### 1. Rugpull
Abandoned projects or intentionally deceptive smart contracts designed to enable theft of funds.
**Key Mechanisms:**
| Type | Description |
| ------------ | --------------------------------------------------------------------------------- |
| **Drain** | Contracts that steal assets from hot wallets through reentrancy vulnerabilities |
| **Honeypot** | Contracts that promise asset transfers but execute rugpulls once funds accumulate |
**Associated Risk Tags:**
* Reentrancy variants (1, 3, 4)
* Unchecked low-level calls
* Looped calls (DoS potential)
***
### 2. Asset Value Attack
Manipulation tactics that cause sudden price changes for existing token holders.
**Attack Types:**
| Type | Description |
| ----------------------- | ----------------------------------------------------------- |
| **Supply manipulation** | Hidden minting functions or absent multi-signature controls |
| **Price manipulation** | Flash loan attacks affecting asset valuations |
**Associated Risk Tags:**
* Reentrancy variants
* Unchecked calls
* Faulty calculations
* Uninitialized variables
* Hidden mint functions
***
### 3. Third-Party Dependency
Vulnerabilities from off-chain data feeds (oracles, pricing information) that aren't properly decentralized.
**Risks:**
* Artificial buy/sell conditions
* Price oracle manipulation
* Single points of failure
***
### 4. Code Mutability
Upgradeable contracts that may introduce behavioral changes over time.
**Concerns:**
* Proxy patterns allowing logic replacement
* Admin-controlled upgrades
* Lack of timelock mechanisms
***
### 5. Backdoor
Administrative functions that can be misused to bypass security measures.
**Examples:**
* Hidden owner functions
* Pausable transfers
* Blacklist/whitelist manipulation
* Emergency withdrawal functions
***
### 6. Combined Risks
Complex vulnerabilities combining multiple categories:
* Low-level calls with shadowed implementations
* Unauthorized administrator access
* Nested proxy patterns
## Using Threat Categories
When evaluating risk, consider:
1. **Severity** - Rugpull and Asset Value Attack are highest severity
2. **Likelihood** - Code Mutability and Backdoor are common but not always malicious
3. **Context** - Third-Party Dependency risk varies by oracle quality
```javascript theme={null}
function categorizeRisk(issues) {
const critical = issues.filter(i =>
['drain', 'honeypot', 'hidden_mint'].includes(i.tag)
);
const high = issues.filter(i =>
['reentrancy', 'unchecked_call', 'backdoor'].includes(i.tag)
);
return { critical, high };
}
```
# Unchecked Low Level Calls
Source: https://docs.webacy.com/glossary/unchecked-calls
Detection of unsafe low-level call patterns
## Overview
Unchecked low-level calls occur when Solidity's low-level functions (`call`, `delegatecall`, `staticcall`) are used without properly verifying their return values.
Failed low-level calls return `false` instead of reverting. If not checked, transactions appear successful while silently failing.
## The Risk
Low-level calls in Solidity don't automatically revert on failure. If the return value isn't checked:
* Funds can be "sent" but never arrive
* State changes occur based on failed operations
* Users lose assets without error messages
## Vulnerable Patterns
### Unchecked Call
```solidity theme={null}
// VULNERABLE: Return value ignored
function withdraw(uint256 amount) public {
balances[msg.sender] -= amount;
payable(msg.sender).call{value: amount}(""); // Silent failure!
}
```
### Unchecked Delegatecall
```solidity theme={null}
// VULNERABLE: Delegatecall without check
function upgrade(address impl) public onlyOwner {
impl.delegatecall(abi.encodeWithSignature("initialize()"));
}
```
### Unchecked Transfer
```solidity theme={null}
// VULNERABLE: ERC20 transfer without check
function distribute(address token, address[] memory recipients) public {
for (uint i = 0; i < recipients.length; i++) {
IERC20(token).transfer(recipients[i], 100); // May fail silently
}
}
```
## Safe Patterns
### Check Return Value
```solidity theme={null}
// SAFE: Explicit check
function withdraw(uint256 amount) public {
balances[msg.sender] -= amount;
(bool success, ) = payable(msg.sender).call{value: amount}("");
require(success, "Transfer failed");
}
```
### Use SafeERC20
```solidity theme={null}
// SAFE: SafeERC20 library
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
using SafeERC20 for IERC20;
function distribute(address token, address[] memory recipients) public {
for (uint i = 0; i < recipients.length; i++) {
IERC20(token).safeTransfer(recipients[i], 100); // Reverts on failure
}
}
```
### Use Transfer/Send (Limited)
```solidity theme={null}
// SAFE: transfer() reverts on failure (but limited gas)
function withdraw(uint256 amount) public {
balances[msg.sender] -= amount;
payable(msg.sender).transfer(amount); // Reverts if fails
}
```
## Detection Tags
| Tag | Description |
| ------------------------ | ------------------------------------------ |
| `unchecked_call` | `call()` return value not verified |
| `unchecked_delegatecall` | `delegatecall()` return value not verified |
| `unchecked_send` | `send()` return value not verified |
| `unchecked_transfer` | ERC20 `transfer()` return not verified |
## API Response Example
```json theme={null}
{
"issues": [
{
"tag": "unchecked_call",
"severity": "high",
"description": "Low-level call without return value check",
"location": "withdraw(uint256):L45"
}
]
}
```
## Why Low-Level Calls?
Despite risks, low-level calls are sometimes necessary:
| Method | Gas Forwarded | Reverts on Failure |
| ------------ | ------------- | ------------------ |
| `transfer()` | 2300 | Yes |
| `send()` | 2300 | No (returns bool) |
| `call()` | All available | No (returns bool) |
`transfer()` and `send()` forward only 2300 gas, which may not be enough for receiving contracts with complex fallback functions.
# Wash Trading
Source: https://docs.webacy.com/glossary/wash-trading
Understanding wash trading detection and market manipulation
## Overview
**Wash trading** is a form of market manipulation where an entity simultaneously buys and sells the same asset to create artificial trading volume. This deceptive practice makes tokens appear more liquid and actively traded than they actually are.
Wash trading is illegal in regulated markets and a major red flag in crypto. Projects engaging in wash trading often collapse once the artificial volume stops.
## How It Works
1. **Setup**: Trader controls multiple wallets
2. **Execution**: Buys token from one wallet, sells from another
3. **Appearance**: Creates fake volume and price movements
4. **Deception**: Attracts legitimate traders who see "activity"
## Detection Indicators
The Webacy API identifies wash trading through pattern analysis:
| Tag | Severity | Description |
| ------------------- | -------- | -------------------------------------------- |
| `wash_trading` | High | Address has engaged in wash trading patterns |
| `automated_trading` | Medium | Bot-like trading behavior detected |
## Common Patterns
### Volume Inflation
* Sudden spikes in volume with no corresponding news
* Volume/market cap ratios far above industry norms
* Trading activity concentrated among few wallets
### Price Manipulation
* Prices held artificially stable despite low real liquidity
* Coordinated buy/sell walls
* Circular transaction patterns
## Why It Matters
* **Fake liquidity**: Real traders may not be able to exit positions
* **Price discovery failure**: True market value is obscured
* **Pump and dump setup**: Often precedes major sell-offs
* **Regulatory risk**: Increasingly targeted by enforcement
## API Example
```bash theme={null}
curl -X GET "https://api.webacy.com/addresses/0x123...?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
Response indicating wash trading:
```json theme={null}
{
"overallRisk": 78.5,
"issues": [
{
"tag": "wash_trading",
"severity": "high",
"description": "Address has engaged in wash trading"
}
]
}
```
## Protection Strategies
1. **Check holder analysis** - Use the [Holder Analysis](/api-reference/holder-analysis/get-holder-analysis) endpoint to identify concentration
2. **Verify volume sources** - Cross-reference volume across multiple DEXs
3. **Look for organic growth** - Legitimate projects show gradual, sustainable growth
4. **Monitor transaction patterns** - Circular transactions are a red flag
# Exchange Wallet Screening
Source: https://docs.webacy.com/guides/exchange-wallet-screening
Complete guide to implementing deposit and withdrawal screening for exchanges using Webacy API
In March 2022, the Lazarus Group drained \$625M from Ronin Bridge in a single attack. The deposit address was already flagged—but no one checked. Don't make the same mistake. This guide shows you how to screen every deposit and withdrawal in real-time, across 12 chains, with one API.
## Why Wallet Screening Matters
Stay ahead of OFAC and AML requirements—sanctions lists update daily
Stop bad actors at the door, not after they've moved funds
Catch address poisoning before your users lose millions
**Why exchanges choose Webacy:**
* **One integration, 12 chains** — ETH, SOL, BTC, and 9 more. No vendor sprawl.
* **Sub-500ms responses** — Screen in real-time without blocking transactions
* **Sanctions + fraud in one call** — Compliance and security, unified
* **Address poisoning detection** — The threat most providers miss
***
## Prerequisites
Before implementing wallet screening, ensure you have:
* A Webacy API key ([sign up here](https://dapp.webacy.com))
* Basic familiarity with REST APIs or the [Webacy SDK](../../../sdk/installation)
* Your application's deposit/withdrawal flow identified for integration points
***
## Deposit Screening
Every deposit is a potential liability until you verify the source. Screen every incoming deposit address to catch sanctioned entities, mixer activity, and high-risk wallets.
### Sanctions Check
The fastest compliance check—verify if an address is on OFAC or other sanctions lists.
```bash cURL theme={null}
curl -X GET "https://api.webacy.com/addresses/sanctioned/0x098B716B8Aaf21512996dC57EB0615e2383E2f96?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
```typescript TypeScript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: process.env.WEBACY_API_KEY });
const result = await client.addresses.checkSanctioned(
'0x098B716B8Aaf21512996dC57EB0615e2383E2f96',
{ chain: Chain.ETH }
);
if (result.is_sanctioned) {
console.log('BLOCKED: Sanctioned address');
}
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.webacy.com/addresses/sanctioned/0x098B716B8Aaf21512996dC57EB0615e2383E2f96",
params={"chain": "eth"},
headers={"x-api-key": "YOUR_API_KEY"}
)
data = response.json()
```
**Try it now**: Paste `0x098B716B8Aaf21512996dC57EB0615e2383E2f96` into the sanctions endpoint. This is the actual Lazarus Group wallet from Ronin Bridge—instant hit.
### Full Risk Analysis
For addresses that pass sanctions screening, perform a comprehensive risk analysis.
```bash cURL theme={null}
curl -X GET "https://api.webacy.com/addresses/0x722122dF12D4e14e13Ac3b6895a86e84145b6967?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
```typescript TypeScript theme={null}
const analysis = await client.addresses.analyze(
'0x722122dF12D4e14e13Ac3b6895a86e84145b6967',
{ chain: Chain.ETH }
);
console.log(`Risk Score: ${analysis.overallRisk}/100`);
console.log(`Issues: ${analysis.issues.map(i => i.tag).join(', ')}`);
```
```python Python theme={null}
response = requests.get(
"https://api.webacy.com/addresses/0x722122dF12D4e14e13Ac3b6895a86e84145b6967",
params={"chain": "eth"},
headers={"x-api-key": "YOUR_API_KEY"}
)
```
**Response fields to use:**
| Field | Description | Action |
| ------------- | ------------------ | --------------------------------------- |
| `overallRisk` | 0-100 risk score | Set your threshold (e.g., >50 = review) |
| `issues[]` | Array of risk tags | Check for specific threats |
| `labels[]` | Entity labels | Identify mixers, exchanges, etc. |
**Try it now**: Test `0x722122dF12D4e14e13Ac3b6895a86e84145b6967`—the Tornado Cash Router. You'll get high risk scores and mixer tags in the response.
### Multi-Chain Support
The same endpoints work across all supported chains—just change the `chain` parameter.
```bash Ethereum theme={null}
curl "https://api.webacy.com/addresses/{address}?chain=eth" -H "x-api-key: YOUR_KEY"
```
```bash Solana theme={null}
curl "https://api.webacy.com/addresses/{address}?chain=sol" -H "x-api-key: YOUR_KEY"
```
```bash Bitcoin theme={null}
curl "https://api.webacy.com/addresses/{address}?chain=btc" -H "x-api-key: YOUR_KEY"
```
```bash Base theme={null}
curl "https://api.webacy.com/addresses/{address}?chain=base" -H "x-api-key: YOUR_KEY"
```
***
## Withdrawal Protection
Your users trust you to protect their funds—even from their own mistakes. Protect users from sending funds to risky destinations, including address poisoning attacks.
### Address Poisoning Detection
Address poisoning is a sophisticated attack where scammers create lookalike addresses to trick users into sending funds to the wrong destination.
**Real Case**: In May 2024, a victim lost \$68 million in WBTC by copying a poisoned address from their transaction history. The legitimate and scam addresses looked nearly identical.
**The Attack Pattern—Can You Spot the Difference?**
| | Address |
| ------------ | -------------------------------------------- |
| ✅ Legitimate | `0xd9A1b0B1e1aE382DbDc898Ea68012FfcB2853a91` |
| ❌ Attacker | `0xd9A1C3788D81257612E2581A6ea0aDa244853a91` |
Both start with `0xd9A1`. Both end with `53a91`. The victim couldn't tell them apart—and lost \$68 million.
```bash cURL theme={null}
curl -X GET "https://api.webacy.com/addresses/0xd9A1C3788D81257612E2581A6ea0aDa244853a91/poisoning?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
```typescript TypeScript theme={null}
const poisoning = await client.addresses.checkPoisoning(
'0xd9A1C3788D81257612E2581A6ea0aDa244853a91',
{ chain: Chain.ETH }
);
if (poisoning.is_poisoned) {
console.log('WARNING: Address poisoning detected!');
console.log(`Similar to: ${poisoning.similar_addresses}`);
}
```
```python Python theme={null}
response = requests.get(
"https://api.webacy.com/addresses/0xd9A1C3788D81257612E2581A6ea0aDa244853a91/poisoning",
params={"chain": "eth"},
headers={"x-api-key": "YOUR_API_KEY"}
)
```
**One API call, millions saved**: Add this check before every withdrawal. Your users won't notice the 300ms latency—but they'll notice when you save them from a \$68M mistake.
### Withdrawal Destination Check
Screen withdrawal destinations for general risk factors.
```typescript theme={null}
async function screenWithdrawal(destination: string, chain: Chain) {
// 1. Sanctions check (immediate block)
const sanctions = await client.addresses.checkSanctioned(destination, { chain });
if (sanctions.is_sanctioned) {
return { allowed: false, reason: 'Sanctioned address' };
}
// 2. Address poisoning check (warn user)
const poisoning = await client.addresses.checkPoisoning(destination, { chain });
if (poisoning.is_poisoned) {
return {
allowed: false,
reason: 'Potential address poisoning attack',
warning: 'Please verify this address carefully'
};
}
// 3. Risk analysis (flag high risk)
const risk = await client.addresses.analyze(destination, { chain });
if (risk.overallRisk >= 50) {
return {
allowed: true,
warning: `High risk destination (score: ${risk.overallRisk})`,
issues: risk.issues
};
}
return { allowed: true };
}
```
***
## Complete Integration Workflow
Here's how it all fits together.
### Recommended Deposit Flow
```mermaid theme={null}
flowchart TD
A[Deposit Received] --> B{Sanctions Check}
B -->|Sanctioned| C[BLOCK Deposit]
B -->|Clear| D{Risk Analysis}
D -->|Score > 80| E["BLOCK + Report"]
D -->|Score 50-80| F[REVIEW Required]
D -->|Score < 50| G[ACCEPT Deposit]
```
### Recommended Withdrawal Flow
```mermaid theme={null}
flowchart TD
A[Withdrawal Request] --> B{Sanctions Check}
B -->|Sanctioned| C[BLOCK Withdrawal]
B -->|Clear| D{Poisoning Check}
D -->|Poisoned| E["WARN User + Require Confirmation"]
D -->|Clear| F{Risk Analysis}
F -->|Score >= 50| G["FLAG + Show Warning"]
F -->|Score < 50| H[Process Withdrawal]
```
### Implementation Example
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// Deposit screening
async function screenDeposit(address: string, chain: Chain) {
// Step 1: Sanctions (must block)
const sanctions = await client.addresses.checkSanctioned(address, { chain });
if (sanctions.is_sanctioned) {
return {
action: 'BLOCK',
reason: 'Sanctioned address',
report: true
};
}
// Step 2: Risk analysis
const risk = await client.addresses.analyze(address, { chain });
if (risk.overallRisk >= 80) {
return {
action: 'BLOCK',
reason: 'Extremely high risk',
riskScore: risk.overallRisk,
issues: risk.issues
};
}
if (risk.overallRisk >= 50) {
return {
action: 'REVIEW',
reason: 'High risk - manual review required',
riskScore: risk.overallRisk,
issues: risk.issues
};
}
return {
action: 'ACCEPT',
riskScore: risk.overallRisk
};
}
// Withdrawal screening
async function screenWithdrawal(destination: string, chain: Chain) {
// Step 1: Sanctions
const sanctions = await client.addresses.checkSanctioned(destination, { chain });
if (sanctions.is_sanctioned) {
return {
action: 'BLOCK',
reason: 'Cannot withdraw to sanctioned address'
};
}
// Step 2: Address poisoning
const poisoning = await client.addresses.checkPoisoning(destination, { chain });
if (poisoning.is_poisoned) {
return {
action: 'WARN',
reason: 'Possible address poisoning attack detected',
requireConfirmation: true,
message: 'Please verify this is the correct address. It appears similar to addresses that have been used in phishing attacks.'
};
}
// Step 3: Risk analysis
const risk = await client.addresses.analyze(destination, { chain });
if (risk.overallRisk >= 50) {
return {
action: 'FLAG',
reason: 'High risk destination',
riskScore: risk.overallRisk,
showWarning: true
};
}
return { action: 'PROCEED' };
}
```
***
## Example Addresses for Testing
Use these addresses to test your integration:
### OFAC Sanctioned Addresses
| Address | Chain | Attribution |
| -------------------------------------------- | ----- | ---------------------------------- |
| `0x098B716B8Aaf21512996dC57EB0615e2383E2f96` | ETH | Lazarus Group (Ronin Bridge heist) |
| `0x566f827a4988d4a3eb9da469d8d3d0b536da196e` | ETH | OFAC SDN List |
| `0x55da7813a4314cc896bf0cf61886529b7769be81` | ETH | OFAC SDN List |
| `bc1qy78e6ml7f3p438jqrrlzsewx625y0sr7jsesa7` | BTC | OpenSanctions |
| `115p7UMMngoj1pMvkpHijcRdfJNXj6LrLn` | BTC | WannaCry Ransomware |
| `1295rkVyNfFpqZpXvKGhDqwhP1jZcNNDMV` | BTC | Suex (OFAC) |
### Known Hackers
| Address | Chain | Attribution |
| -------------------------------------------- | ----- | ----------------------------- |
| `0x3b09A3c9aDD7D0262e6E9724D7e823Cd767a0c74` | ETH | Bittensor Hack |
| `0x7a503e3ab9433ebf13afb4f7f1793c25733b3cca` | ETH | GANA Hack |
| `0xd967113224c354600b3151e27aaba53e3034f372` | ETH | WazirX Malware/Spear Phishing |
| `0x889b49ef0bf787c3ddc2950bfc7d1d439320004b` | ETH | Woo X Exploiter |
| `0x44f887cfbd667cb2042dd55ab1d8951c94bb0102` | ETH | Loopring Guardian 2FA Exploit |
| `bc1ql9r9a4uxmsdwkenjwx7t5clslsf62gxt8ru7e8` | BTC | Trust Hack |
### Mixers & Money Laundering
| Address | Chain | Type |
| -------------------------------------------- | ----- | ----------------------------- |
| `0x722122dF12D4e14e13Ac3b6895a86e84145b6967` | ETH | Tornado Cash Router |
| `0x5614987586c15f4e9b3ebcbec07c477b58f2e59b` | ETH | Tornado Cash Router (Primary) |
| `0x561376c5c8313bd742083d42e6b8b6d8da701fff` | ETH | Tornado Cash Pool (100 ETH) |
### Phishing & Scam Addresses
| Address | Chain | Attribution |
| -------------------------------------------- | ----- | ------------------------------------------- |
| `0x84672cc56b6dad30cfa5f9751d9ccae6c39e29cd` | ETH | AI Protocol User Permit Phishing |
| `0x1aDf5DAc035AE7FEC116e8345e005FB88d542f53` | ETH | Phishing scammer |
| `0xe7d13137923142a0424771e1778865b88752b3c7` | ETH | Mailer Lite/WalletConnect Phishing Campaign |
| `0x624Fc3Dc249E37E8BFd3e834C4dF81Ff2dA1D0Ca` | BSC | Malicious Permit scammer |
### Address Poisoning
| Address | Chain | Type |
| -------------------------------------------- | ----- | ------------------------------------------ |
| `0xd9A1C3788D81257612E2581A6ea0aDa244853a91` | ETH | Known poisoned address (\$68M WBTC attack) |
| `0xCF03Aa88AfDA357C837b9DDD38A678E3Ad7Cd5D7` | ETH | Poisoning victim |
| `0x5f90e59d0a03fd2f8c56b8cc896c5b42594eb3a0` | ETH | \$50M address poisoning drain |
### DPRK-Related (North Korea)
| Address | Chain | Attribution |
| -------------------------------------------- | ----- | --------------------------------- |
| `0x0fa09c3a328792253f8dee7116848723b72a6d2e` | ETH | North Korean entities (High Risk) |
| `0x6eedf92fb92dd68a270c3205e96dccc527728066` | ETH | North Korean entities (High Risk) |
| `0xbdd077f651ebe7f7b3ce16fe5f2b025be2969516` | ETH | North Korean entities (High Risk) |
### Clean Addresses (for comparison)
| Address | Chain | Type |
| -------------------------------------------- | ----- | --------------------------- |
| `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` | ETH | Vitalik's wallet (low risk) |
For a complete list of test addresses, see [Example Addresses](./getting-started/quickstart/example-addresses).
***
## API Quick Reference
| Endpoint | Use Case | Response Time |
| ------------------------------------- | ----------------------- | ------------- |
| `GET /addresses/sanctioned/{address}` | Sanctions screening | \~100ms |
| `GET /addresses/{address}` | Full risk analysis | \~500ms |
| `GET /addresses/{address}/poisoning` | Address poisoning check | \~300ms |
**Authentication:**
```text theme={null}
Header: x-api-key: YOUR_API_KEY
Base URL: https://api.webacy.com
```
***
## Ready to Ship?
You've seen how it works. Now integrate it:
1. **Get your API key** — Takes 2 minutes
2. **Test with the example addresses** — Verify your integration
3. **Go live** — Start screening deposits today
## Next Steps
Start screening in minutes
Every endpoint, every parameter
TypeScript bindings included
Know what you're looking at
# Example Addresses
Source: https://docs.webacy.com/guides/getting-started/quickstart/example-addresses
Example addresses to test our endpoints and services
To help you get started quickly, we provide a small set of example addresses you can use to test our endpoints end-to-end.
These examples are designed to showcase the kinds of signals you’ll see in real usage, including risk flags, behavioral indicators, and other intelligence and exposure. They’re especially helpful for validating integration logic, UI rendering, and decisioning workflows before you run screening on live user activity.
## What these examples are good for
Use these addresses below to:
* **Confirm your integration works** (request/response structure, latency, pagination, error handling)
* **Validate risk outcomes** (flags, severity, labels, and explainability fields)
* **Test decisioning logic** (block, warn, allow, review)
* **Prototype dashboards** (monitoring views, alert feeds, triage workflows)
### Notes
* These examples are provided for **testing and development** only.
* Address risk is **contextual and time-sensitive**. Results may change as new on-chain activity occurs.
* If you’d like a broader sample set (including “clean,” borderline, and mixed-risk examples), [reach out](mailto:info@webacy.co) and we can provide a curated testing bundle.
# Sanctioned Addresses
These addresses are on sanctions lists and will return `is_sanctioned: true` from the `/addresses/sanctioned/{address}` endpoint.
| Address | Chain | Attribution |
| -------------------------------------------- | ----- | ------------------------------------------------ |
| `0x098B716B8Aaf21512996dC57EB0615e2383E2f96` | ETH | Lazarus Group (North Korea) - Ronin Bridge heist |
| `1295rkVyNfFpqZpXvKGhDqwhP1jZcNNDMV` | BTC | Suex - OFAC SDN List |
| `19D8PHBjZH29uS1uPZ4m3sVyqqfF8UFG9o` | BTC | Sanctioned Address |
# Hacker Addresses
These addresses are associated with known hacks and exploits. They return high-risk scores with tags like `hack`, `stealing_attack`, and `blacklist_doubt`.
| Address | Chain | Attribution | Risk Score |
| -------------------------------------------- | ----- | ------------------------------- | ---------- |
| `0x3b09A3c9aDD7D0262e6E9724D7e823Cd767a0c74` | ETH | Bittensor Hack | 100 |
| `0xd967113224c354600b3151e27aaba53e3034f372` | ETH | WazirX Malware / Spear Phishing | 100 |
| `0x44f887cfbd667cb2042dd55ab1d8951c94bb0102` | ETH | Loopring Guardian 2FA Exploit | 10 |
| `0x889b49ef0bf787c3ddc2950bfc7d1d439320004b` | ETH | Woo X Exploiter | 3.1 |
# DPRK (North Korea) Linked
These addresses are associated with North Korean cyber operations and return the `dprk` tag.
| Address | Chain | Risk Score | Tags |
| -------------------------------------------- | ----- | ---------- | ---------------------------- |
| `0x0fa09c3a328792253f8dee7116848723b72a6d2e` | ETH | 100 | dprk, hack, stealing\_attack |
# Address Poisoning
These addresses are involved in address poisoning attacks. The `/addresses/{address}/poisoning` endpoint will return `poisoning_detected: true` for attackers.
| Address | Chain | Type | Notes |
| -------------------------------------------- | ----- | -------- | --------------------------------------------------------------- |
| `0x70c5698da7f86487837f59642b1ebe5682dfa3c7` | ETH | Attacker | Returns `poisoning_detected: true` with suspicious transactions |
| `0xCF03Aa88AfDA357C837b9DDD38A678E3Ad7Cd5D7` | ETH | Victim | Address was targeted by a poisoning attempt |
# Phishing Addresses
These addresses are associated with phishing campaigns and return the `phishing_activities` tag.
| Address | Chain | Attribution | Risk Score |
| -------------------------------------------- | ----- | ----------------------------- | ---------- |
| `0x1aDf5DAc035AE7FEC116e8345e005FB88d542f53` | ETH | ScamSniffer reported phishing | 23 |
| `0x5f90e59d0a03fd2f8c56b8cc896c5b42594eb3a0` | ETH | \$50M Address Poisoning Drain | 20.1 |
# Mixers
These addresses are associated with mixing services and return tags like `associated_mixer` and `sanctioned`.
| Address | Chain | Attribution | Risk Score |
| -------------------------------------------- | ----- | ------------------- | ---------- |
| `0x722122dF12D4e14e13Ac3b6895a86e84145b6967` | ETH | Tornado Cash Router | 10.1 |
# Pool Analysis Examples
[Pool Analysis](../../../api-reference/pool-analysis/get-pool-ohlcv-data-with-risk-assessment) examples:
| Address | Chain | Pool |
| -------------------------------------------- | ----- | ------------ |
| `V79vihUymP25ypDCRVmED106MvTI3AfPajSqWJ1M` | SOL | - |
| `0x397ff1542f962076d0bfe58ea045ffa2d347aca0` | ETH | Sushiswap v2 |
| `0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc` | ETH | Uniswap v2 |
# Other Examples
| Address | Chain | Type |
| ---------------------------------------------- | ----- | --------------------------------------------- |
| `7gGRg15D2vGbeqwp5J5bQatAFVSrG6doNx2V3i8aVYEv` | SOL | Automated Trader Account |
| `23JPm15PgYWV5uTnjADEVN8uSma2rdcULq3EGciTArzS` | SOL | Upbit Hack Related Wallet |
| `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` | ETH | Vitalik Buterin (clean wallet for comparison) |
# Webacy DD APIs
Source: https://docs.webacy.com/index
Enterprise-grade blockchain risk intelligence
The Webacy DD APIs are an enterprise-grade, real-time blockchain transaction, wallet, token, address, smart contract, and customer-level risk system.
Sign up for API access to start building
Reach out for enterprise plans and support
**Want a Sandbox UI?** Check out [DD.xyz](https://dd.xyz), which uses all of our APIs. Note that not all functionalities available through our APIs are available on the DD.xyz app.
## Get Started
Get your API key and make your first request in minutes
## API Reference
Complete endpoint reference with interactive examples
Learn how to authenticate your API requests
Risk due diligence for addresses, tokens, and contracts
Trading-focused analysis and pool data
## What Can You Do?
Analyze wallets for threats, sanctions, and malicious activity
Get comprehensive security and market analysis for any token
Detect vulnerabilities and risks in smart contracts
Preview transaction risks before users sign
Screen addresses against OFAC and global sanction lists
Detect snipers, whale concentration, and holder risks
## Explore the Docs
Full endpoint documentation
12 blockchain networks
14 analysis modules
## What's Next
Learn how to authenticate your API requests
# Agent Reference
Source: https://docs.webacy.com/integrations/agent-reference
Self-contained API reference for AI coding agents — everything needed to generate correct Webacy API code
This page is a dense, self-contained reference designed for AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.). Copy this into your `CLAUDE.md`, `.cursorrules`, or agent system prompt so the AI can generate correct Webacy API integration code without additional lookups.
## Setup
### Claude Code
Add to your project's `CLAUDE.md`:
```markdown theme={null}
## Webacy API
See the full agent reference at: https://docs.webacy.com/integrations/agent-reference
```
Or paste the content of this page directly into `CLAUDE.md` for offline access.
### Cursor
Add to your `.cursorrules` file:
```text theme={null}
When working with the Webacy API, refer to: https://docs.webacy.com/integrations/agent-reference
```
Or add `https://docs.webacy.com` as a doc source in Cursor Settings > Features > Docs.
### Other Agents
Include this page's content in any system prompt, context window, or retrieval source your agent uses.
***
## Authentication & Base URL
```text theme={null}
Base URL: https://api.webacy.com
Auth Header: x-api-key: YOUR_API_KEY
```
All requests require the `x-api-key` header. Get a key at [developers.webacy.co](https://developers.webacy.co/).
```bash theme={null}
curl -X GET "https://api.webacy.com/addresses/{address}?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
***
## Endpoint Reference
### Risk DD Endpoints
| Method | Path | Description | Chains |
| ------ | -------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET` | `/addresses/{address}` | Threat risks for any address (wallet, token, or contract) | `eth` `pol` `opt` `arb` `base` `bsc` `sol` `ton` `sei` `sui` `stellar` `hedera` `btc` |
| `GET` | `/contracts/{contractAddress}` | Real-time smart contract risk analysis | `eth` `pol` `opt` `arb` `base` `bsc` |
| `GET` | `/contracts/{contractAddress}/code-analysis` | Detailed contract code analysis | `eth` `pol` `opt` `arb` `base` `bsc` |
| `GET` | `/contracts/{contractAddress}/source-code` | Contract source code retrieval | `eth` `pol` `opt` `arb` `base` `bsc` |
| `GET` | `/tokens/{tokenAddress}` | Comprehensive token risk analysis | `eth` `base` `bsc` `pol` `opt` `arb` `sol` `ton` `sei` `sui` `btc` |
| `GET` | `/holder-analysis/{address}` | Token holder distribution and sniper detection | `eth` `pol` `opt` `arb` `base` `bsc` `sol` `stellar` `sui` `hedera` |
| `POST` | `/url` | Analyze a URL for phishing/malware risks | All (not chain-specific) |
| `GET` | `/transactions/{txHash}` | Risk details for a completed transaction | `eth` `base` `bsc` `pol` `opt` `sol` `arb` `stellar` `hedera` |
| `GET` | `/addresses/sanctioned/{walletAddress}` | Check address against OFAC sanction lists | `eth` `pol` `opt` `arb` `base` `bsc` `sol` `ton` `sei` `sui` `stellar` `btc` |
| `GET` | `/addresses/{address}/poisoning` | Detect address poisoning attacks | `eth` `pol` `opt` `arb` `base` `bsc` |
| `GET` | `/addresses/{address}/approvals` | Analyze token approval risks | `eth` `pol` `opt` `arb` `base` `bsc` |
| `GET` | `/contracts/taxes/{tokenAddress}` | Get buy/sell tax percentages for a token | All chains |
| `GET` | `/contracts/tokens/recommendations` | Get recommended high-quality tokens | All (optional chain filter) |
| `GET` | `/contracts/tokens/by-risk-level` | Get tokens filtered by risk level (low/high) | All (optional chain filter) |
| `GET` | `/contracts/symbol/{symbol}` | Look up token risk data by ticker symbol | All (optional chain filter) |
| `POST` | `/addresses/multisender` | Batch detect multisender/disperser contracts | All chains |
| `POST` | `/batch/transactions` | Batch analyze up to 500 transactions | All chains |
| `GET` | `/audits/{address}` | Get smart contract audit data (via Trustblock) | All chains |
| `GET` | `/mica-report/{symbol}` | Get MiCA compliance report for a token | Not chain-specific |
### Trading DD Endpoints
| Method | Path | Description | Chains |
| ------ | ---------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
| `GET` | `/trading-lite/{address}` | Lightweight trading risk assessment | `sol` |
| `GET` | `/tokens/{tokenAddress}/pools` | Get liquidity pools for a token | `eth` `base` `bsc` `pol` `opt` `arb` `sol` `ton` `sei` `sui` `btc` |
| `GET` | `/tokens/pools/{poolAddress}` | Get specific pool data | `eth` `base` `bsc` `pol` `opt` `arb` `sol` `ton` `sei` `sui` `btc` |
| `GET` | `/tokens/trending` | Get trending tokens | `eth` `base` `bsc` `pol` `opt` `arb` `sol` `ton` `sei` `sui` `btc` |
| `GET` | `/tokens/pools/trending` | Get trending liquidity pools | `eth` `base` `bsc` `pol` `opt` `arb` `sol` `ton` `sei` `sui` `btc` |
| `POST` | `/scan/{fromAddress}/transactions` | Simulate and scan a transaction before signing | `eth` `pol` `opt` `arb` `base` `bsc` |
| `POST` | `/scan/{fromAddress}/eip712` | Scan EIP-712 typed data signing requests | `eth` |
### Utility Endpoints
| Method | Path | Description |
| ------ | ---------------- | -------------------------------- |
| `GET` | `/usage` | Get API usage for a date range |
| `GET` | `/usage/current` | Get current billing period usage |
| `GET` | `/usage/max-rps` | Get max requests per second |
***
## Chain Reference
| Blockchain | Identifier | Address Format |
| ---------- | ---------- | --------------------------------------------- |
| Ethereum | `eth` | `0x...` (42 chars) |
| Polygon | `pol` | `0x...` (42 chars) |
| Optimism | `opt` | `0x...` (42 chars) |
| Arbitrum | `arb` | `0x...` (42 chars) |
| Base | `base` | `0x...` (42 chars) |
| BSC | `bsc` | `0x...` (42 chars) |
| Solana | `sol` | Base58 (32-44 chars) |
| TON | `ton` | `EQ...` or `UQ...` |
| Sei | `sei` | `sei1...` or `0x...` |
| Sui | `sui` | `0x...` (66 chars) |
| Stellar | `stellar` | `G...` (56 chars) or `CODE:ISSUER` for tokens |
| Hedera | `hedera` | `0.0.X` (native) or `0x...` (EVM) |
| Bitcoin | `btc` | `bc1...`, `1...`, or `3...` |
Default chain when omitted: `eth`.
***
## Response Shapes
### Address Risk (`GET /addresses/{address}`)
```json theme={null}
{
"count": 1,
"medium": 0,
"high": 0,
"overallRisk": 25.99,
"issues": [
{
"key": "risk_tag_key",
"name": "Risk Tag Name",
"description": "Description of the risk",
"severity": "low"
}
],
"isContract": false
}
```
* `overallRisk`: 0-100 score (higher = riskier)
* `count`: Total number of risk issues found
* `medium` / `high`: Count of medium/high severity issues
Additional fields may be present including `addressType`, `details`, `context`, `deployer`, `holder_analysis`, and others. The fields shown above are the core risk assessment fields.
### Token Risk (`GET /tokens/{tokenAddress}`)
```json theme={null}
{
"metrics": {
"current_price": 1.25,
"market_cap": 500000000,
"total_volume": 1000000,
"date": "2025-01-15"
},
"risk": {
"count": 2,
"medium": 1,
"high": 0,
"overallRisk": 42.5,
"issues": [],
"isContract": true
},
"metadata": {
"name": "Token Name",
"symbol": "TKN",
"contract_address": "0x...",
"chain": "eth",
"decimals": 18,
"categories": ["defi"]
}
}
```
Access the risk score via `data.risk.overallRisk`. Risk data is nested under the `risk` key, not at the top level.
### Holder Analysis (`GET /holder-analysis/{address}`)
```json theme={null}
{
"token_address": "0x...",
"total_holders_count": 1500,
"first_buyers_analysis": { },
"top_10_holders_analysis": { },
"sniper_analysis": { },
"activity_patterns": { },
"metadata": { }
}
```
Sub-objects vary by chain. For example, `sniper_analysis` is excluded for Hedera, and `activity_patterns` is EVM-only.
### Transaction Scan (`POST /scan/{fromAddress}/transactions`)
Request body:
```json theme={null}
{
"to": "0xContractAddress",
"data": "0xCalldata",
"value": "1000000000000000000",
"chain": "eth"
}
```
Response:
```json theme={null}
{
"public_key_id": "...",
"descriptor": "...",
"block": 12345678,
"simulation": { },
"timestamp": "2025-01-15T10:30:00Z",
"chain": "eth"
}
```
The `simulation` object is opaque and varies by transaction type.
### Sanction Check (`GET /addresses/sanctioned/{walletAddress}`)
```json theme={null}
{
"address": "0x...",
"is_sanctioned": false
}
```
### URL Risk (`POST /url`)
Request body:
```json theme={null}
{
"url": "https://example.com"
}
```
Response:
```json theme={null}
{
"riskLevel": "low",
"description": "URL is whitelisted as safe",
"message": "..."
}
```
`riskLevel` values: `"high"`, `"medium"`, `"low"`, `"unknown"`.
***
## Common Workflows
### Wallet Risk Screening
Screen a wallet address before allowing a deposit, withdrawal, or interaction.
```javascript theme={null}
const response = await fetch(
`https://api.webacy.com/addresses/${walletAddress}?chain=eth`,
{ headers: { "x-api-key": API_KEY } }
);
const data = await response.json();
if (data.overallRisk > 70) {
console.log("HIGH RISK — block or flag for review");
} else if (data.overallRisk > 40) {
console.log("MEDIUM RISK — enhanced monitoring");
} else {
console.log("LOW RISK — proceed");
}
```
### Token Due Diligence
Evaluate a token before listing or trading.
```javascript theme={null}
// 1. Token risk analysis
const tokenRisk = await fetch(
`https://api.webacy.com/tokens/${tokenAddress}?chain=eth`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
// 2. Holder concentration check
const holders = await fetch(
`https://api.webacy.com/holder-analysis/${tokenAddress}?chain=eth`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
// 3. Contract security check
const contract = await fetch(
`https://api.webacy.com/contracts/${tokenAddress}?chain=eth`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
```
### Pre-Trade Risk Check
Fast risk assessment before executing a trade (optimized for Solana trading bots).
```javascript theme={null}
// Quick risk check
const risk = await fetch(
`https://api.webacy.com/trading-lite/${tokenAddress}?chain=sol`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
if (risk.overallRisk > 70) return; // Skip risky tokens
// Check liquidity
const pools = await fetch(
`https://api.webacy.com/tokens/${tokenAddress}/pools?chain=sol`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
```
### Compliance Screening
Check addresses against sanctions lists for regulatory compliance.
```javascript theme={null}
// Sanction check
const sanction = await fetch(
`https://api.webacy.com/addresses/sanctioned/${walletAddress}?chain=eth`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
if (sanction.is_sanctioned) {
console.log("SANCTIONED — do not process");
return;
}
// Full threat analysis for additional compliance context
const threats = await fetch(
`https://api.webacy.com/addresses/${walletAddress}?chain=eth`,
{ headers: { "x-api-key": API_KEY } }
).then(r => r.json());
```
### Transaction Simulation
Simulate a transaction to preview risks before the user signs.
```javascript theme={null}
const simulation = await fetch(
`https://api.webacy.com/scan/${fromAddress}/transactions`,
{
method: "POST",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
to: contractAddress,
data: calldata,
value: "0",
chain: "eth"
})
}
).then(r => r.json());
```
***
## Error Handling
| Status Code | Meaning | Action |
| ----------- | ---------------------------- | ------------------------------------------------ |
| `200` | Success | Parse response body |
| `400` | Bad request (invalid params) | Check address format and chain parameter |
| `401` | Unauthorized | Check `x-api-key` header |
| `403` | Forbidden | API key lacks permissions for this endpoint |
| `404` | Not found | Address/transaction not found on specified chain |
| `429` | Rate limit exceeded | Back off and retry with exponential delay |
| `500` | Server error | Retry after a short delay |
Error response format:
```json theme={null}
{
"message": "Error description"
}
```
***
## Query Parameters
Common parameters across endpoints:
| Parameter | Type | Description |
| ------------------ | --------- | -------------------------------------------------------------------------------- |
| `chain` | string | Blockchain identifier (e.g., `eth`, `sol`). Defaults to `eth` |
| `show_low_risk` | boolean | Include low-risk issues in response. Default: `true` |
| `hide_trust_flags` | boolean | Hide trust-related flags from response |
| `modules` | string\[] | Comma-separated risk modules to execute (e.g., `token_security,fraud_detection`) |
Available risk modules: `source_code_analysis`, `governance_analysis`, `token_security`, `contract_analysis`, `market_data`, `holder_analysis`, `liquidity_analysis`, `fraud_detection`, `sanctions_compliance`, `mixer_detection`, `address_behavior`, `transaction_analysis`, `reputation_analysis`, `solana_specific`, `evm_specific`, `ton_specific`, `sui_specific`, `basic_info`, `security_essentials`, `fund_flow_screening`, `developer_migration`.
***
## Rules for AI Agents
### ALWAYS
* Include the `x-api-key` header on every request
* Include the `chain` query parameter — do not rely on the default
* Store API keys in environment variables, never hardcoded
* Validate address format matches the target chain before calling
* Handle rate limiting with exponential backoff
### NEVER
* Expose API keys in client-side code, logs, or version control
* Use the development URL (`api-development.webacy.com`) in production code
* Assume all endpoints support all chains — check the endpoint reference table
* Ignore the `overallRisk` score — always check it before proceeding
### ASK FIRST
* Before choosing between Risk DD and Trading DD endpoints, ask what the use case is
* Before selecting specific `modules`, ask if the user wants full analysis or filtered results
* Before implementing retry logic, ask about the user's rate limit tier
# Build with AI
Source: https://docs.webacy.com/integrations/build-with-ai
All the ways to use AI tools with Webacy's blockchain risk API and documentation
Webacy documentation is designed to be AI-native. Whether you're building autonomous agents, using AI coding assistants, or feeding context into LLMs, there are multiple ways to access Webacy's API documentation programmatically.
## Complete Documentation for LLMs
Webacy publishes a plain-text version of the entire documentation site, optimized for LLM consumption and RAG systems.
| File | Description |
| -------------------------------------------------------- | ----------------------------------------------------------- |
| [`llms.txt`](https://docs.webacy.com/llms.txt) | Lightweight index of all pages with titles and descriptions |
| [`llms-full.txt`](https://docs.webacy.com/llms-full.txt) | Full text of every documentation page in a single file |
Use `llms-full.txt` to:
* Build RAG pipelines that answer questions about Webacy's API
* Seed AI agents with complete API knowledge
* Create custom chatbots for your team's integration workflow
```bash theme={null}
# Download the full docs for your RAG system
curl -o webacy-docs.txt https://docs.webacy.com/llms-full.txt
```
## Per-Page AI Access
Every documentation page has built-in AI options. Click the contextual menu on any page to:
* **Copy** the page content as markdown
* **Open in Claude** to discuss the page with Claude
* **Open in ChatGPT** to discuss the page with ChatGPT
* **Open in Cursor** to use the page as context in Cursor
You can also append `.md` to any page URL to get the raw markdown content. For example:
```text theme={null}
https://docs.webacy.com/api-reference/introduction.md
```
## OpenAPI Specification
The full OpenAPI 3.0 spec is published at:
```text theme={null}
https://docs.webacy.com/openapi.json
```
Feed this to AI tools for automatic code generation, SDK creation, or API client scaffolding:
```bash theme={null}
# Generate a TypeScript client with an AI coding assistant
# Provide the spec as context:
curl -o webacy-openapi.json https://docs.webacy.com/openapi.json
```
## Cursor Integration
Add Webacy docs as a documentation source in Cursor for inline context while coding.
**Step 1:** Open Cursor Settings > Features > Docs
**Step 2:** Click "Add new doc" and enter:
```text theme={null}
https://docs.webacy.com
```
**Step 3:** Use `@Docs` in Cursor chat to reference Webacy documentation:
```text theme={null}
@Docs How do I check if a wallet is sanctioned using the Webacy API?
```
You can also add the [Agent Reference](/integrations/agent-reference) page directly to your project's `.cursorrules` file for persistent context.
## Claude Code / CLAUDE.md
For projects using [Claude Code](https://docs.anthropic.com/en/docs/claude-code), add the Agent Reference to your `CLAUDE.md` file so Claude always has Webacy API context:
```bash theme={null}
# Download the agent reference and append to your CLAUDE.md
echo "\n## Webacy API Reference\nSee: https://docs.webacy.com/integrations/agent-reference\n" >> CLAUDE.md
```
Or copy the content from the [Agent Reference](/integrations/agent-reference) page directly into your `CLAUDE.md` for offline access.
## MCP Server
For the deepest AI integration, connect your AI coding assistant directly to Webacy's API using the Model Context Protocol (MCP). This lets tools like Claude Code and Cursor query live blockchain risk data without leaving your editor.
Connect Claude Code or Cursor to Webacy's live risk analysis tools
## AI Search
The documentation site includes built-in AI-powered search. Use the search bar on any page to ask natural language questions about the API, and get AI-generated answers grounded in the documentation.
## Quick Reference
| Method | Best For |
| ------------------------------------------------------ | --------------------------------------------- |
| [llms-full.txt](https://docs.webacy.com/llms-full.txt) | RAG systems, bulk ingestion, agent training |
| [Agent Reference](/integrations/agent-reference) | AI coding assistants, CLAUDE.md, .cursorrules |
| [MCP Server](/integrations/mcp-server) | Live data queries from your editor |
| [OpenAPI spec](https://docs.webacy.com/openapi.json) | Code generation, SDK scaffolding |
| Per-page AI buttons | Ad-hoc questions about specific pages |
| AI Search | Quick natural language lookups |
# MCP Server
Source: https://docs.webacy.com/integrations/mcp-server
Connect your AI coding assistant to Webacy's blockchain risk analysis tools
The Webacy API exposes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI coding assistants like Claude Code and Cursor query blockchain risk data directly from your development environment.
Instead of switching to a browser or writing API calls manually, you can ask your AI assistant questions like *"Analyze the risk of 0x742d..."* and get real-time results inline.
## Prerequisites
* An API key from [developers.webacy.co](https://developers.webacy.co/)
Keep your API key secret. Never commit it to version control.
## Installation
### Claude Code
Add the Webacy MCP server using the CLI:
```bash theme={null}
claude mcp add webacy-mcp --transport http https://api.webacy.com/mcp --header "x-api-key: YOUR_API_KEY"
```
Or add it manually to your `.claude/mcp.json` file:
```json theme={null}
{
"mcpServers": {
"webacy-mcp": {
"type": "http",
"url": "https://api.webacy.com/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}
```
### Cursor
Open Cursor Settings and navigate to **MCP Servers**. Click **Add Server** and configure:
```json theme={null}
{
"mcpServers": {
"webacy-mcp": {
"url": "https://api.webacy.com/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}
```
### Other MCP Clients
Any MCP client that supports HTTP Streamable transport can connect to the Webacy MCP server. Use the following configuration:
| Setting | Value |
| --------------- | ---------------------------- |
| **URL** | `https://api.webacy.com/mcp` |
| **Transport** | HTTP Streamable |
| **Auth Header** | `x-api-key: YOUR_API_KEY` |
## Available Tools
The MCP server exposes three tools for blockchain risk analysis:
### `get_address_risk`
Analyze the risk profile of a blockchain address (wallet or contract). Returns risk score, risk factors, and detailed security analysis.
| Parameter | Type | Required | Description |
| ------------------- | --------- | -------- | ---------------------------------------------- |
| `address` | string | Yes | The blockchain address to analyze |
| `chain` | string | Yes | Blockchain network (e.g. `eth`, `sol`, `base`) |
| `detailed_response` | boolean | No | Include detailed risk factor breakdowns |
| `show_low_risk` | boolean | No | Include low-risk factors in the response |
| `modules` | string\[] | No | Specific risk analysis modules to run |
### `get_token_risk`
Analyze the risk profile of a token contract. Returns token security flags, market data, and economic risk indicators.
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | ----------------------------------------------- |
| `address` | string | Yes | The token contract address to analyze |
| `chain` | string | Yes | Blockchain network (e.g. `eth`, `sol`, `base`) |
| `metrics_date` | string | No | Date for historical metrics (DD-MM-YYYY format) |
| `modules` | string\[] | No | Specific risk analysis modules to run |
### `get_holder_analysis`
Analyze the holder distribution and concentration of a token. Returns top holders, holder counts, and distribution metrics.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ------------------------------------------------ |
| `address` | string | Yes | The token contract address to analyze |
| `chain` | string | No | Blockchain network (defaults to `sol`) |
| `disable_refetch` | boolean | No | Skip re-fetching data and use existing data only |
| `refresh_cache` | boolean | No | Force refresh cached holder data |
## Supported Chains
The `chain` parameter accepts: `eth`, `sol`, `arb`, `pol`, `opt`, `base`, `bsc`, `ton`, `sui`, `stellar`, `btc`, `sei`.
See [Supported Blockchains](/essentials/supported-blockchains) for full details on each chain.
## Example Usage
Once configured, you can query Webacy risk data directly from your AI assistant:
```text theme={null}
You: Analyze the risk of 0x742d35Cc6634C0532925a3b844Bc454e4438f44e on Ethereum
Claude: I'll check the risk profile using the Webacy MCP tools...
The address has an overall risk score of 25.99/100 (low risk).
No high-severity issues were found. The address is an EOA (not a contract).
```
You can also analyze tokens and holder distributions:
```text theme={null}
You: What's the token risk for USDC on Ethereum (0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)?
You: Show me the holder analysis for this Solana token: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
```
## Next Steps
Explore all available endpoints
Use the TypeScript SDK for programmatic access
Understand how to interpret risk scores
# Quickstart
Source: https://docs.webacy.com/quickstart
Get started with the Webacy API in minutes
## Prerequisites
Before you begin, ensure you have:
* An API key from [developers.webacy.co](https://developers.webacy.co/)
## Step 1: Get Your API Key
1. Visit [developers.webacy.co](https://developers.webacy.co/) to sign up
2. Generate your API key
3. Copy and securely store your API key
Keep your API key secret. Never expose it in client-side code or public repositories.
## Step 2: Make Your First Request
Check the risk score of any blockchain address:
```bash cURL theme={null}
curl -X GET "https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e?chain=eth" \
-H "x-api-key: YOUR_API_KEY"
```
```javascript JavaScript theme={null}
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 Python theme={null}
import requests
response = requests.get(
'https://api.webacy.com/addresses/0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
params={'chain': 'eth'},
headers={'x-api-key': 'YOUR_API_KEY'}
)
print(response.json())
```
## Step 3: Understand the Response
```json theme={null}
{
"count": 1,
"medium": 0,
"high": 0,
"overallRisk": 25.99,
"issues": [],
"isContract": false
}
```
| Field | Description |
| ------------- | ---------------------------------------- |
| `overallRisk` | Risk score from 0-100 (higher = riskier) |
| `count` | Total number of risk factors found |
| `medium` | Count of medium-severity issues |
| `high` | Count of high-severity issues |
| `issues` | Array of specific risk details |
| `isContract` | Whether the address is a smart contract |
See [Risk Levels](/essentials/risk-levels) for how to interpret the `overallRisk` score.
## Common Use Cases
Check if an address is associated with scams, hacks, or sanctions
Get comprehensive security analysis for any token
Detect vulnerabilities in smart contracts
Preview transaction risks before signing
## Next Steps
Explore all available endpoints
See all 12 supported blockchains
Understand our 14 risk analysis modules
Check API limits and quotas
# Chains
Source: https://docs.webacy.com/sdk/chains
Supported blockchain networks in the SDK
Use the `Chain` enum to specify which blockchain you want to analyze. The SDK provides type-safe chain identifiers for all supported networks.
## Chain Enum
```typescript theme={null}
import { Chain } from '@webacy-xyz/sdk';
// Use in API calls
const result = await client.addresses.analyze('0x...', {
chain: Chain.ETH,
});
```
## Supported Chains
| Chain | Enum Value | API Value | Type |
| ----------------- | --------------- | --------- | ------- |
| Ethereum | `Chain.ETH` | `eth` | EVM |
| Solana | `Chain.SOL` | `sol` | Solana |
| Base | `Chain.BASE` | `base` | EVM |
| BNB Smart Chain | `Chain.BSC` | `bsc` | EVM |
| Polygon | `Chain.POL` | `pol` | EVM |
| Arbitrum | `Chain.ARB` | `arb` | EVM |
| Optimism | `Chain.OPT` | `opt` | EVM |
| TON | `Chain.TON` | `ton` | TON |
| Sui | `Chain.SUI` | `sui` | Sui |
| Stellar | `Chain.STELLAR` | `stellar` | Stellar |
| Bitcoin | `Chain.BTC` | `btc` | Bitcoin |
| Sei | `Chain.SEI` | `sei` | Sei |
| Hedera | `Chain.HEDERA` | `hedera` | Hedera |
| Sepolia (Testnet) | `Chain.SEP` | `sep` | EVM |
## Default Chain
Set a default chain to avoid specifying it on every request.
**Prerequisites:**
* SDK installed (`npm install @webacy-xyz/sdk`)
* API key available (from your Webacy dashboard)
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// No need to specify chain - uses ETH
const result = await client.addresses.analyze('0x742d35Cc...');
// Override for a specific request
const solResult = await client.addresses.analyze('So1ana...', {
chain: Chain.SOL,
});
```
## Chain Compatibility
The SDK provides utilities to check chain compatibility:
```typescript theme={null}
import { Chain, isEvmChain, getChainCompatibility, ChainCompatibility } from '@webacy-xyz/sdk';
// Check if chain is EVM-compatible
isEvmChain(Chain.ETH); // true
isEvmChain(Chain.SOL); // false
// Get compatibility group
getChainCompatibility(Chain.ETH); // ChainCompatibility.EVM
getChainCompatibility(Chain.SOL); // ChainCompatibility.SOLANA
getChainCompatibility(Chain.TON); // ChainCompatibility.TON
```
### Compatibility Groups
| Group | Chains |
| --------- | ---------------------------------- |
| `EVM` | ETH, SEP, ARB, POL, OPT, BASE, BSC |
| `SOLANA` | SOL |
| `TON` | TON |
| `BTC` | BTC |
| `SEI` | SEI |
| `SUI` | SUI |
| `STELLAR` | STELLAR |
| `HEDERA` | HEDERA |
## Chain IDs
For EVM chains, you can access the chain ID:
```typescript theme={null}
import { CHAIN_IDS, Chain } from '@webacy-xyz/sdk';
CHAIN_IDS[Chain.ETH]; // 1
CHAIN_IDS[Chain.BSC]; // 56
CHAIN_IDS[Chain.POL]; // 137
CHAIN_IDS[Chain.OPT]; // 10
CHAIN_IDS[Chain.ARB]; // 42161
CHAIN_IDS[Chain.BASE]; // 8453
```
## Chain Names
Get human-readable chain names:
```typescript theme={null}
import { CHAIN_NAMES, Chain } from '@webacy-xyz/sdk';
CHAIN_NAMES[Chain.ETH]; // "Ethereum"
CHAIN_NAMES[Chain.SOL]; // "Solana"
CHAIN_NAMES[Chain.BSC]; // "BNB Smart Chain"
CHAIN_NAMES[Chain.STELLAR]; // "Stellar"
```
## Address Validation
The SDK automatically validates addresses for the specified chain:
```typescript theme={null}
// Valid Ethereum address
await client.addresses.analyze('0x742d35Cc6634C0532925a3b844Bc454e4438f44e', {
chain: Chain.ETH,
});
// Valid Solana address
await client.addresses.analyze('So11111111111111111111111111111111111111112', {
chain: Chain.SOL,
});
// Invalid address throws ValidationError
try {
await client.addresses.analyze('invalid', { chain: Chain.ETH });
} catch (error) {
// ValidationError: Invalid Ethereum address format
}
```
### Address Formats
| Chain Type | Format | Example |
| ---------- | -------------------------- | ---------------------------------------------------------- |
| EVM | 42-char hex with 0x prefix | `0x742d35Cc6634C0532925a3b844Bc454e4438f44e` |
| Solana | Base58, 32-44 chars | `So11111111111111111111111111111111111111112` |
| Bitcoin | Various formats | `bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq` |
| TON | Base64 or raw | `EQBvW8Z5huBkMJYdnfAEM5JqTNLuuFU8cAF7P2CvbXj8-E-t` |
| Stellar | 56-char starting with G | `GCKV3Z7HN3WUT2WIOUM4SMAS5DN3X5LWQ6FQXVH7ZRMWKFU4Z5IPQWWN` |
| Hedera | Native `0.0.X` or EVM hex | `0.0.1234567` |
| Sui | 66-char hex with 0x prefix | `0x7d2f...` |
| Sei | Bech32 with sei prefix | `sei1...` |
## Endpoint Availability
Not all endpoints support all chains. See the [API Reference](../api-reference/introduction) for endpoint-specific chain support.
Complete chain support matrix with endpoint availability
# Error Handling
Source: https://docs.webacy.com/sdk/error-handling
Handle SDK errors gracefully
You can handle errors gracefully using the SDK's structured error classes. All errors extend the base `WebacyError` class, making it easy to catch and respond to different failure scenarios.
## Error Classes
```typescript theme={null}
import {
WebacyError,
AuthenticationError,
ValidationError,
RateLimitError,
NotFoundError,
NetworkError,
} from '@webacy-xyz/sdk';
```
| Error | HTTP Status | Description |
| --------------------- | ----------- | --------------------------- |
| `AuthenticationError` | 401 | Invalid or missing API key |
| `ValidationError` | 400 | Invalid input parameters |
| `RateLimitError` | 429 | Rate limit exceeded |
| `NotFoundError` | 404 | Resource not found |
| `NetworkError` | - | Network connectivity issues |
| `WebacyError` | Various | Base class for all errors |
## Basic Error Handling
```typescript theme={null}
import { ThreatClient, ValidationError, RateLimitError } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: process.env.WEBACY_API_KEY });
try {
const result = await client.addresses.analyze('0x...');
} catch (error) {
if (error instanceof ValidationError) {
console.error('Invalid input:', error.message);
} else if (error instanceof RateLimitError) {
console.error('Rate limited, retry later');
} else {
console.error('Unexpected error:', error);
}
}
```
***
## Error Properties
All SDK errors include these properties:
```typescript theme={null}
try {
await client.addresses.analyze('invalid-address');
} catch (error) {
if (error instanceof WebacyError) {
console.log(error.message); // Human-readable message
console.log(error.code); // Programmatic error code
console.log(error.status); // HTTP status code (if applicable)
console.log(error.requestId); // Request ID for support
console.log(error.endpoint); // Failed endpoint
console.log(error.cause); // Original error (if wrapped)
}
}
```
### Recovery Suggestions
Errors provide recovery suggestions:
```typescript theme={null}
try {
await client.addresses.analyze('invalid');
} catch (error) {
if (error instanceof WebacyError) {
const suggestion = error.getRecoverySuggestion();
if (suggestion) {
console.log('How to fix:', suggestion);
}
}
}
```
***
## Specific Error Types
### AuthenticationError
Thrown when the API key is invalid or missing.
```typescript theme={null}
import { ThreatClient, AuthenticationError } from '@webacy-xyz/sdk';
try {
const client = new ThreatClient({ apiKey: 'invalid-key' });
await client.addresses.analyze('0x...');
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
// Prompt user to check their API key
}
}
```
### ValidationError
Thrown when input parameters are invalid.
```typescript theme={null}
import { ThreatClient, Chain, ValidationError } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: 'your-api-key' });
try {
await client.addresses.analyze('not-an-address', { chain: Chain.ETH });
} catch (error) {
if (error instanceof ValidationError) {
console.error('Validation failed:', error.message);
console.log('Fix:', error.getRecoverySuggestion());
// "Ensure the address is a valid Ethereum address (0x followed by 40 hex characters)"
}
}
```
### RateLimitError
Thrown when you exceed API rate limits. The SDK automatically retries rate-limited requests with exponential backoff.
```typescript theme={null}
import { ThreatClient, RateLimitError } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: 'your-api-key' });
try {
await client.addresses.analyze('0x...');
} catch (error) {
if (error instanceof RateLimitError) {
console.error('Rate limited');
if (error.retryAfter) {
console.log(`Retry after ${error.retryAfter} seconds`);
}
if (error.resetAt) {
const resetDate = new Date(error.resetAt * 1000);
console.log(`Limit resets at ${resetDate.toISOString()}`);
}
}
}
```
### NotFoundError
Thrown when the requested resource doesn't exist.
```typescript theme={null}
import { ThreatClient, NotFoundError } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: 'your-api-key' });
try {
await client.contracts.analyze('0xNonExistentContract...');
} catch (error) {
if (error instanceof NotFoundError) {
console.error('Contract not found');
}
}
```
### NetworkError
Thrown when there are network connectivity issues.
```typescript theme={null}
import { ThreatClient, NetworkError } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: 'your-api-key' });
try {
await client.addresses.analyze('0x...');
} catch (error) {
if (error instanceof NetworkError) {
console.error('Network error:', error.message);
// Retry or notify user of connectivity issues
}
}
```
***
## Retryable Errors
Check if an error can be retried:
```typescript theme={null}
import { ThreatClient, WebacyError } from '@webacy-xyz/sdk';
const client = new ThreatClient({ apiKey: 'your-api-key' });
async function analyzeWithRetry(address: string, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await client.addresses.analyze(address);
} catch (error) {
if (error instanceof WebacyError && error.isRetryable() && attempt < maxRetries) {
// Safe to retry (rate limits, network issues)
const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
// Don't retry (validation errors, auth errors) or max retries reached
throw error;
}
}
}
```
Retryable errors:
* `RateLimitError` - Wait and retry
* `NetworkError` - Retry after connectivity restored
Non-retryable errors:
* `AuthenticationError` - Fix API key
* `ValidationError` - Fix input
* `NotFoundError` - Resource doesn't exist
***
## Automatic Retries
The SDK automatically retries failed requests with exponential backoff:
```typescript theme={null}
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
retry: {
maxRetries: 3, // Default: 3
initialDelay: 1000, // Default: 1000ms
maxDelay: 30000, // Default: 30000ms
backoffMultiplier: 2, // Default: 2
},
});
```
Disable retries for specific requests using an AbortController:
```typescript theme={null}
const controller = new AbortController();
// Timeout after 5 seconds (no retries)
setTimeout(() => controller.abort(), 5000);
try {
await client.addresses.analyze('0x...', {
signal: controller.signal,
});
} catch (error) {
if (error.name === 'AbortError') {
console.log('Request timed out');
}
}
```
***
## Logging Errors
Convert errors to JSON for logging:
```typescript theme={null}
try {
await client.addresses.analyze('0x...');
} catch (error) {
if (error instanceof WebacyError) {
// Structured logging
console.error(JSON.stringify(error.toJSON(), null, 2));
// {
// "name": "ValidationError",
// "message": "Invalid Ethereum address format",
// "code": "VALIDATION_ERROR",
// "status": 400,
// "requestId": "req_abc123",
// "endpoint": "/addresses/invalid"
// }
}
}
```
***
## Full Example
```typescript theme={null}
import {
ThreatClient,
Chain,
WebacyError,
AuthenticationError,
ValidationError,
RateLimitError,
NotFoundError,
NetworkError,
} from '@webacy-xyz/sdk';
async function safeAnalyze(client: ThreatClient, address: string) {
try {
return await client.addresses.analyze(address);
} catch (error) {
// Handle specific error types
if (error instanceof AuthenticationError) {
throw new Error('Please check your API key configuration');
}
if (error instanceof ValidationError) {
throw new Error(`Invalid address: ${error.getRecoverySuggestion()}`);
}
if (error instanceof RateLimitError) {
const waitTime = error.retryAfter || 60;
throw new Error(`Too many requests. Please wait ${waitTime} seconds.`);
}
if (error instanceof NotFoundError) {
return null; // Address not found, return null
}
if (error instanceof NetworkError) {
throw new Error('Network error. Please check your connection.');
}
// Log unexpected errors with request ID for support
if (error instanceof WebacyError) {
console.error('Unexpected error:', error.toJSON());
if (error.requestId) {
console.error(`Request ID for support: ${error.requestId}`);
}
}
throw error;
}
}
```
# Installation
Source: https://docs.webacy.com/sdk/installation
Install and configure the Webacy SDK
## Requirements
* Node.js 18 or later
* An API key from [developers.webacy.co](https://developers.webacy.co/)
## Install the Package
```bash npm theme={null}
npm install @webacy-xyz/sdk
```
```bash pnpm theme={null}
pnpm add @webacy-xyz/sdk
```
```bash yarn theme={null}
yarn add @webacy-xyz/sdk
```
```bash bun theme={null}
bun add @webacy-xyz/sdk
```
## Module Support
The SDK supports both ESM and CommonJS:
```typescript ESM (Recommended) theme={null}
import { ThreatClient, TradingClient, Chain } from '@webacy-xyz/sdk';
```
```javascript CommonJS theme={null}
const { ThreatClient, TradingClient, Chain } = require('@webacy-xyz/sdk');
```
## Initialize a Client
### ThreatClient
For security analysis (addresses, contracts, sanctions, URLs):
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
});
```
### TradingClient
For trading analysis (holder analysis, sniper detection):
```typescript theme={null}
import { TradingClient, Chain } from '@webacy-xyz/sdk';
const client = new TradingClient({
apiKey: process.env.WEBACY_API_KEY,
});
```
## Configuration Options
Both clients accept the same configuration options:
```typescript theme={null}
const client = new ThreatClient({
// Required
apiKey: 'your-api-key',
// Optional: Set a default chain for all requests
defaultChain: Chain.ETH,
// Optional: Enable debug logging
debug: true, // or 'requests' | 'responses' | 'errors'
// Optional: Custom base URL (for development)
baseUrl: 'https://api-development.webacy.com',
// Optional: Request timeout in milliseconds
timeout: 30000,
});
```
### Default Chain
Set a default chain to avoid specifying it on every request:
```typescript theme={null}
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// No need to specify chain - uses ETH
const result = await client.addresses.analyze('0x...');
// Override for specific requests
const solResult = await client.addresses.analyze('So1...', {
chain: Chain.SOL,
});
```
### Debug Mode
Enable logging to troubleshoot issues:
```typescript theme={null}
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
debug: true, // Log everything
});
// Or be more specific:
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
debug: 'requests', // Only log outgoing requests
// debug: 'responses', // Only log responses
// debug: 'errors', // Only log errors
});
```
Never commit your API key to version control. Use environment variables or a secrets manager.
## Individual Packages
If you only need specific functionality, install individual packages to reduce bundle size:
| Package | Install | Description |
| ---------------------------------------------------------------------------------- | ------------------------------------- | ------------------- |
| [`@webacy-xyz/sdk-core`](https://www.npmjs.com/package/@webacy-xyz/sdk-core) | `npm install @webacy-xyz/sdk-core` | Core utilities only |
| [`@webacy-xyz/sdk-threat`](https://www.npmjs.com/package/@webacy-xyz/sdk-threat) | `npm install @webacy-xyz/sdk-threat` | Threat analysis |
| [`@webacy-xyz/sdk-trading`](https://www.npmjs.com/package/@webacy-xyz/sdk-trading) | `npm install @webacy-xyz/sdk-trading` | Trading analysis |
```typescript theme={null}
// Import from specific packages
import { ThreatClient } from '@webacy-xyz/sdk-threat';
import { TradingClient } from '@webacy-xyz/sdk-trading';
import { Chain, ValidationError } from '@webacy-xyz/sdk-core';
```
## TypeScript Configuration
The SDK is written in TypeScript and includes type definitions. For the best experience, ensure your `tsconfig.json` includes:
```json theme={null}
{
"compilerOptions": {
"moduleResolution": "bundler", // or "node16" / "nodenext"
"esModuleInterop": true,
"strict": true
}
}
```
## Next Steps
Analyze addresses, contracts, and URLs
Holder analysis and trading insights
# SDK Introduction
Source: https://docs.webacy.com/sdk/introduction
Official TypeScript SDK for the Webacy API
Use the Webacy SDK to integrate blockchain security and risk analysis capabilities into your applications. You get type-safe access to all Webacy API endpoints with built-in error handling, retry logic, and multi-chain support.
## Why Use the SDK?
Full TypeScript support with complete type definitions for all requests and responses
Built-in support for 12 blockchains with type-safe Chain enum
Structured error classes with recovery suggestions
Automatic retries with exponential backoff for transient failures
## Packages
The SDK is organized as a monorepo with focused packages:
| Package | Description |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`@webacy-xyz/sdk`](https://www.npmjs.com/package/@webacy-xyz/sdk) | Unified SDK that re-exports all packages |
| [`@webacy-xyz/sdk-core`](https://www.npmjs.com/package/@webacy-xyz/sdk-core) | Core utilities: HTTP client, errors, Chain enum |
| [`@webacy-xyz/sdk-threat`](https://www.npmjs.com/package/@webacy-xyz/sdk-threat) | Threat analysis: addresses, contracts, sanctions, URLs |
| [`@webacy-xyz/sdk-trading`](https://www.npmjs.com/package/@webacy-xyz/sdk-trading) | Trading analysis: holder analysis, sniper detection |
For most use cases, install `@webacy-xyz/sdk` which includes everything you need.
## Quick Example
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// Analyze an address for security risks
const result = await client.addresses.analyze(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
);
console.log(result.overallRisk); // 0-100 risk score
console.log(result.issues); // Array of risk factors
```
## Supported Chains
The SDK supports all 12 blockchains available in the Webacy API:
```typescript theme={null}
import { Chain } from '@webacy-xyz/sdk';
Chain.ETH // Ethereum
Chain.SOL // Solana
Chain.BASE // Base
Chain.BSC // BNB Smart Chain
Chain.POL // Polygon
Chain.ARB // Arbitrum
Chain.OPT // Optimism
Chain.TON // TON
Chain.SUI // Sui
Chain.STELLAR // Stellar
Chain.BTC // Bitcoin
Chain.SEI // Sei
```
## Next Steps
Install the SDK in your project
Analyze addresses, contracts, and URLs
Holder analysis and sniper detection
Handle errors gracefully
# ThreatClient
Source: https://docs.webacy.com/sdk/threat-client
Security analysis for addresses, contracts, and URLs
The `ThreatClient` provides access to Webacy's threat and risk analysis APIs. Use it to analyze addresses for security risks, screen for sanctions, check smart contract vulnerabilities, and verify URL safety.
## Initialization
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH, // Optional: set default chain
});
```
## Resources
The ThreatClient provides access to these resources:
| Resource | Description |
| -------------- | ------------------------------------------------------------------------------- |
| `addresses` | Address risk analysis, sanctions screening, poisoning detection, quick profiles |
| `contracts` | Smart contract security analysis and code analysis |
| `url` | URL safety and phishing detection |
| `wallets` | Wallet activity and approval analysis |
| `ledger` | Hardware wallet transaction scanning |
| `accountTrace` | Fund flow tracing |
| `transactions` | Transaction risk analysis |
| `scan` | Transaction and EIP-712 message scanning |
| `usage` | API usage statistics |
***
## Addresses
### Analyze Address Risk
Get comprehensive risk analysis for any blockchain address.
```typescript theme={null}
const result = await client.addresses.analyze(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{ chain: Chain.ETH }
);
console.log(result.overallRisk); // 0-100 risk score
console.log(result.issues); // Array of risk factors
console.log(result.isContract); // true if smart contract
```
**Response:**
```json theme={null}
{
"count": 1,
"medium": 0,
"high": 1,
"overallRisk": 75.5,
"issues": [
{
"tag": "Mixer User",
"severity": "high",
"description": "Address has interacted with mixing services"
}
],
"isContract": false
}
```
**Options:**
| Option | Type | Description |
| -------------- | -------------- | ---------------------------------------------------- |
| `chain` | `Chain` | Blockchain to analyze (optional if defaultChain set) |
| `modules` | `RiskModule[]` | Specific risk modules to run |
| `detailed` | `boolean` | Include detailed analysis data |
| `deployerRisk` | `boolean` | Include deployer risk for contracts |
### Check Sanctions
Screen an address against OFAC and other sanctions lists.
```typescript theme={null}
const result = await client.addresses.checkSanctioned(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{ chain: Chain.ETH }
);
if (result.is_sanctioned) {
console.error('Address is sanctioned!');
console.log(result.sanction_details);
}
```
### Check Address Poisoning
Detect address poisoning (dust attack) attempts.
```typescript theme={null}
const result = await client.addresses.checkPoisoning(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{ chain: Chain.ETH }
);
if (result.is_poisoned) {
console.warn('Address poisoning detected!');
console.log(result.poisoning_details?.similar_addresses);
}
```
### Get Quick Profile
Get a lightweight risk profile with optional token approvals.
```typescript theme={null}
const result = await client.addresses.getQuickProfile(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{
chain: Chain.ETH,
withApprovals: true, // Include token approvals
}
);
console.log(`Risk score: ${result.riskScore}`);
console.log(`Risk level: ${result.riskLevel}`);
console.log(`Account age: ${result.accountAge} days`);
// Check approvals if requested
for (const approval of result.approvals ?? []) {
console.log(`${approval.symbol} approved to ${approval.spenderName}`);
}
```
**Options:**
| Option | Type | Description |
| ---------------- | --------- | ---------------------------------------------------------- |
| `chain` | `Chain` | Blockchain to analyze (ETH, BASE, BSC, POL, OPT, ARB, SOL) |
| `withApprovals` | `boolean` | Include token approval data |
| `hideTrustFlags` | `boolean` | Hide trust flags in response |
***
## Contracts
### Analyze Contract
Get security analysis for a smart contract.
```typescript theme={null}
const result = await client.contracts.analyze(
'0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
{ chain: Chain.ETH }
);
console.log(result.overallRisk);
console.log(result.vulnerabilities);
```
### Get Contract Tax
Check buy/sell tax for a token contract.
```typescript theme={null}
const result = await client.contracts.getTax(
'0xTokenAddress...',
{ chain: Chain.ETH }
);
console.log(`Buy tax: ${result.buyTax}%`);
console.log(`Sell tax: ${result.sellTax}%`);
```
### Get Code Analysis
Perform static code analysis on a contract's source code.
```typescript theme={null}
const result = await client.contracts.getCodeAnalysis(
'0xContractAddress...',
{
chain: Chain.ETH,
refreshCache: false, // Use cached results if available
}
);
console.log(`Total findings: ${result.findings.length}`);
for (const finding of result.findings) {
console.log(`[${finding.severity}] ${finding.title}`);
console.log(` ${finding.description}`);
console.log(` Location: ${finding.location}`);
}
```
**Response:**
```json theme={null}
{
"contractAddress": "0x...",
"chain": "eth",
"findings": [
{
"title": "Reentrancy vulnerability",
"description": "External call before state update",
"severity": "high",
"location": "withdraw() line 45",
"recommendation": "Use checks-effects-interactions pattern"
}
],
"analyzedAt": "2024-01-20T12:00:00Z"
}
```
***
## URL Safety
### Check URL
Analyze a URL for phishing and malware.
```typescript theme={null}
const result = await client.url.check('https://suspicious-site.com');
if (result.isPhishing) {
console.error('Phishing site detected!');
}
console.log(result.riskScore);
console.log(result.categories);
```
***
## Wallets
### Get Approvals
List token approvals for a wallet.
```typescript theme={null}
const result = await client.wallets.getApprovals(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{ chain: Chain.ETH }
);
for (const approval of result.approvals) {
console.log(`${approval.token} approved to ${approval.spender}`);
console.log(`Amount: ${approval.amount}`);
}
```
### Get Transactions
Get risk-scored transaction history for a wallet.
```typescript theme={null}
const result = await client.wallets.getTransactions(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{ chain: Chain.ETH }
);
console.log(`Risk score: ${result.overallRisk}`);
console.log(`Issues found: ${result.count}`);
for (const issue of result.issues) {
console.log(`[${issue.severity}] ${issue.tag}: ${issue.description}`);
}
```
**Response:**
```json theme={null}
{
"count": 2,
"overallRisk": 45,
"issues": [
{
"tag": "Risky Interaction",
"severity": "medium",
"description": "Interacted with flagged address"
}
]
}
```
***
## Account Trace
### Trace Fund Flows
Trace multi-hop fund flows for compliance and forensics.
```typescript theme={null}
const result = await client.accountTrace.trace(
'0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
{ chain: Chain.ETH }
);
console.log(`Total connections: ${result.summary.totalConnections}`);
console.log(`High-risk: ${result.summary.highRiskConnections}`);
for (const conn of result.connections) {
console.log(`${conn.address}: ${conn.relationship} - ${conn.riskFlags.join(', ')}`);
}
```
**Response:**
```json theme={null}
{
"summary": {
"totalConnections": 15,
"highRiskConnections": 3
},
"connections": [
{
"address": "0xabc...",
"relationship": "direct_transfer",
"riskFlags": ["mixer_user", "high_risk"],
"depth": 1
}
]
}
```
***
## Usage
### Get API Usage
Monitor your API usage and quotas.
```typescript theme={null}
const usage = await client.usage.get();
console.log(`Requests used: ${usage.requestsUsed}`);
console.log(`Requests remaining: ${usage.requestsRemaining}`);
console.log(`Reset date: ${usage.resetDate}`);
```
### Get Max RPS
Get maximum requests per second for an organization over a time period.
```typescript theme={null}
const maxRps = await client.usage.getMaxRps({
organization: 'my-org',
from: Date.now() - 86400000, // 24 hours ago
to: Date.now(),
});
console.log(`Max RPS: ${maxRps}`);
```
**Options:**
| Option | Type | Required | Description |
| -------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `organization` | `string` | Yes | Organization identifier |
| `from` | `number` | Yes | Start time as Unix timestamp in milliseconds (e.g., `Date.now() - 86400000`) |
| `to` | `number` | Yes | End time as Unix timestamp in milliseconds (e.g., `Date.now()`) |
***
## Transactions
### Analyze Transaction
Get risk analysis for a blockchain transaction.
```typescript theme={null}
const result = await client.transactions.analyze(
'0xTransactionHash...',
{ chain: Chain.ETH }
);
console.log(`Risk score: ${result.riskScore}`);
console.log(`Risk level: ${result.riskLevel}`);
for (const tag of result.riskTags ?? []) {
console.log(`Risk: ${tag.tag} - ${tag.description}`);
}
```
**Supported chains:** ETH, BASE, BSC, POL, OPT, ARB, SOL, STELLAR
**Options:**
| Option | Type | Description |
| ---------------- | --------- | ---------------------------- |
| `chain` | `Chain` | Blockchain to analyze |
| `hideTrustFlags` | `boolean` | Hide trust flags in response |
***
## Scan
### Scan Transaction
Scan a raw transaction for risks before signing.
```typescript theme={null}
const result = await client.scan.scanTransaction(
'0xSignerAddress...',
{
tx: {
from: '0xSignerAddress...',
raw: '0xRawTransactionData...',
},
chain: 1, // Chain ID (1 = Ethereum)
domain: 'app.example.com', // Optional: dApp domain
}
);
console.log(`Risk level: ${result.riskLevel}`); // low, medium, high
console.log(`Warnings: ${result.warnings.length}`);
// Check asset changes
for (const change of result.assetChanges ?? []) {
console.log(`${change.type}: ${change.amount} ${change.symbol}`);
}
```
**Supported chain IDs:** 1 (ETH), 56 (BSC), 137 (POL), 10 (OPT), 42161 (ARB), 8453 (BASE)
### Scan EIP-712 Message
Scan an EIP-712 typed data message before signing.
```typescript theme={null}
const result = await client.scan.scanEip712(
'0xSignerAddress...',
{
msg: {
from: '0xSignerAddress...',
data: {
types: {
EIP712Domain: [
{ name: 'name', type: 'string' },
{ name: 'version', type: 'string' },
{ name: 'chainId', type: 'uint256' },
],
Permit: [
{ name: 'owner', type: 'address' },
{ name: 'spender', type: 'address' },
{ name: 'value', type: 'uint256' },
],
},
primaryType: 'Permit',
domain: {
name: 'MyToken',
version: '1',
chainId: 1,
},
message: {
owner: '0x...',
spender: '0x...',
value: '1000000000000000000',
},
},
},
domain: 'app.example.com',
}
);
console.log(`Risk level: ${result.riskLevel}`);
console.log(`Message type: ${result.messageType}`);
```
***
## Full Example
```typescript theme={null}
import { ThreatClient, Chain, ValidationError, RateLimitError } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
async function analyzeWallet(address: string) {
try {
// Get overall risk
const risk = await client.addresses.analyze(address);
if (risk.overallRisk > 70) {
console.warn(`High risk wallet: ${risk.overallRisk}`);
// Check sanctions
const sanctions = await client.addresses.checkSanctioned(address);
if (sanctions.is_sanctioned) {
throw new Error('Sanctioned address - cannot proceed');
}
// Check for address poisoning
const poisoning = await client.addresses.checkPoisoning(address);
if (poisoning.is_poisoned) {
console.warn('Address may be a poisoning attempt');
}
}
return { safe: risk.overallRisk < 50, risk };
} catch (error) {
if (error instanceof ValidationError) {
console.error('Invalid address:', error.message);
} else if (error instanceof RateLimitError) {
console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
}
throw error;
}
}
```
## Next Steps
Holder analysis and sniper detection
Handle errors gracefully
Supported blockchain networks
Full API documentation
# TradingClient
Source: https://docs.webacy.com/sdk/trading-client
Token holder analysis and trading insights
Use the `TradingClient` to access Webacy's trading analysis APIs. You can analyze token holder distribution, detect snipers and bundlers, and get quick trading insights.
## Initialization
**Prerequisites:**
* SDK installed (`npm install @webacy-xyz/sdk`)
* API key available (from your Webacy dashboard)
```typescript theme={null}
import { TradingClient, Chain } from '@webacy-xyz/sdk';
const client = new TradingClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.SOL, // Optional: set default chain
});
```
## Resources
The TradingClient provides access to these resources:
| Resource | Description |
| ---------------- | ------------------------------------------------------- |
| `holderAnalysis` | Token holder distribution, sniper/bundler detection |
| `tradingLite` | Quick trading analysis (Solana only) |
| `tokens` | Token pools, trending data, economics, and OHLCV charts |
***
## Holder Analysis
### Get Holder Analysis
Get comprehensive analysis of token holder distribution.
```typescript theme={null}
const result = await client.holderAnalysis.get(
'TokenMintAddress...',
{ chain: Chain.SOL }
);
console.log(`Total holders: ${result.totalHolders}`);
console.log(`Top 10 hold: ${result.top10Percentage}%`);
console.log(`Snipers detected: ${result.sniperCount}`);
```
**Response includes:**
* Top holders with wallet addresses and percentages
* First buyers analysis
* Sniper detection with confidence scores
* Bundler detection
* Developer wallet tracking
* Concentration metrics
### Response Example
```json theme={null}
{
"totalHolders": 1523,
"top10Percentage": 45.2,
"top10Holders": [
{
"address": "ABC123...",
"percentage": 12.5,
"isSuspicious": false
}
],
"sniperCount": 8,
"snipers": [
{
"address": "DEF456...",
"confidence": 0.95,
"buyBlock": 123456,
"percentage": 2.1
}
],
"bundlerCount": 3,
"devWallets": ["GHI789..."]
}
```
**Options:**
| Option | Type | Description |
| ------- | ------- | ---------------------------------------------------- |
| `chain` | `Chain` | Blockchain to analyze (optional if defaultChain set) |
***
## Trading Lite
Quick, simplified token analysis optimized for trading decisions.
Trading Lite is currently available for **Solana only**.
### Analyze Token
```typescript theme={null}
const result = await client.tradingLite.analyze('PumpTokenAddress...');
console.log(`Risk score: ${result.riskScore}`);
console.log(`Liquidity: $${result.liquidity}`);
console.log(`Is honeypot: ${result.isHoneypot}`);
```
**Response includes:**
* Quick risk assessment
* Liquidity metrics
* Honeypot detection
* Basic holder stats
***
## Tokens
### Fetch Token Pools
Retrieve liquidity pool information for a token.
```typescript theme={null}
const result = await client.tokens.getPools(
'0xTokenAddress...',
{ chain: Chain.ETH }
);
for (const pool of result.pools) {
console.log(`DEX: ${pool.dex}`);
console.log(`Liquidity: $${pool.liquidity}`);
console.log(`Pair: ${pool.pairToken}`);
}
```
### List Trending Tokens
Retrieve currently trending tokens on a chain.
```typescript theme={null}
const result = await client.tokens.getTrending({ chain: Chain.SOL });
for (const token of result.tokens) {
console.log(`${token.symbol}: ${token.priceChange24h}%`);
}
```
### Get Token Economics
Retrieve token economics data including supply, market cap, and holder statistics.
```typescript theme={null}
const result = await client.tokens.getToken(
'0xTokenAddress...',
{
chain: Chain.ETH,
metricsDate: '20-01-2024', // DD-MM-YYYY format
}
);
console.log(`Token: ${result.name} (${result.symbol})`);
console.log(`Price: $${result.metrics.priceUsd}`);
console.log(`Market Cap: $${result.metrics.marketCap}`);
console.log(`24h Volume: $${result.metrics.volume24h}`);
console.log(`Holders: ${result.metrics.holderCount}`);
```
**Supported chains:** ETH, BASE, BSC, POL, OPT, ARB, SOL
**Options:**
| Option | Type | Description |
| ------------- | -------- | ------------------------- |
| `chain` | `Chain` | Blockchain to query |
| `metricsDate` | `string` | Date in DD-MM-YYYY format |
### Get Pool OHLCV
Retrieve Open, High, Low, Close, Volume candlestick data for a liquidity pool.
```typescript theme={null}
const result = await client.tokens.getPoolOhlcv(
'0xPoolAddress...',
{
chain: Chain.ETH,
timeFrame: 'hour', // 'minute', 'hour', or 'day'
limit: 24, // Number of data points
}
);
console.log(`Pool: ${result.poolName}`);
for (const candle of result.data) {
const time = new Date(candle.timestamp * 1000).toISOString();
console.log(`${time} - O: ${candle.open} H: ${candle.high} L: ${candle.low} C: ${candle.close}`);
console.log(` Volume: ${candle.volume}`);
}
```
**Options:**
| Option | Type | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `chain` | `Chain` | Blockchain to query |
| `timeFrame` | `string` | `minute`, `hour`, or `day` |
| `beforeTimestamp` | `number` | Unix timestamp in **seconds** to fetch data before (use `Math.floor(Date.now() / 1000)` to convert from milliseconds) |
| `limit` | `number` | Number of data points to return |
***
## Full Example
```typescript theme={null}
import { TradingClient, Chain, ValidationError } from '@webacy-xyz/sdk';
const client = new TradingClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.SOL,
});
async function analyzeToken(tokenAddress: string) {
try {
// Get holder analysis
const holders = await client.holderAnalysis.get(tokenAddress);
// Check for red flags
const redFlags: string[] = [];
// High concentration
if (holders.top10Percentage > 80) {
redFlags.push(`High concentration: Top 10 hold ${holders.top10Percentage}%`);
}
// Snipers
if (holders.sniperCount > 5) {
redFlags.push(`${holders.sniperCount} snipers detected`);
}
// Bundlers
if (holders.bundlerCount > 0) {
redFlags.push(`${holders.bundlerCount} bundlers detected`);
}
// Quick analysis (Solana)
const quickAnalysis = await client.tradingLite.analyze(tokenAddress);
if (quickAnalysis.isHoneypot) {
redFlags.push('Honeypot detected!');
}
return {
safe: redFlags.length === 0,
redFlags,
holders,
quickAnalysis,
};
} catch (error) {
if (error instanceof ValidationError) {
console.error('Invalid token address:', error.message);
}
throw error;
}
}
// Usage
const analysis = await analyzeToken('PumpTokenMint...');
if (!analysis.safe) {
console.warn('Red flags detected:');
analysis.redFlags.forEach(flag => console.warn(` - ${flag}`));
}
```
## Use Cases
Detect snipers and bundlers on new token launches
Identify concentrated holdings and dev wallets
Quick risk assessment for trading decisions
Comprehensive holder analysis before investing
## Next Steps
Address and contract security analysis
Handle errors gracefully
# Use Cases
Source: https://docs.webacy.com/sdk/use-cases
How different types of businesses use the Webacy SDK
Use the Webacy SDK to add blockchain security across diverse applications. Here's how you can leverage these capabilities for your use case.
## Wallet Apps & Browser Extensions
**Examples**: MetaMask-like wallets, hardware wallet companions, mobile wallets
`addresses.analyze()` - Check addresses before sending funds
`addresses.getQuickProfile()` - Sub-500ms risk scores for real-time UX
`addresses.checkPoisoning()` - Detect address poisoning attacks
`scan.scanTransaction()` - Simulate transactions before signing
**Additional Features**:
* `scan.scanEip712()` - Verify permit signatures
* `url.check()` - Block phishing links
* `wallets.getApprovals()` - Show risky token approvals
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// Before sending funds, check the recipient
async function checkRecipient(address: string) {
// Quick risk check (< 500ms)
const profile = await client.addresses.getQuickProfile(address);
if (profile.riskScore > 70) {
// Deep analysis for high-risk addresses
const analysis = await client.addresses.analyze(address);
return { safe: false, issues: analysis.issues };
}
// Check for address poisoning
const poisoning = await client.addresses.checkPoisoning(address);
if (poisoning.is_poisoned) {
return { safe: false, issues: ['Possible address poisoning attack'] };
}
return { safe: true };
}
```
**Value**: Protect your users before they sign dangerous transactions
***
## DeFi Protocols & DEXes
**Examples**: Uniswap-like DEXes, lending protocols, yield aggregators
`contracts.analyze()` - Screen new token listings
`contracts.getTax()` - Show buy/sell taxes
`addresses.checkSanctioned()` - OFAC sanctions screening
`holderAnalysis.get()` - Detect concentrated holdings
**Additional Features**:
* `tokens.getPools()` - Pool risk analysis
```typescript theme={null}
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 };
}
```
**Value**: Screen tokens and protect your users from scams
***
## Trading Platforms & Bots
**Examples**: Copy trading apps, trading bots, alpha scanners
`tradingLite.analyze()` - Rapid token analysis (Solana)
`holderAnalysis.get()` - Detect snipers and bundlers
`tokens.getTrending()` - Find trending tokens with risk scores
`contracts.getTax()` - Uncover hidden trading fees
**Additional Features**:
* `tokens.getPoolOhlcv()` - Technical analysis data
```typescript theme={null}
import { TradingClient, ThreatClient, Chain } from '@webacy-xyz/sdk';
const trading = new TradingClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.SOL,
});
const threat = new ThreatClient({ apiKey: process.env.WEBACY_API_KEY });
// Quick token analysis for trading bot
async function analyzeForTrading(tokenAddress: string) {
// Fast analysis (< 1s)
const quick = await trading.tradingLite.analyze(tokenAddress);
if (quick.isHoneypot) return { tradeable: false, reason: 'Honeypot' };
if (quick.riskScore > 80) return { tradeable: false, reason: 'High risk' };
// Check for hidden fees
const tax = await threat.contracts.getTax(tokenAddress, { chain: Chain.SOL });
if (tax.buyTax > 5 || tax.sellTax > 5) {
return { tradeable: false, reason: `High tax: ${tax.buyTax}/${tax.sellTax}` };
}
return { tradeable: true, riskScore: quick.riskScore };
}
```
**Value**: Identify safe trading opportunities, avoid scams
***
## Exchanges (CEX & DEX)
**Examples**: Centralized exchanges, hybrid exchanges
`addresses.checkSanctioned()` - OFAC/sanctions compliance
`addresses.analyze()` - Screen incoming deposits
`accountTrace.trace()` - Multi-hop fund flow analysis
`transactions.analyze()` - Real-time transaction screening
**Additional Features**:
* `contracts.analyze()` - Token listing due diligence
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// Screen deposit address for compliance
async function screenDeposit(address: string, chain: Chain) {
// Sanctions check (required for compliance)
const sanctions = await client.addresses.checkSanctioned(address, { chain });
if (sanctions.is_sanctioned) {
return { allowed: false, reason: 'Sanctioned address', details: sanctions };
}
// Risk analysis
const risk = await client.addresses.analyze(address, { chain });
if (risk.overallRisk > 80) {
// Trace fund sources for high-risk
const trace = await client.accountTrace.trace(address, { chain });
return { allowed: false, reason: 'High risk', risk, trace };
}
return { allowed: true, riskScore: risk.overallRisk };
}
```
**Value**: Meet regulatory requirements and protect your platform
***
## Portfolio Trackers & Analytics
**Examples**: Zerion, DeBank-like apps, wallet dashboards
`wallets.getApprovals()` - Show and manage token approvals
`wallets.getTransactions()` - Risk-scored transaction history
`addresses.getQuickProfile()` - Wallet security scores
`tokens.getToken()` - Token economics and safety data
```typescript theme={null}
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 });
// Build wallet health dashboard
async function getWalletHealth(address: string, chain: Chain) {
const [profile, approvals, transactions] = await Promise.all([
threat.addresses.getQuickProfile(address, { chain, withApprovals: true }),
threat.wallets.getApprovals(address, { chain }),
threat.wallets.getTransactions(address, { chain }),
]);
// Count risky approvals (unlimited or to unknown contracts)
const riskyApprovals = approvals.approvals.filter(
a => a.amount === 'unlimited' || a.spenderRisk > 50
);
return {
riskScore: profile.riskScore,
riskLevel: profile.riskLevel,
accountAge: profile.accountAge,
riskyApprovals: riskyApprovals.length,
recentIssues: transactions.issues,
};
}
```
**Value**: Give users insights into their wallet security
***
## Compliance & Security Teams
**Examples**: Crypto compliance firms, AML providers, forensic investigators
`addresses.checkSanctioned()` - Real-time sanctions checks
`accountTrace.trace()` - Multi-hop transaction tracing
`wallets.getTransactions()` - Complete transaction history
`contracts.getCodeAnalysis()` - Smart contract security analysis
```typescript theme={null}
import { ThreatClient, Chain } from '@webacy-xyz/sdk';
const client = new ThreatClient({
apiKey: process.env.WEBACY_API_KEY,
defaultChain: Chain.ETH,
});
// AML screening workflow
async function amlScreening(address: string, chain: Chain) {
// Step 1: Sanctions check
const sanctions = await client.addresses.checkSanctioned(address, { chain });
if (sanctions.is_sanctioned) {
return { status: 'blocked', reason: 'sanctioned', data: sanctions };
}
// Step 2: Risk analysis
const risk = await client.addresses.analyze(address, { chain });
// Step 3: Fund flow tracing for medium+ risk
if (risk.overallRisk >= 50) {
const trace = await client.accountTrace.trace(address, { chain });
const transactions = await client.wallets.getTransactions(address, { chain });
return {
status: risk.overallRisk >= 75 ? 'review' : 'monitor',
risk,
trace,
transactions,
};
}
return { status: 'approved', risk };
}
```
**Value**: Enterprise-grade blockchain compliance and forensics
***
## Token Launch Platforms
**Examples**: Pump.fun integrations, launchpads, fair launch platforms
`holderAnalysis.get()` - Monitor holder concentration
`tradingLite.analyze()` - Screen new token launches
`contracts.analyze()` - Verify contract security
```typescript theme={null}
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,
defaultChain: Chain.SOL,
});
// Screen new token launch
async function screenLaunch(tokenAddress: string) {
const [quick, holders, contract] = await Promise.all([
trading.tradingLite.analyze(tokenAddress),
trading.holderAnalysis.get(tokenAddress),
threat.contracts.analyze(tokenAddress, { chain: Chain.SOL }),
]);
const warnings: string[] = [];
if (quick.isHoneypot) warnings.push('Honeypot detected');
if (holders.sniperCount > 5) warnings.push(`${holders.sniperCount} snipers`);
if (holders.bundlerCount > 0) warnings.push(`${holders.bundlerCount} bundlers`);
if (holders.top10Percentage > 80) warnings.push('High concentration');
if (contract.overallRisk > 70) warnings.push('Contract risk');
return {
safe: warnings.length === 0,
warnings,
metrics: { holders: holders.totalHolders, liquidity: quick.liquidity },
};
}
```
**Value**: Verify launches are safe, detect snipers and bundlers
***
## Why Webacy SDK?
12+ chains: ETH, SOL, BASE, ARB, POL, OPT, BSC, TON, SUI, STELLAR, BTC, SEI
Full TypeScript support with IntelliSense
Quick profile optimized for sub-500ms responses
Addresses, contracts, URLs, transactions
Built-in retry logic and error handling
Stop losses before they happen
## Get Started
Install the SDK in your project
Start with address and contract analysis
Token and holder analysis
Full endpoint documentation