What is a pre-trade token risk API?

Where the risk call belongs in an execution loop.

The check belongs after your system identifies a candidate token and before it signs, approves, routes, or submits a transaction. Running it after execution can explain a loss, but it cannot prevent one.

1. 01

   Validate the request boundary

   Accept only a token contract or mint and a supported chain. Reject wallet addresses, LP pairs, explorer URLs, and unsupported networks before the risk call.

2. 02

   Call before money moves

   Place the check after the trade candidate is known but before signing, routing, approving, or submitting the transaction.

3. 03

   Read the action first

   Use avoid, caution, or clear as the branch. Treat score, signals, confidence, freshness, and coverage as explanations—not substitute decisions.

4. 04

   Fail closed

   A timeout, malformed response, exhausted allowance, payment failure, or unavailable dependency stops the execution path unless another approved control takes over.

5. 05

   Log the receipt

   Persist the request identity, verdict action, observation identifier, evidence freshness, and the policy branch that followed for later review.

A decision contract is more useful than a score alone.

A score can rank risk, but an autonomous caller still needs to know what to do. VerdictSwarm returns three lower-case actions for code and presents them as AVOID, CAUTION, or CLEAR to people.

Solana and Base require different evidence boundaries.

The output contract can stay consistent across chains even when the underlying evidence differs. The request must use the chain's token identity and the response must make unavailable evidence visible.

What a production response should contain.

Decision

One explicit action suitable for a deterministic branch.

Evidence

Machine-readable signals that explain why the action was returned.

Uncertainty

Confidence, insufficient-data state, and coverage—not a silently optimistic score.

Freshness

When relevant data was generated or observed.

Identity

A stable observation or request identifier for logs and review.

Billing

Whether the call used a free key, prepaid credits, cache pricing, or x402.

Read the exact request, response, error, and discovery fields in the Verdict API v2 reference.

Minimal implementation.

Request a fast verdict for a Base contract, then make the action branch exhaustive. Keep the credential outside source control.

curl -sS -X POST https://api.vswarm.io/v2/verdict \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VS_API_KEY" \
  -d '{
    "address": "0x731814e491571A2e9eE3c5b1F7f3b962eE8f4870",
    "chain": "base",
    "level": "fast"
  }'

const response = await fetch("https://api.vswarm.io/v2/verdict", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.VS_API_KEY,
  },
  body: JSON.stringify({ address, chain, level: "fast" }),
});

if (!response.ok) throw new Error("Risk control unavailable");

const result = await response.json();
switch (result.verdict?.action) {
  case "avoid":
    return blockExecution(result);
  case "caution":
    return pauseOrEscalate(result);
  case "clear":
    return runNextIndependentControl(result);
  default:
    throw new Error("No valid execution action");
}

Why machine-payable access matters for agents.

A free key is useful for evaluation, and prepaid credits fit stable workloads. An x402 challenge lets a wallet-native caller discover a price, settle USDC, and retry without a subscription or manual account flow. The risk decision remains identical regardless of the payment rail.

Retrieve current levels, limits, supported chains, and prices from GET /v2/verdict/info. Do not hard-code commercial terms when live discovery is available.

Direct answers.