TokenGuard Base / Guides

Detect rug pull risk before buying a token (AI agent)

Rug pulls are not a single trick, so an agent that buys on a signal needs a gate that checks several levers and returns a decision it can act on without parsing prose.

The problem

A deployer can pull liquidity, mint new supply and dump it, flip a blacklist or fee switch, or change the contract logic behind an upgradeable proxy. A language model reading a token's website will not notice any of this. The signals live on-chain, in the bytecode, the owner's balance and the pool.

How /token-risk helps

/token-risk checks each lever and reports it as a flag with a severity of medium, high or critical. It reports whether ownership is renounced and, if not, the share of circulating supply the owner wallet holds (flagged above 5% and above 20%). It detects owner-only functions in the bytecode, an upgradeable proxy still under an owner's control, liquidity under $100k and under $10k, and, for Uniswap v2 style pools under $1M of liquidity, whether less than half of the LP tokens are burned. The flags sum to riskScore, and verdict is one of LOW_RISK, CAUTION, HIGH_RISK or AVOID, so the gate in your agent is a simple comparison.

Request and response

Example with the default sample token (AERO).

$ curl -i "https://tokenguard.imac2014ville.workers.dev/token-risk?token=0x940181a94A35A4569E4529A3CDfB74e38FD98631"
HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi4uLn0=   # base64 JSON: scheme "exact", network eip155:8453,
                                                  # asset USDC, amount 20000 (= $0.02)
# An x402 client signs the payment, then retries with a PAYMENT-SIGNATURE header.

The paid response (illustrative: field names and flag wording come from the service, the numbers are invented to show a risky token):

{
  "ok": true,
  "symbol": "XYZ",
  "verdict": "HIGH_RISK",
  "riskScore": 49,
  "flags": [
    { "severity": "high", "issue": "Very low liquidity (~$8200)" },
    { "severity": "high", "issue": "Owner-controllable functions present: mint(address,uint256), blacklist(address)" },
    { "severity": "medium", "issue": "Owner wallet holds 12.4% of circulating supply" },
    { "severity": "medium", "issue": "Only 0% of main LP tokens are burned: liquidity can be pulled" }
  ],
  "ownershipRenounced": false,
  "ownerHoldingsPct": 12.4
}

JavaScript with @x402/fetch

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.PRIVATE_KEY); // wallet holding USDC on Base
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(signer) }],
});
async function safeToBuy(token) {
  const res = await pay(`https://tokenguard.imac2014ville.workers.dev/token-risk?token=${token}`);
  const r = await res.json();
  const critical = r.flags.some(f => f.severity === "critical");
  return !critical && (r.verdict === "LOW_RISK" || r.verdict === "CAUTION");
}

Pricing

/token-risk costs $0.02 per call, so screening ten candidates costs $0.20. There is no API key and no account: each request is paid in USDC on Base over x402. Malformed input returns 400 and failed lookups return a non-2xx status, so those are not charged.

Limitations

More guides

TokenGuard Base overview/openapi.jsonllms.txt

Sister services