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

# DEX Token Screening

> Screen tokens in your DEX, aggregator, or swap UI for honeypots, hidden buy and sell taxes, holder concentration, and rug pull signals in real time.

You spot a honeypot token on trending. The chart looks perfect—steady climb, healthy volume. Your users buy in. When they try to sell, nothing happens. The contract blocks all sells except for the developer's wallet. \$3.2 million locked forever. This guide shows you how to screen tokens before your users get burned.

## Why Token Screening Matters

<CardGroup cols={3}>
  <Card title="Honeypot Detection" icon="jar-wheat">
    Block tokens that won't let users sell
  </Card>

  <Card title="Tax Analysis" icon="percent">
    Expose hidden buy/sell taxes before users swap
  </Card>

  <Card title="Rug Risk Assessment" icon="triangle-exclamation">
    Identify concentrated holdings and suspicious patterns
  </Card>
</CardGroup>

**Why DEX developers choose Webacy:**

* **Contract security analysis** — Detect honeypots, malicious functions, and rug mechanics
* **Hidden tax detection** — Find buy/sell taxes hidden in contract code
* **Holder concentration** — Identify tokens where insiders hold most supply
* **Liquidity analysis** — Assess pool depth and rug pull indicators
* **Trading Lite API** — Sub-second screening for real-time user protection
* **Multi-chain support** — ETH, Solana, Base, Arbitrum, BSC, and more

***

## Prerequisites

Before implementing token screening, ensure you have:

