The pre-trade token risk gate for agents that move money

What you get

The decision is nested at verdict.action. This recorded v2 response is generated from the checked-in contract fixture; payment identifiers are removed while required schema fields remain.

{
  "schema_version": "1.0",
  "request": {
    "address": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
    "chain": "solana",
    "level": "fast",
    "include": []
  },
  "verdict": {
    "action": "caution",
    "score": 55,
    "grade": "D",
    "risk_level": "high",
    "confidence": 0.8,
    "summary": "Analysis timed out — using available on-chain data only."
  },
  "signals": [
    {
      "id": "honeypot_simulation",
      "category": "security",
      "severity": "critical",
      "pass": true,
      "value": "ok",
      "detail": "Sell simulation passed."
    },
    {
      "id": "mint_authority",
      "category": "security",
      "severity": "critical",
      "pass": true,
      "value": "revoked",
      "detail": "Mint authority revoked — cannot inflate supply."
    },
    {
      "id": "freeze_authority",
      "category": "security",
      "severity": "high",
      "pass": true,
      "value": "revoked",
      "detail": "Freeze authority revoked — holders cannot be frozen."
    },
    {
      "id": "top10_holder_concentration",
      "category": "distribution",
      "severity": "high",
      "pass": false,
      "value": 67,
      "detail": "Top-10 wallets hold 67.0% of supply."
    },
    {
      "id": "contract_verified",
      "category": "transparency",
      "severity": "medium",
      "pass": true,
      "value": "verified",
      "detail": "Contract source code is publicly verified."
    },
    {
      "id": "liquidity_vs_mcap",
      "category": "liquidity",
      "severity": "info",
      "pass": true,
      "value": 0.0642,
      "detail": "Liquidity ratio: 6.42% of market cap."
    }
  ],
  "agents": [
    {
      "name": "FreeTierAI",
      "score": 5.5,
      "sentiment": "neutral",
      "key_findings": [],
      "reasoning": null
    }
  ],
  "data_freshness": {
    "onchain_age_seconds": 6,
    "market_age_seconds": 6,
    "social_age_seconds": null
  },
  "data_confidence": 1,
  "insufficient_data": false,
  "lifecycle": null,
  "timing": null,
  "observation_id": "4434bc13-5b0d-42bc-88f4-7df50e961b66",
  "cached": false,
  "generated_at": "2026-07-18T18:47:07.801107Z",
  "latency_ms": 5268,
  "billing": {
    "rail": "free",
    "amount_usdc": "0",
    "tx": null,
    "degraded": true,
    "retry_voucher": null
  }
}

Service levels

Pricing is served live at GET /v2/verdict/info. The values shown were verified on 2026-07-18; cache hits then cost 20% of the fresh price. Verify live before hardcoding.

Prepaid credits

For higher prepaid usage, pass a funded signed key. No X-PAYMENT header is needed:

# Pass your key in the X-API-Key header (no X-PAYMENT header needed)
curl -s -X POST https://api.vswarm.io/v2/verdict \
  -H "Content-Type: application/json" \
  -H "X-VS-Integration: web-docs" \
  -H "X-API-Key: vs1_agent_your-key-id_your-sig" \
  -d '{"address":"0x6982508145454Ce325dDbE47a25d4ec3d2311933","chain":"base","level":"fast"}'

Check your balance without spending a call:

curl -s https://api.vswarm.io/v2/credits/balance \
  -H "X-VS-Integration: web-docs" \
  -H "X-API-Key: vs1_agent_your-key-id_your-sig"

Python client (x402 + credits)

import httpx
from x402.client import handle_402  # pip install x402

async def get_verdict(address: str, chain: str, level: str = "fast") -> dict:
    url = "https://api.vswarm.io/v2/verdict"
    payload = {"address": address, "chain": chain, "level": level}

    async with httpx.AsyncClient() as client:
        resp = await client.post(url, json=payload, headers={"X-VS-Integration": "python-x402"})
        if resp.status_code == 402:
            resp = await handle_402(resp, client, wallet_private_key=WALLET_KEY)
        resp.raise_for_status()
        return resp.json()

verdict = await get_verdict("0x6982508145454Ce325dDbE47a25d4ec3d2311933", "base")
action = verdict["verdict"]["action"]  # "avoid" | "caution" | "clear"

Error codes

All errors return structured JSON with a stable code field.

Agent Commerce Protocol (ACP)

The same pre-trade decision is available as a Virtuals ACP offering — preTradeTokenRiskCheck, $0.05 per check, avoid / caution / clear with score, top signals, and report URL. Any agent on Virtuals Protocol can request a check and pay with USDC, no API key needed.