Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.webacy.com/llms.txt

Use this file to discover all available pages before exploring further.

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: 
## 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: 
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

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. 
curl -X GET "https://api.webacy.com/addresses/{address}?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

​
Endpoint Reference

​
Risk DD Endpoints

MethodPathDescriptionChains
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 analysiseth pol opt arb base bsc
GET/contracts/{contractAddress}/code-analysisDetailed contract code analysiseth pol opt arb base bsc
GET/contracts/{contractAddress}/source-codeContract source code retrievaleth pol opt arb base bsc
GET/tokens/{tokenAddress}Comprehensive token risk analysiseth base bsc pol opt arb sol ton sei sui btc
GET/holder-analysis/{address}Token holder distribution and sniper detectioneth pol opt arb base bsc sol stellar sui hedera
POST/urlAnalyze a URL for phishing/malware risksAll (not chain-specific)
GET/transactions/{txHash}Risk details for a completed transactioneth base bsc pol opt sol arb stellar hedera
GET/addresses/sanctioned/{walletAddress}Check address against OFAC sanction listseth pol opt arb base bsc sol ton sei sui stellar btc
GET/addresses/{address}/poisoningDetect address poisoning attackseth pol opt arb base bsc
GET/addresses/{address}/approvalsAnalyze token approval riskseth pol opt arb base bsc
GET/contracts/taxes/{tokenAddress}Get buy/sell tax percentages for a tokenAll chains
GET/contracts/tokens/recommendationsGet recommended high-quality tokensAll (optional chain filter)
GET/contracts/tokens/by-risk-levelGet tokens filtered by risk level (low/high)All (optional chain filter)
GET/contracts/symbol/{symbol}Look up token risk data by ticker symbolAll (optional chain filter)
POST/addresses/multisenderBatch detect multisender/disperser contractsAll chains
POST/batch/transactionsBatch analyze up to 500 transactionsAll chains
GET/audits/{address}Get smart contract audit data (via Trustblock)All chains
GET/mica-report/{symbol}Get MiCA compliance report for a tokenNot chain-specific

​
Trading DD Endpoints

MethodPathDescriptionChains
GET/trading-lite/{address}Lightweight trading risk assessmentsol
GET/tokens/{tokenAddress}/poolsGet liquidity pools for a tokeneth base bsc pol opt arb sol ton sei sui btc
GET/tokens/pools/{poolAddress}Get specific pool dataeth base bsc pol opt arb sol ton sei sui btc
GET/tokens/trendingGet trending tokenseth base bsc pol opt arb sol ton sei sui btc
GET/tokens/pools/trendingGet trending liquidity poolseth base bsc pol opt arb sol ton sei sui btc
POST/scan/{fromAddress}/transactionsSimulate and scan a transaction before signingeth pol opt arb base bsc
POST/scan/{fromAddress}/eip712Scan EIP-712 typed data signing requestseth

​
Utility Endpoints

MethodPathDescription
GET/usageGet API usage for a date range
GET/usage/currentGet current billing period usage
GET/usage/max-rpsGet max requests per second

​
Chain Reference

BlockchainIdentifierAddress Format
Ethereumeth0x... (42 chars)
Polygonpol0x... (42 chars)
Optimismopt0x... (42 chars)
Arbitrumarb0x... (42 chars)
Basebase0x... (42 chars)
BSCbsc0x... (42 chars)
SolanasolBase58 (32-44 chars)
TONtonEQ... or UQ...
Seiseisei1... or 0x...
Suisui0x... (66 chars)
StellarstellarG... (56 chars) or CODE:ISSUER for tokens
Hederahedera0.0.X (native) or 0x... (EVM)
Bitcoinbtcbc1..., 1..., or 3...
Default chain when omitted: eth.

​
Response Shapes

​
Address Risk (GET /addresses/{address})

{
  "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})

{
  "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})

{
  "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: 
{
  "to": "0xContractAddress",
  "data": "0xCalldata",
  "value": "1000000000000000000",
  "chain": "eth"
}
Response: 
{
  "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})

{
  "address": "0x...",
  "is_sanctioned": false
}

​
URL Risk (POST /url)

Request body: 
{
  "url": "https://example.com"
}
Response: 
{
  "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. 
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. 
// 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). 
// 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. 
// 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. 
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 CodeMeaningAction
200SuccessParse response body
400Bad request (invalid params)Check address format and chain parameter
401UnauthorizedCheck x-api-key header
403ForbiddenAPI key lacks permissions for this endpoint
404Not foundAddress/transaction not found on specified chain
429Rate limit exceededBack off and retry with exponential delay
500Server errorRetry after a short delay
Error response format: 
{
  "message": "Error description"
}

​
Query Parameters

Common parameters across endpoints:
ParameterTypeDescription
chainstringBlockchain identifier (e.g., eth, sol). Defaults to eth
show_low_riskbooleanInclude low-risk issues in response. Default: true
hide_trust_flagsbooleanHide trust-related flags from response
modulesstring[]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