> ## Documentation Index
> Fetch the complete documentation index at: https://docs.txshield.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Badge Integration

> Add a TxShield risk badge to any token page in under 5 minutes

## Overview

The TxShield badge gives your users an instant visual risk signal on any token page — no blockchain knowledge required on their end. One API call, one badge, full protection.

This is the fastest way to integrate TxShield into a DEX, screener, or token explorer.

***

## What It Looks Like

| Badge                 | Meaning                      | Risk Score             |
| --------------------- | ---------------------------- | ---------------------- |
| ✅ TxShield Verified   | No threats detected          | 0 – 20                 |
| ⚠️ TxShield Caution   | Moderate risk flags          | 21 – 70                |
| ❌ TxShield High Risk  | Honeypot or critical threat  | 71 – 100               |
| 🚨 TxShield Time Trap | Tax spikes in future windows | `isTimeHoneypot: true` |

***

## Quick Integration — Vanilla JavaScript

Drop this into any token page. Replace `YOUR_API_KEY` and call `renderTxShieldBadge()` with the token address and chain ID.

```javascript theme={null}
<div id="txshield-badge"></div>

<script>
async function renderTxShieldBadge(targetContractAddress, chainId = 1) {
  const badge = document.getElementById('txshield-badge');
  badge.innerHTML = '<span style="color:#94A3B8">⏳ Checking...</span>';

  try {
    const res = await fetch('https://api.txshield.xyz/api/honeypot/honeypot-checks', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ targetContractAddress, chainId })
    });

    const data = await res.json();

    if (!data.success) {
      badge.innerHTML = '<span style="color:#94A3B8">TxShield unavailable</span>';
      return;
    }

    const hp = data.honeypotResponse;

    // Time-delayed honeypot takes highest priority
    if (hp.isTimeHoneypot) {
      badge.innerHTML = '<span style="color:#DC2626">🚨 TxShield Time Trap</span>';
    } else if (hp.riskScore <= 20) {
      badge.innerHTML = '<span style="color:#16A34A">✅ TxShield Verified</span>';
    } else if (hp.riskScore <= 70) {
      badge.innerHTML = '<span style="color:#F59E0B">⚠️ TxShield Caution</span>';
    } else {
      badge.innerHTML = '<span style="color:#DC2626">❌ TxShield High Risk</span>';
    }

  } catch (err) {
    badge.innerHTML = '<span style="color:#94A3B8">TxShield unavailable</span>';
    console.error('[TxShield]', err);
  }
}

// Call on page load with your token address and chain
renderTxShieldBadge('0xTokenAddressHere', 1);
</script>
```

<Warning>
  Never expose your API key in client-side code in a production environment. Proxy the request through your own backend and keep the key in a server-side environment variable. See the pattern below.
</Warning>

***

## Production Pattern — Backend Proxy

Your frontend calls your own backend. Your backend holds the API key and calls TxShield.

```javascript theme={null}
// YOUR BACKEND — e.g. Express.js
app.post('/token-risk', async (req, res) => {
  const { targetContractAddress, chainId } = req.body;

  const response = await fetch('https://api.txshield.xyz/api/honeypot/honeypot-checks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.TXSHIELD_API_KEY}`
    },
    body: JSON.stringify({ targetContractAddress, chainId })
  });

  const data = await response.json();
  res.json(data);
});
```

```javascript theme={null}
// YOUR FRONTEND — calls your backend, not TxShield directly
async function renderTxShieldBadge(targetContractAddress, chainId = 1) {
  const badge = document.getElementById('txshield-badge');

  const res = await fetch('/token-risk', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ targetContractAddress, chainId })
  });

  const data = await res.json();
  const hp = data.honeypotResponse;

  if (hp.isTimeHoneypot || hp.riskScore > 70) {
    badge.innerHTML = '<span style="color:#DC2626">❌ High Risk</span>';
  } else if (hp.riskScore <= 20) {
    badge.innerHTML = '<span style="color:#16A34A">✅ Verified</span>';
  } else {
    badge.innerHTML = '<span style="color:#F59E0B">⚠️ Caution</span>';
  }
}
```

***

## React Component

```jsx theme={null}
import { useEffect, useState } from 'react';

const BADGES = {
  verified:  { label: '✅ TxShield Verified',   color: '#16A34A' },
  caution:   { label: '⚠️ TxShield Caution',    color: '#F59E0B' },
  high_risk: { label: '❌ TxShield High Risk',   color: '#DC2626' },
  time_trap: { label: '🚨 TxShield Time Trap',   color: '#DC2626' },
  loading:   { label: '⏳ Checking...',           color: '#94A3B8' },
  error:     { label: 'TxShield unavailable',    color: '#94A3B8' },
};

export function TxShieldBadge({ targetContractAddress, chainId = 1 }) {
  const [badge, setBadge] = useState('loading');

  useEffect(() => {
    async function check() {
      try {
        const res = await fetch('/token-risk', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ targetContractAddress, chainId })
        });
        const data = await res.json();

        if (!data.success) return setBadge('error');

        const hp = data.honeypotResponse;
        if (hp.isTimeHoneypot)    return setBadge('time_trap');
        if (hp.riskScore > 70)    return setBadge('high_risk');
        if (hp.riskScore > 20)    return setBadge('caution');
        setBadge('verified');
      } catch {
        setBadge('error');
      }
    }
    check();
  }, [targetContractAddress, chainId]);

  const { label, color } = BADGES[badge];
  return <span style={{ color, fontWeight: 600 }}>{label}</span>;
}

// Usage
<TxShieldBadge targetContractAddress="0xTokenAddressHere" chainId={1} />
```

***

## Deeper Integration

Want to show full risk details on hover, a modal breakdown, or a risk score bar alongside the badge? We can provide UI component templates for your stack.

Reach out via [X @txshield\_](https://x.com/txshield_) or [contactcodecommunity@gmail.com](mailto:contactcodecommunity@gmail.com) and mention your platform.

***

<CardGroup cols={2}>
  <Card title="Honeypot Endpoint" icon="spider-web" href="/evm-honeypot-copied-1">
    Full reference for the data powering the badge.
  </Card>

  <Card title="EVM Simulation" icon="flask" href="/evm-simulation-copied-1">
    Run deeper analysis including bytecode and transaction history.
  </Card>
</CardGroup>