// Developer surface

One token risk API. Three depths. No SDK required.

Put an explicit token-risk decision before execution. The same contract works with prepaid credits, x402, ACP, or MCP.

curl -sS -X POST https://api.vswarm.io/v2/verdict \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VS_API_KEY" \
  -d '{"address":"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN","chain":"solana","level":"fast","include":[]}'
Pinned live responseHTTP 200 · 3099ms observed
{
  "schema_version": "1.1",
  "request": {
    "address": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
    "chain": "solana",
    "level": "fast",
    "include": []
  },
  "verdict": {
    "action": "caution",
    "score": 82,
    "grade": "A",
    "risk_level": "low",
    "confidence": 1,
    "summary": "Jupiter (JUP) is a well-established major Solana ecosystem token with strong financials, a long operating history, and safe authority settings."
  },
  "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": 66.2,
      "detail": "Top-10 wallets hold 66.2% 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": "high",
      "pass": false,
      "value": 0.0033,
      "detail": "Very low liquidity ratio: 0.33% of market cap."
    }
  ],
  "agents": [
    {
      "name": "FreeTierAI",
      "score": 8.2,
      "sentiment": "bullish",
      "key_findings": [
        "Token age is 919 days, indicating a long-standing and established project.",
        "Market cap stands at $607.5M with $2.0M in liquidity, reflecting mature market operations.",
        "Mint and freeze authorities have both been revoked, eliminating centralized supply manipulation risks.",
        "Missing holder metrics are typical data provider anomalies for high-volume native assets and do not negate foundational safety."
      ],
      "reasoning": null
    }
  ],
  "data_freshness": {
    "onchain_age_seconds": 2911,
    "market_age_seconds": 3,
    "social_age_seconds": 3,
    "basis": "observed"
  },
  "token": {
    "name": "Jupiter",
    "symbol": "JUP",
    "price_usd": 0.1829,
    "liquidity_usd": 2021849.5,
    "mcap_usd": 607509009,
    "fdv_usd": 1280767814,
    "volume_24h_usd": 316009.15,
    "holder_count": 827230,
    "age_days": 919,
    "top10_holder_pct": 66.22
  },
  "data_quality": {
    "required_missing": [
      "Holder data"
    ],
    "optional_missing": [],
    "warnings": [
      "Required data missing: Holder data unavailable during initial scan. Treat as missing data, not a negative signal.",
      "Holder count reported as 0 with mcap $607.5M — likely API limitation, not indicative of actual holder base",
      "Top 10 holder concentration unavailable — data source did not return holder distribution. Do not penalize for missing data."
    ],
    "degraded_agents": []
  },
  "liquidity_exposure_cap_usd": 10000,
  "data_confidence": 1,
  "insufficient_data": false,
  "lifecycle": null,
  "timing": null,
  "observation_id": "9cd71c81-86a4-4380-9eb0-d7e482948e98",
  "cached": false,
  "generated_at": "2026-08-07T16:55:18.090125Z",
  "latency_ms": 3099,
  "billing": {
    "rail": "free",
    "amount_usdc": "0",
    "tx": null,
    "degraded": false,
    "retry_voucher": null
  }
}

Pick a depth per call

Spend more analysis only where policy calls for it.

Triage

$0.001

Latency
1s p95 target
Analysts
No staged panel
Cache hit
$0.0002

Deterministic pre-checks with no model spend.

  • Explicit decision contract
  • Deterministic risk checks
  • No model spend
  • Observation receipt

Use for broad screening before a more expensive call.

Fast

$0.01

Default
Latency
2.5s p95 target
Analysts
No staged panel
Cache hit
$0.002

Cached data, heuristics, and single-model adjudication.

  • Explicit decision contract
  • Full signal detail
  • Single-model adjudication
  • Observation receipt

Use as the default gate for routine execution.

Deep

$0.03

Latency
45s p95 target
Analysts
6
Cache hit
$0.006

The configured specialist swarm with cross-examination.

  • Explicit decision contract
  • Configured specialist panel
  • Adversarial cross-examination
  • Per-analyst evidence

Use for ambiguous or higher-stakes assets.

Prepaid credits

Attach a funded API key

Use X-API-Key for predictable bearer-key billing and balance tracking.

x402 USDC

Pay the challenge and retry

Settle the returned challenge on solana or base without creating an account.

Four ways in

Choose the rail your runtime already speaks.

SurfaceStatusCost shapeBest for
x402LIVEPer-call USDCWallet-native callers that can settle a payment challenge.
Credits / API keyLIVEPrepaid balanceBots and integrations that prefer bearer-key billing.
Virtuals ACPLIVE$0.05 per checkVirtuals agents hiring preTradeTokenRiskCheck.
MCPPUBLISHED · VERIFIEDUses the configured API railMCP-compatible runtimes using the PyPI package or official MCP Registry entry.

Contract shape

Request and response schema.

Request

addressstring

Token mint or contract address.

chainstring

Supported chain identifier.

levelstring

Analysis depth for this call.

includearray

Optional result expansions.

Response

schema_versionstring

Version of the response contract.

requestobject

Normalized request that produced this result.

verdictobject

Authoritative action and supporting score.

signalsarray

Machine-readable evidence ordered by the service.

agentsarray

Analyst output when the selected depth runs it.

data_freshnessobject

Observed source ages at generation time.

tokenobject

Absolute market measurements (price, liquidity, mcap, volume, holders, age) read at verdict time.

data_qualityobject

What the pipeline could not fetch or evaluate: required and optional sources missing, warnings, and degraded agents. Empty lists mean full coverage.

liquidity_exposure_cap_usdnumber

Field returned by the pinned live contract.

data_confidencenumber

Confidence supported by available coverage.

insufficient_databoolean

Whether coverage was too weak for a complete result.

lifecyclenull

Requested lifecycle expansion or null.

timingnull

Requested timing expansion or null.

observation_idstring

Identifier for the decision receipt.

cachedboolean

Whether the verdict came from response cache.

generated_atstring

UTC generation timestamp.

latency_msnumber

Observed request latency.

billingobject

Rail, charge, and recovery details.

Failure modes

Errors are branch conditions, not permission to continue.

CodeHTTPAgent action
invalid_address400Validate the address against the selected chain and stop the trade.
unsupported_chain400Route only supported-chain assets here; stop on every other chain.
level_unavailable400Read the enabled levels from service discovery and halt unless policy permits another depth.
payment_required402Pay the top-level x402 challenge or attach a funded key, then retry the identical request.The x402 challenge is returned at the top level.
payment_invalid402Replace the payment proof or key. Do not retry unchanged credentials.
rate_limited429Wait for details.retry_after_s or Retry-After, then retry with bounded backoff.Response includes details.retry_after_s and the Retry-After header.
upstream_data_unavailable503Halt execution and surface the dependency failure. Never fail open.
internal_error500Halt, use a retry voucher when returned, and alert if the retry fails.

Limits and caching

Budget for bursts. Price cache hits correctly.

Per payer
5 requests / second
Burst
20 requests
triage cache hit
$0.0002
fast cache hit
$0.002
deep cache hit
$0.006

Execution policy

Never fail open.

If the verdict is missing, unavailable, or invalid, stop the money movement and surface the failure.

Build the gate