* A Webacy API key ([sign up here](https://developers.webacy.co/billing))
* Basic familiarity with REST APIs or the [Webacy SDK](../sdk/installation)
* Your swap interface's token selection and pre-swap flows identified

***

## Token Listing Due Diligence

Screen tokens before they appear on your platform.

### Contract Security Analysis

Get a comprehensive security analysis of any token contract.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/contracts/0xTokenAddress...?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 analysis = await client.contracts.analyze(
    '0xTokenAddress...',
    { chain: Chain.ETH }
  );

  console.log(`Risk score: ${analysis.overallRisk}/100`);
  console.log(`Is honeypot: ${analysis.isHoneypot}`);

  for (const vuln of analysis.vulnerabilities ?? []) {
    console.log(`[${vuln.severity}] ${vuln.name}: ${vuln.description}`);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.webacy.com/contracts/0xTokenAddress...",
      params={"chain": "eth"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  analysis = response.json()
  ```
</CodeGroup>

**Key fields to check:**

| Field               | Description             | Red Flag              |
| ------------------- | ----------------------- | --------------------- |
| `isHoneypot`        | Contract blocks sells   | Block immediately     |
| `overallRisk`       | 0-100 risk score        | > 70 requires review  |
| `vulnerabilities[]` | Security issues found   | Any critical severity |
| `hasProxyContract`  | Contract is upgradeable | Hidden risk           |

### Hidden Tax Detection

Many scam tokens hide excessive taxes that steal from users on every transaction.

<Warning>
  **The Tax Trap**: A token advertises "5% tax for marketing." The contract actually takes 90% on sells. Users buy in at market price and can only exit at 10 cents on the dollar.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/contracts/0xTokenAddress.../tax?chain=eth" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const tax = await client.contracts.getTax(
    '0xTokenAddress...',
    { chain: Chain.ETH }
  );

  console.log(`Buy tax: ${tax.buyTax}%`);
  console.log(`Sell tax: ${tax.sellTax}%`);
  console.log(`Transfer tax: ${tax.transferTax}%`);

  // Flag high taxes
  if (tax.sellTax > 10) {
    console.warn(`⚠️ High sell tax: ${tax.sellTax}%`);
  }

  if (tax.buyTax !== tax.sellTax) {
    console.warn('⚠️ Asymmetric taxes detected');
  }
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.webacy.com/contracts/0xTokenAddress.../tax",
      params={"chain": "eth"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  tax = response.json()
  ```
</CodeGroup>

**Tax warning thresholds:**

| Tax Level | Recommendation                        |
| --------- | ------------------------------------- |
| 0-5%      | Normal range                          |
| 5-10%     | Show warning to users                 |
| 10-25%    | Strong warning + require confirmation |
| > 25%     | Block or hide token                   |

### Holder Concentration Analysis

Identify tokens where insiders control most of the supply.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/holder-analysis/TokenMintAddress...?chain=sol" \
    -H "x-api-key: YOUR_API_KEY"
  ```

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

  const tradingClient = new TradingClient({ apiKey: process.env.WEBACY_API_KEY });

  const holders = await tradingClient.holderAnalysis.get(
    'TokenMintAddress...',
    { chain: Chain.SOL }
  );

  console.log(`Total holders: ${holders.totalHolders}`);
  console.log(`Top 10 concentration: ${holders.top10Percentage}%`);
  console.log(`Snipers detected: ${holders.sniperCount}`);
  console.log(`Bundlers detected: ${holders.bundlerCount}`);

  // Check for rug indicators
  if (holders.top10Percentage > 80) {
    console.warn('⚠️ Extreme concentration: Top 10 hold over 80%');
  }

  if (holders.sniperCount > 10) {
    console.warn('⚠️ High sniper activity at launch');
  }
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.webacy.com/holder-analysis/TokenMintAddress...",
      params={"chain": "sol"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  holders = response.json()
  ```
</CodeGroup>

**Holder red flags:**

| Metric        | Red Flag Threshold | What It Means                  |
| ------------- | ------------------ | ------------------------------ |
| Top 10 %      | > 80%              | Insiders can dump              |
| Sniper count  | > 10               | Coordinated buying at launch   |
| Bundler count | > 3                | Multiple wallets acting as one |
| Dev wallet %  | > 20%              | Developer can rug              |

***

## Real-Time User Warnings

Screen tokens in real-time when users try to swap.

### Pre-Swap Screening

Check tokens before users execute swaps.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/contracts/0xTokenAddress...?chain=eth" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  async function screenTokenBeforeSwap(tokenAddress: string, chain: Chain) {
    // Get contract analysis
    const analysis = await client.contracts.analyze(tokenAddress, { chain });

    // Get tax info
    const tax = await client.contracts.getTax(tokenAddress, { chain });

    const warnings: string[] = [];
    let shouldBlock = false;

    // Check for honeypot
    if (analysis.isHoneypot) {
      warnings.push('This token appears to be a honeypot - you may not be able to sell');
      shouldBlock = true;
    }

    // Check tax
    if (tax.sellTax > 25) {
      warnings.push(`Extreme sell tax detected: ${tax.sellTax}%`);
      shouldBlock = true;
    } else if (tax.sellTax > 10) {
      warnings.push(`High sell tax: ${tax.sellTax}%`);
    }

    // Check risk score
    if (analysis.overallRisk > 70) {
      warnings.push(`High risk score: ${analysis.overallRisk}/100`);
    }

    return {
      allowed: !shouldBlock,
      warnings,
      riskScore: analysis.overallRisk,
      taxes: {
        buy: tax.buyTax,
        sell: tax.sellTax,
      },
    };
  }
  ```

  ```python Python theme={null}
  def screen_token_before_swap(token_address: str, chain: str):
      # Get contract analysis
      analysis = requests.get(
          f"https://api.webacy.com/contracts/{token_address}",
          params={"chain": chain},
          headers={"x-api-key": "YOUR_API_KEY"}
      ).json()

      # Get tax info
      tax = requests.get(
          f"https://api.webacy.com/contracts/{token_address}/tax",
          params={"chain": chain},
          headers={"x-api-key": "YOUR_API_KEY"}
      ).json()

      return {
          "risk_score": analysis.get("overallRisk"),
          "is_honeypot": analysis.get("isHoneypot"),
          "buy_tax": tax.get("buyTax"),
          "sell_tax": tax.get("sellTax")
      }
  ```
</CodeGroup>

### Trading Lite for Speed

For high-volume DEXes, use Trading Lite for sub-second token screening.

<Warning>
  Trading Lite is currently available for **Solana only**. Use the standard contract analysis endpoints for EVM chains.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/trading-lite/PumpTokenAddress..." \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const quickAnalysis = await tradingClient.tradingLite.analyze('PumpTokenAddress...');

  console.log(`Risk score: ${quickAnalysis.riskScore}`);
  console.log(`Is honeypot: ${quickAnalysis.isHoneypot}`);
  console.log(`Liquidity: $${quickAnalysis.liquidity}`);

  // Quick pass/fail for swap UI
  const safeToSwap = quickAnalysis.riskScore < 50 && !quickAnalysis.isHoneypot;
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.webacy.com/trading-lite/PumpTokenAddress...",
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  quick = response.json()
  ```
</CodeGroup>

***

## Liquidity Analysis

Check if there's enough liquidity to actually execute trades.

### Pool Data

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/tokens/0xTokenAddress.../pools?chain=eth" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const pools = await tradingClient.tokens.getPools(
    '0xTokenAddress...',
    { chain: Chain.ETH }
  );

  for (const pool of pools.pools) {
    console.log(`DEX: ${pool.dex}`);
    console.log(`Liquidity: $${pool.liquidity.toLocaleString()}`);
    console.log(`Pair: ${pool.pairToken}`);
    console.log(`24h Volume: $${pool.volume24h.toLocaleString()}`);
  }

  // Check for low liquidity
  const totalLiquidity = pools.pools.reduce((sum, p) => sum + p.liquidity, 0);
  if (totalLiquidity < 10000) {
    console.warn('⚠️ Very low liquidity - high slippage expected');
  }
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.webacy.com/tokens/0xTokenAddress.../pools",
      params={"chain": "eth"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  pools = response.json()
  ```
</CodeGroup>

**Liquidity warning thresholds:**

| Liquidity  | Risk Level | User Guidance                 |
| ---------- | ---------- | ----------------------------- |
| > \$100k   | Low        | Normal trading                |
| $10k-$100k | Medium     | Warn about slippage           |
| $1k-$10k   | High       | Strong slippage warning       |
| \< \$1k    | Critical   | May be rug pull or dead token |

### Rug Pull Indicators

Combine multiple signals to detect potential rug pulls.

```typescript theme={null}
interface RugPullRisk {
  score: number; // 0-100
  indicators: string[];
  recommendation: 'safe' | 'caution' | 'avoid';
}

async function assessRugPullRisk(
  tokenAddress: string,
  chain: Chain
): Promise<RugPullRisk> {
  const indicators: string[] = [];
  let score = 0;

  // Get all data
  const [contract, tax, pools, holders] = await Promise.all([
    client.contracts.analyze(tokenAddress, { chain }),
    client.contracts.getTax(tokenAddress, { chain }),
    tradingClient.tokens.getPools(tokenAddress, { chain }),
    tradingClient.holderAnalysis.get(tokenAddress, { chain }),
  ]);

  // Check contract risks
  if (contract.isHoneypot) {
    indicators.push('Honeypot detected');
    score += 50;
  }

  if (contract.hasProxyContract) {
    indicators.push('Upgradeable contract');
    score += 15;
  }

  // Check taxes
  if (tax.sellTax > 25) {
    indicators.push(`Extreme sell tax: ${tax.sellTax}%`);
    score += 30;
  } else if (tax.sellTax > 10) {
    indicators.push(`High sell tax: ${tax.sellTax}%`);
    score += 15;
  }

  // Check liquidity
  const totalLiquidity = pools.pools.reduce((sum, p) => sum + p.liquidity, 0);
  if (totalLiquidity < 10000) {
    indicators.push(`Low liquidity: $${totalLiquidity.toLocaleString()}`);
    score += 20;
  }

  // Check holder concentration
  if (holders.top10Percentage > 80) {
    indicators.push(`High concentration: Top 10 hold ${holders.top10Percentage}%`);
    score += 25;
  }

  if (holders.sniperCount > 10) {
    indicators.push(`${holders.sniperCount} snipers at launch`);
    score += 10;
  }

  // Determine recommendation
  let recommendation: 'safe' | 'caution' | 'avoid' = 'safe';
  if (score >= 50) {
    recommendation = 'avoid';
  } else if (score >= 25) {
    recommendation = 'caution';
  }

  return {
    score: Math.min(score, 100),
    indicators,
    recommendation,
  };
}
```

***

## Complete Integration Workflow

### Token Listing Flow

```mermaid theme={null}
flowchart TD
    A[New Token Submitted] --> B[Contract Analysis]
    B --> C{Is Honeypot?}
    C -->|Yes| D["❌ REJECT Token"]
    C -->|No| E[Tax Analysis]
    E --> F{Sell Tax > 25%?}
    F -->|Yes| D
    F -->|No| G[Holder Analysis]
    G --> H{Top 10 > 90%?}
    H -->|Yes| D
    H -->|No| I[Pool Analysis]
    I --> J{Liquidity > $10k?}
    J -->|No| K["⚠️ Flag for Review"]
    J -->|Yes| L["✅ List Token"]
    K --> M{Manual Review}
    M -->|Approved| L
    M -->|Rejected| D
```

### Pre-Swap User Warning Flow

```mermaid theme={null}
flowchart TD
    A[User Selects Token] --> B{Cached Analysis?}
    B -->|Yes| C[Show Cached Warnings]
    B -->|No| D[Fetch Token Analysis]
    D --> C
    C --> E{Any Critical Issues?}
    E -->|Yes| F["🛑 Show Strong Warning"]
    E -->|No| G{Any Warnings?}
    G -->|Yes| H["⚠️ Show Caution Banner"]
    G -->|No| I["✅ Normal Swap UI"]
    F --> J{User Acknowledges?}
    J -->|Yes| K[Enable Swap]
    J -->|No| L[Cancel]
    H --> K
    I --> K
```

### Full TypeScript Implementation

<Accordion title="Complete DEX Token Screening Module">
  ```typescript theme={null}
  import { ThreatClient, TradingClient, Chain } from '@webacy-xyz/sdk';

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

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

  interface TokenScreeningResult {
    allowed: boolean;
    riskScore: number;
    warnings: Warning[];
    taxes: { buy: number; sell: number };
    liquidity: number;
    holderConcentration: number;
    recommendation: 'safe' | 'caution' | 'avoid' | 'block';
  }

  interface Warning {
    severity: 'info' | 'warning' | 'critical';
    message: string;
    category: string;
  }

  // Main screening function
  async function screenToken(
    tokenAddress: string,
    chain: Chain
  ): Promise<TokenScreeningResult> {
    const warnings: Warning[] = [];

    // Parallel fetch all data
    const [contract, tax, pools, holders] = await Promise.all([
      threatClient.contracts.analyze(tokenAddress, { chain }),
      threatClient.contracts.getTax(tokenAddress, { chain }),
      tradingClient.tokens.getPools(tokenAddress, { chain }),
      tradingClient.holderAnalysis.get(tokenAddress, { chain }).catch(() => null),
    ]);

    // Critical: Honeypot check
    if (contract.isHoneypot) {
      warnings.push({
        severity: 'critical',
        message: 'This token appears to be a honeypot. You may not be able to sell.',
        category: 'honeypot',
      });

      return {
        allowed: false,
        riskScore: 100,
        warnings,
        taxes: { buy: tax.buyTax, sell: tax.sellTax },
        liquidity: 0,
        holderConcentration: 0,
        recommendation: 'block',
      };
    }

    // Tax warnings
    if (tax.sellTax > 25) {
      warnings.push({
        severity: 'critical',
        message: `Extreme sell tax: ${tax.sellTax}%. You will lose most of your value when selling.`,
        category: 'tax',
      });
    } else if (tax.sellTax > 10) {
      warnings.push({
        severity: 'warning',
        message: `High sell tax: ${tax.sellTax}%`,
        category: 'tax',
      });
    }

    if (tax.buyTax > 10) {
      warnings.push({
        severity: 'warning',
        message: `High buy tax: ${tax.buyTax}%`,
        category: 'tax',
      });
    }

    // Liquidity warnings
    const totalLiquidity = pools.pools.reduce((sum, p) => sum + p.liquidity, 0);
    if (totalLiquidity < 1000) {
      warnings.push({
        severity: 'critical',
        message: `Very low liquidity: $${totalLiquidity.toLocaleString()}. May be unable to sell.`,
        category: 'liquidity',
      });
    } else if (totalLiquidity < 10000) {
      warnings.push({
        severity: 'warning',
        message: `Low liquidity: $${totalLiquidity.toLocaleString()}. Expect high slippage.`,
        category: 'liquidity',
      });
    }

    // Holder concentration warnings
    const holderConcentration = holders?.top10Percentage ?? 0;
    if (holders) {
      if (holders.top10Percentage > 90) {
        warnings.push({
          severity: 'critical',
          message: `Extreme concentration: Top 10 wallets hold ${holders.top10Percentage}%`,
          category: 'holders',
        });
      } else if (holders.top10Percentage > 70) {
        warnings.push({
          severity: 'warning',
          message: `High concentration: Top 10 wallets hold ${holders.top10Percentage}%`,
          category: 'holders',
        });
      }

      if (holders.sniperCount > 10) {
        warnings.push({
          severity: 'warning',
          message: `${holders.sniperCount} snipers detected at launch`,
          category: 'trading',
        });
      }

      if (holders.bundlerCount > 3) {
        warnings.push({
          severity: 'warning',
          message: `${holders.bundlerCount} bundler wallets detected`,
          category: 'trading',
        });
      }
    }

    // Determine recommendation
    const criticalCount = warnings.filter(w => w.severity === 'critical').length;
    const warningCount = warnings.filter(w => w.severity === 'warning').length;

    let recommendation: 'safe' | 'caution' | 'avoid' | 'block' = 'safe';
    if (criticalCount > 0) {
      recommendation = tax.sellTax > 50 ? 'block' : 'avoid';
    } else if (warningCount >= 2) {
      recommendation = 'caution';
    }

    return {
      allowed: recommendation !== 'block',
      riskScore: contract.overallRisk,
      warnings,
      taxes: { buy: tax.buyTax, sell: tax.sellTax },
      liquidity: totalLiquidity,
      holderConcentration,
      recommendation,
    };
  }

  // Quick screen for Solana (using Trading Lite)
  async function quickScreenSolana(tokenMint: string): Promise<{
    safe: boolean;
    riskScore: number;
    isHoneypot: boolean;
    liquidity: number;
  }> {
    const result = await tradingClient.tradingLite.analyze(tokenMint);

    return {
      safe: result.riskScore < 50 && !result.isHoneypot,
      riskScore: result.riskScore,
      isHoneypot: result.isHoneypot,
      liquidity: result.liquidity,
    };
  }

  // Batch screen for token lists
  async function screenTokenList(
    tokens: Array<{ address: string; chain: Chain }>
  ): Promise<Map<string, TokenScreeningResult>> {
    const results = new Map<string, TokenScreeningResult>();

    // Process in batches of 5 to avoid rate limits
    for (let i = 0; i < tokens.length; i += 5) {
      const batch = tokens.slice(i, i + 5);
      const batchResults = await Promise.all(
        batch.map(t => screenToken(t.address, t.chain))
      );

      batch.forEach((token, index) => {
        results.set(token.address, batchResults[index]);
      });
    }

    return results;
  }
  ```
</Accordion>

***

## Example Tokens for Testing

### Known Honeypots

| Address                                     | Chain | Description                             |
| ------------------------------------------- | ----- | --------------------------------------- |
| Test with newly deployed tokens on testnets | -     | Honeypots are constantly being deployed |

### High Tax Tokens

| Address                                 | Chain | Description                 |
| --------------------------------------- | ----- | --------------------------- |
| Various "reflection" or "rebase" tokens | -     | Often have hidden mechanics |

### Safe Tokens (for comparison)

| Address                                      | Chain | Description                   |
| -------------------------------------------- | ----- | ----------------------------- |
| `0xdAC17F958D2ee523a2206206994597C13D831ec7` | ETH   | USDT - no tax, high liquidity |
| `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | ETH   | USDC - verified, safe         |
| `0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599` | ETH   | WBTC - established token      |

<Info>
  **Testing tip**: For honeypot and tax testing, use tokens you find in real-time on DEX trending lists. Scam tokens are deployed constantly, so the best test data is fresh data.
</Info>

***

## API Quick Reference

| Endpoint                         | Use Case             | Response Time |
| -------------------------------- | -------------------- | ------------- |
| `GET /contracts/{address}`       | Contract analysis    | \~500ms       |
| `GET /contracts/{address}/tax`   | Tax detection        | \~300ms       |
| `GET /holder-analysis/{address}` | Holder distribution  | \~400ms       |
| `GET /tokens/{address}/pools`    | Liquidity pools      | \~300ms       |
| `GET /trading-lite/{address}`    | Quick analysis (SOL) | \~200ms       |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Your API Key" icon="key" href="https://developers.webacy.co/billing">
    Start screening tokens today
  </Card>

  <Card title="API Reference" icon="book" href="../api-reference/introduction">
    Complete endpoint documentation
  </Card>

  <Card title="Honeypots Explained" icon="jar" href="../glossary/honeypots">
    Deep dive on honeypot mechanics
  </Card>

  <Card title="Trading Client SDK" icon="code" href="../sdk/trading-client">
    SDK for holder analysis
  </Card>
</CardGroup>