Agent Reference

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

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	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}`)

{
  "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,
  "analyzed_at": "2026-07-07T03:06:06.986Z"
}

overallRisk: 0-100 score (higher = riskier)
count: Total number of risk issues found
medium / high: Count of medium/high severity issues
analyzed_at: ISO 8601 timestamp of the analysis. This endpoint has no stale flag — use analyzed_at as the freshness signal. Treat missing or errored data as unknown, never safe.

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

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

Getting Started

Risk Ratings, Scoring, and Documentation

SDK

Integrations

Essentials

Glossary

Setup

Claude Code

Cursor

Other Agents

Authentication & Base URL

Endpoint Reference

Risk DD Endpoints

Trading DD Endpoints

Utility Endpoints

Chain Reference

Response Shapes

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

Token Risk (`GET /tokens/{tokenAddress}`)

Holder Analysis (`GET /holder-analysis/{address}`)

Transaction Scan (`POST /scan/{fromAddress}/transactions`)

Sanction Check (`GET /addresses/sanctioned/{walletAddress}`)

URL Risk (`POST /url`)

Common Workflows

Wallet Risk Screening

Token Due Diligence

Pre-Trade Risk Check

Compliance Screening

Transaction Simulation

Error Handling

Query Parameters

Rules for AI Agents

ALWAYS

NEVER

ASK FIRST

​Setup

​Claude Code

​Cursor

​Other Agents

​Authentication & Base URL

​Endpoint Reference

​Risk DD Endpoints

​Trading DD Endpoints

​Utility Endpoints

​Chain Reference

​Response Shapes

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

​Token Risk (GET /tokens/{tokenAddress})

​Holder Analysis (GET /holder-analysis/{address})

​Transaction Scan (POST /scan/{fromAddress}/transactions)

​Sanction Check (GET /addresses/sanctioned/{walletAddress})

​URL Risk (POST /url)

​Common Workflows

​Wallet Risk Screening

​Token Due Diligence

​Pre-Trade Risk Check

​Compliance Screening

​Transaction Simulation

​Error Handling

​Query Parameters

​Rules for AI Agents

​ALWAYS

​NEVER

​ASK FIRST

Setup

Claude Code

Cursor

Other Agents

Authentication & Base URL

Endpoint Reference

Risk DD Endpoints

Trading DD Endpoints

Utility Endpoints

Chain Reference

Response Shapes

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

Token Risk (`GET /tokens/{tokenAddress}`)

Holder Analysis (`GET /holder-analysis/{address}`)

Transaction Scan (`POST /scan/{fromAddress}/transactions`)

Sanction Check (`GET /addresses/sanctioned/{walletAddress}`)

URL Risk (`POST /url`)

Common Workflows

Wallet Risk Screening

Token Due Diligence

Pre-Trade Risk Check

Compliance Screening

Transaction Simulation

Error Handling

Query Parameters

Rules for AI Agents

ALWAYS

NEVER

ASK FIRST