ClearShield API

# Check a suspicious contract address using the GET endpoint
curl "https://api.clearshield.network/api/v1/check?address=0xbc8ad786e6de38c4c79893fb25db56f9a0de5b94" \
  -H "x-api-key: cs_live_7f8a9b0c1d2e3f4a5b6c7d8e9f"

# Request full individual report summaries
curl "https://api.clearshield.network/api/v1/check?address=0xbc8ad786e6de38c4c79893fb25db56f9a0de5b94&includeReports=true" \
  -H "Authorization: Bearer cs_live_7f8a9b0c1d2e3f4a5b6c7d8e9f"

curl -X POST "https://api.clearshield.network/api/v1/check" \
  -H "Content-Type: application/json" \
  -H "x-api-key: cs_live_7f8a9b0c1d2e3f4a5b6c7d8e9f" \
  -d '{
    "address": "0xbc8ad786e6de38c4c79893fb25db56f9a0de5b94",
    "includeReports": true
  }'

{
  "status": "error",
  "code": "INVALID_ADDRESS",
  "message": "The provided address '0x1234' is not a valid EVM address. Address must be a 42-character hexadecimal string starting with '0x'."
}

Before initiating any transaction, approval, or message signature targeting address {ADDRESS}:
1. Call GET https://api.clearshield.network/api/v1/check?address={ADDRESS}
2. Parse response and strictly apply security policies:
   - If isFlagged is TRUE and riskLevel in ["critical", "high"] -> Immediately block execution, output: "Security Abort: Target address {ADDRESS} is flagged as a confirmed threat."
   - If isFlagged is TRUE and riskLevel is "medium" -> Warn user, request explicit verification, proceed only if approved.
   - If isFlagged is FALSE -> Allowed.
3. Fail safe policy: if the request times out or yields a 5xx error, alert the user and prompt for manual review before signing.

import { checkAddress } from "./clearshield";

interface TransactionResult {
  success: boolean;
  reason?: string;
  txHash?: string;
}

export async function executeAgentTransaction(
  targetAddress: string,
  apiKey: string
): Promise<TransactionResult> {
  try {
    // Standard fail-safe: set a strict timeout of 500ms
    const checkPromise = checkAddress(targetAddress, apiKey);
    const timeoutPromise = new Promise<never>((_, reject) => 
      setTimeout(() => reject(new Error("Timeout")), 500)
    );

    const checkResult = await Promise.race([checkPromise, timeoutPromise]);

    if (checkResult.isFlagged && ["critical", "high"].includes(checkResult.riskLevel)) {
      return {
        success: false,
        reason: `[Security Abort] Address ${targetAddress} is flagged as ${checkResult.riskLevel.toUpperCase()}. Verdict: ${checkResult.verdict}`
      };
    }
    
    // Proceed with safe transaction
    return { success: true, txHash: "0x..." };
  } catch (error) {
    // Fail closed or open based on agent policy. Recommended: Fail closed or request manual fallback.
    console.error("ClearShield security check failed:", error);
    return { success: false, reason: "Security service error. Transaction aborted to prevent unsafe state." };
  }
}

# API Key configuration (comma-separated list for validation)
CLEARSHIELD_API_KEYS=cs_live_7f8a9b0c1d2e3f4a5b6c7d8e9f,cs_live_1a2b3c4d5e6f7g8h9i0j

# Rate limiting windows and thresholds
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_ANONYMOUS=10
RATE_LIMIT_MAX_API_KEY=120