presign-guard

# presign-guard

[![x402 payable](https://x402-doctor.fizzl.eu/badge.svg?url=https%3A%2F%2Fpresign-guard.fizzl.eu%2Fv1%2Ftoken)](https://x402-doctor.fizzl.eu/trust?url=https%3A%2F%2Fpresign-guard.fizzl.eu%2Fv1%2Ftoken) · [Live status](https://x402-doctor.fizzl.eu/status)

A pre-sign risk check for AI agents. Before an agent signs a transaction, approval, or EIP-712 signature, it pays a few cents per call over [x402](https://x402.org) and gets back a **green / orange / red** verdict with machine-readable reason codes. Optionally, it also gets a plain-language explanation in Dutch or English.

**Watch the 1-minute explainer:** [presign-guard.fizzl.eu/media/explainer.mp4](https://presign-guard.fizzl.eu/media/explainer.mp4)

[![presign-guard explainer video](public/media/explainer.jpg)](https://presign-guard.fizzl.eu/media/explainer.mp4)

**New: the token verdict in 45 seconds:** [presign-guard.fizzl.eu/media/token.mp4](https://presign-guard.fizzl.eu/media/token.mp4)

Part of [Klaartaal](https://github.com/Fizzl13/SmartContractExplainer) by [FIZZL AI](https://fizzl.eu).

## Use it in a few lines: `presign-guard-wallet`

For agents on [viem](https://viem.sh), the npm package [`presign-guard-wallet`](https://www.npmjs.com/package/presign-guard-wallet) wraps the wallet so every `sendTransaction`, `writeContract` and `signTypedData` is checked first: green signs, orange stops (or asks), red never signs. Each verdict's signed receipt is verified before the wallet acts.

```js
import { guardWallet } from "presign-guard-wallet";

const wallet = guardWallet(walletClient, { pay, onOrange: "stop" }); // pay = an x402 fetch, $0.01 per check
await wallet.writeContract({ address: token, abi, functionName: "approve", args: [spender, amount] });
```

`npm install presign-guard-wallet viem @x402/fetch @x402/evm` · [source and options](https://github.com/Fizzl13/x402-examples/tree/main/guard-wallet)

## Endpoints

| Route | Price | Returns |
|---|---|---|
| `POST /v1/check` | $0.01 USDC | Verdict, reason codes, decoded subject |
| `POST /v1/check/explain` | $0.03 USDC | The same, plus a plain-language explanation (`lang: "nl"` or `"en"`) |
| `GET /v1/token?chain=…&address=…` | $0.01 USDC, Base or Solana | Token verdict: grade, reason codes, one-line summary, market data (see below) |
| `GET /v1/approvals?chain=…&address=…` | $0.02 USDC, Base or Solana | Wallet approval audit: every open token approval, its spender, and which to revoke (see below) |
| `GET /v1/credits/100`, `/v1/credits/1000` | $0.80 / $7.00 USDC | A pack of prepaid credits (20% / 30% off): see [Credit packs](#credit-packs) |
| `GET /v1/credits` | free | Pack prices, credit cost per call, and your balance (with the `x-credit-key` header) |
| `POST /mcp` | free / paid | MCP server (Streamable HTTP): see below |
| `POST /feedback` | free | Report a bug or a missing feature: see [Feedback](#feedback) |
| `GET /health` | free | Liveness |
| `GET /openapi.json` | free | OpenAPI 3.1 spec with prices (`x-payment-info`) |
| `GET /.well-known/x402` | free | x402 discovery manifest |

Payment is x402 v2 with the `exact` scheme, in USDC on Base (the token verdict and the approval audit also on Solana). The 402 carries Bazaar discovery metadata (input example, input and output schema), and the challenge is mirrored into the JSON body for clients that don't read the `PAYMENT-REQUIRED` header. **You are never charged for an error.** Invalid requests (400) and upstream outages (503) cancel settlement, and they always return `verdict: null`, never a guessed verdict.

## Credit packs

Agents that call presign-guard often can prepay: one x402 payment of **$0.80 for 100 credits** or **$7.00 for 1000 credits** (20% and 30% off), valid for a year. A credit is $0.01 of checks: `POST /v1/check` and `GET /v1/token` cost 1, `GET /v1/approvals` 2, `POST /v1/check/explain` 3.

```bash
# 1. Buy a pack (any x402 client); the answer holds your key
GET /v1/credits/100   ->  { "credit_key": "pgc_…", "credits": 100, "expires_at": "…" }

# 2. Send the key instead of paying; no new payment needed
curl -X POST https://presign-guard.fizzl.eu/v1/check -H 'x-credit-key: pgc_…' -H 'content-type: application/json' -d '{…}'
#    -> the verdict (signed as usual), with headers x-credit-status: paid and x-credits-remaining: 99

# 3. Balance
curl https://presign-guard.fizzl.eu/v1/credits -H 'x-credit-key: pgc_…'
```

A call that fails (400 or 5xx) gives its credits back. With no key, a malformed or unknown key, or too few credits, the call gets the normal 402 (`x-credit-status` says why), so a client can always fall back to paying per call. Keep the key secret: anyone who has it can spend the credits, and it cannot be recovered (only a SHA-256 of it is stored). Credits work over HTTP; MCP tools are paid per call.

Packs are only offered when balances persist: set `CREDITS_REDIS_URL` (a persistent Redis, for example a free Upstash database; Render only). Without it the credit routes don't exist.

## MCP

`https://presign-guard.fizzl.eu/mcp` is an MCP server (Streamable HTTP, stateless) for Claude, Cursor and agent frameworks, listed in the official MCP registry as `io.github.Fizzl13/presign-guard`.

Using Claude Code for trading agents? See [Pre-trade checks for Claude Code agents](docs/claude-code-pre-trade.md): a token check and an Ichimoku trend check before every order, with a ready-made `CLAUDE.md` rule.

| Tool | Price | Returns |
|---|---|---|
| `presign_quick_check` | free, 10 calls/hour | The verdict only (green, orange or red) |
| `presign_check` | $0.01 USDC via x402 | The full verdict and reason codes, as `POST /v1/check` |
| `presign_check_explain` | $0.03 USDC via x402 | The same plus a plain-language explanation, as `POST /v1/check/explain` |
| `token_quick_verdict` | free, shares the 10 calls/hour | The token verdict and grade only |
| `token_verdict` | $0.01 USDC via x402 | The full token verdict, as `GET /v1/token` |
| `wallet_approvals` | $0.02 USDC via x402 | The wallet approval audit, as `GET /v1/approvals` |
| `feedback` | free | Report a bug or a missing feature, as `POST /feedback` |

The paid tools are paid inside the MCP call with the x402 MCP transport (`_meta["x402/payment"]`), on Base (`token_verdict` and `wallet_approvals` also on Solana), to the same payout wallets as the HTTP routes. Invalid input is refused before payment, and a failed check is not charged.

## Token verdict

[![Token verdict video](public/media/token.jpg)](https://presign-guard.fizzl.eu/media/token.mp4)

`GET /v1/token?chain=solana&address=<mint>` (or `chain=base|ethereum|arbitrum|optimism|polygon|bsc` with a `0x` token contract) answers one question before an agent buys, holds or accepts a token: is the token itself a trap?

```json
{
  "verdict": "orange",
  "grade": "RISKY",
  "one_liner": "RISKY: 1% transfer fee; $21k liquidity; 1 h old (+2 more)",
  "reasons": [{ "code": "TRANSFER_FEE", "severity": "orange", "details": { "feePct": 1 } }, "…"],
  "token": { "chain": "solana", "address": "…", "name": "…", "symbol": "…" },
  "market": { "priceUsd": 0.0004, "liquidityUsd": 21000, "marketCapUsd": 400000, "volume24hUsd": 90000, "firstPairAt": "…", "ageSeconds": 3600, "url": "https://dexscreener.com/…" },
  "sources": ["goplus", "dexscreener", "rugcheck"],
  "checkedAt": "…"
}
```

Grades: `SAFE` (green), `CAUTION` (one orange reason), `RISKY` (two or more), `AVOID` (red). The one-liner states facts only.

| Severity | Codes |
|---|---|
| red | `RUGGED`, `NON_TRANSFERABLE`, `MALICIOUS_AUTHORITY`; EVM: `TOKEN_HONEYPOT`, `TOKEN_AIRDROP_SCAM`, `TOKEN_IMPERSONATION` |
| orange | `AI_TOKEN_IMPERSONATION` (AI second opinion via TypeSafe Jev, when the server has it set up: the name or symbol pretends to be another token; never red), `MINT_AUTHORITY_ACTIVE`, `FREEZE_AUTHORITY_ACTIVE`, `PERMISSIONED_TOKEN`, `BALANCE_MUTABLE`, `CLOSABLE`, `TRANSFER_HOOK`, `TRANSFER_FEE`, `HIGH_TRANSFER_FEE` (≥10%), `TRANSFER_FEE_UPGRADABLE`, `LP_NOT_LOCKED` (<50% locked, token younger than 30 days), `LOW_LIQUIDITY` (<$50k), `NO_DEX_MARKET`, `NEW_TOKEN` (<24 h), `TOP_HOLDERS_CONCENTRATED` (top holder >20% or top 10 >50%, pools and locked accounts excluded; on EVM only wallets count, not contracts); EVM: the GoPlus token codes of `/v1/check` (`TOKEN_HIGH_TAX`, `TOKEN_UNVERIFIED`, …), `TOKEN_CANNOT_BUY` and `TOKEN_PAUSED` (transfers are paused right now) |
| info | `MUTABLE_METADATA`, `GENESIS_LAUNCH_ESCROW`, `NO_SOCIALS`, `TOKEN_ON_TRUST_LIST`, `NO_SECURITY_DATA`, `RUGCHECK_DANGER`, `RUGCHECK_UNAVAILABLE`, `LP_NOT_LOCKED` on older tokens, on trust-list tokens (USDC, USDT, WETH): the issuer's powers, `LP_NOT_LOCKED`, `LOW_LIQUIDITY` and `NO_DEX_MARKET` (DexScreener undercounts quote assets); EVM: `TOKEN_PAUSABLE` and `TOKEN_BLACKLIST` (the issuer can pause transfers or blacklist holders; a green one-liner says so) |

A permissioned Solana token (Token ACL, sRFC 37, which Metaplex MPL-3643 builds on) is a Token-2022 mint whose new token accounts start frozen and whose freeze authority is a Token ACL `MintConfig` PDA; an issuer-chosen gate program decides which wallets are thawed. When GoPlus reports a freeze authority, the verdict reads the mint and its `MintConfig` from a Solana RPC (`SOLANA_RPC_URL`, default the public mainnet endpoint) and reports one `PERMISSIONED_TOKEN` reason instead of `FREEZE_AUTHORITY_ACTIVE`: only approved wallets can hold or send it, so a buyer who isn't approved may not be able to sell. The response then carries a `permissioned` block (gate program, config authority, default-frozen, permanent delegate, pausable). A permanent delegate stays a separate `BALANCE_MUTABLE`.

When the top holders of a Solana token look concentrated, the verdict first asks the chain who owns them: a Metaplex Genesis launch bucket (an account of program `GNS1S5J5AspKXgpjz6SvKL66kPaKWAhaGRhCqPRxii2B`, holding supply until the launch distributes it) is not a whale. It is left out of the count and reported as `GENESIS_LAUNCH_ESCROW` with its