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

# Agent Reference

> Self-contained Webacy API reference for AI coding agents like Claude Code, Cursor, and Copilot, with endpoints, parameters, and ready-to-paste examples.

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                             | 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,
  "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.

<Note>Additional fields may be present including `addressType`, `details`, `context`, `deployer`, `holder_analysis`, and others. The fields shown above are the core risk assessment fields.</Note>

### 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"]
  }
}
```

<Note>Access the risk score via `data.risk.overallRisk`. Risk data is nested under the `risk` key, not at the top level.</Note>

### 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": { }
}
```

<Note>Sub-objects vary by chain. For example, `sniper_analysis` is excluded for Hedera, and `activity_patterns` is EVM-only.</Note>

### 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"
}
```

<Note>The `simulation` object is opaque and varies by transaction type.</Note>

### 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": "..."
}
```

<Note>`riskLevel` values: `"high"`, `"medium"`, `"low"`, `"unknown"`.</Note>

***

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