{
  "markdown": "# TokenSafe\n\nSolana token safety scanner. Deterministic on-chain analysis, cryptographically signed, behind x402 micropayments.\n\n**Status: shipping.** Live on mainnet behind x402 micropayments. No CI workflows in this repo; the deploy is Railway-side.\n\n**$0.02/request in USDC. No API keys, no accounts, no opaque ML.** Every verdict is read straight from chain state and Ed25519-signed — so anyone can verify TokenSafe said it, at [`/v1/verify`](#verifiable-attestations). Aggregators reselling third-party grades can't do that. Payment is authentication.\n\n**Try it:** [scry.app](https://scry-production.up.railway.app/) (web) · [@ScryTokenBot](https://t.me/ScryTokenBot) (Telegram)\n\n## What It Checks\n\n| Check            | What It Detects                          | Source                         |\n| ---------------- | ---------------------------------------- | ------------------------------ |\n| Mint authority   | Supply inflation risk                    | RPC `getAccountInfo`           |\n| Freeze authority | Token seizure risk                       | RPC `getAccountInfo`           |\n| Top holders      | Concentration / rug risk                 | RPC `getTokenLargestAccounts`  |\n| Liquidity        | Sellability, price impact                | Jupiter quote API              |\n| LP locks         | Liquidity removal risk                   | RPC + 9 known locker programs  |\n| Honeypot         | Can't-sell detection                     | Jupiter buy/sell comparison    |\n| Metadata         | Name/image bait-and-switch               | RPC Metaplex PDA               |\n| Token age        | Fresh launch signal                      | RPC `getSignaturesForAddress`  |\n| Token-2022       | Transfer fees, permanent delegate, hooks | TLV extension parsing          |\n\nRug risk score 0-100 where every point is traceable to on-chain state. No third-party security APIs.\n\n## Quick Start\n\n### Free lite check (no payment needed)\n\n```bash\ncurl https://tokensafe-production.up.railway.app/v1/check/lite?mint=So11111111111111111111111111111111111111112\n```\n\nReturns rug risk score, risk level, and summary. Rate-limited to 30/min per IP.\n\n### Full paid check (x402)\n\n```bash\n# First request returns 402 with payment requirements\ncurl -s https://tokensafe-production.up.railway.app/v1/check?mint=So11111111111111111111111111111111111111112\n\n# Use any x402-compatible client to handle payment automatically\n```\n\nAny x402-compatible wallet/client handles the payment flow automatically. $0.02 USDC per request.\n\n### MCP (Claude Code, Cursor, Windsurf)\n\n```bash\n# Claude Code plugin (recommended)\n/plugin marketplace add ampactor-labs/tokensafe\n/plugin install tokensafe@ampactor-labs\n\n# Or direct MCP server add\nclaude mcp add tokensafe --transport http https://tokensafe-production.up.railway.app/mcp\n```\n\nOne tool: `solana_token_safety_check` — free rug risk score, summary, and Token-2022 detection. Full report via x402 REST API.\n\n### Discovery\n\nMachine-readable service descriptions for automated agent + aggregator discovery:\n\n```bash\ncurl https://tokensafe-production.up.railway.app/openapi.json          # OpenAPI 3.1 (x-x402 per paid op)\ncurl https://tokensafe-production.up.railway.app/.well-known/x402      # x402 manifest (x402scan compat)\ncurl https://tokensafe-production.up.railway.app/discovery/resources   # x402 Bazaar resource list\ncurl https://tokensafe-production.up.railway.app/llms.txt              # agent guide (markdown)\n```\n\nAll discovery documents are generated from a single source of truth\n(`src/discovery/catalog.ts`), so advertised prices can never drift from the\nprices the x402 payment gate actually charges.\n\n## Endpoints\n\n| Endpoint                                 | Price       | Auth | Rate Limit |\n| ---------------------------------------- | ----------- | ---- | ---------- |\n| `GET /v1/check?mint=<ADDR>`              | $0.02 USDC  | x402 | 60/min/IP  |\n| `POST /v1/check/batch/{small,medium,large}` | $0.07 / $0.20 / $0.40 | x402 | 60/min/IP |\n| `POST /v1/audit/{small,standard}`        | $0.15 / $0.60 | x402 | 60/min/IP |\n| `POST /v1/subscribe`                     | $49 USDC    | x402 | 60/min/IP  |\n| `GET /v1/check/lite?mint=<ADDR>`         | Free        | None | 30/min/IP  |\n| `GET /v1/decide?mint=<ADDR>&threshold=N` | Free        | None | 30/min/IP  |\n| `POST /v1/verify`                        | Free        | None | 60/min/IP  |\n| `GET /health`                            | Free        | None | 60/min/IP  |\n| `POST /mcp`                              | Free        | None | 30/min/IP  |\n| `GET /.well-known/x402`                  | Free        | None | —          |\n| `GET /openapi.json`                      | Free        | None | —          |\n| `GET /discovery/resources`              | Free        | None | —          |\n| `GET /llms.txt`                          | Free        | None | —          |\n\n`POST /v1/subscribe` pays once via x402 and returns a 30-day Pro API key\n(6000 checks/mo, 200 req/min) — send it as `X-API-Key` to skip per-call payment.\n\n## Response (Full Check)\n\n```json\n{\n  \"mint\": \"So11111111111111111111111111111111111111112\",\n  \"name\": \"Wrapped SOL\",\n  \"symbol\": \"SOL\",\n  \"risk_score\": 5,\n  \"risk_level\": \"LOW\",\n  \"summary\": \"Low risk. Mint/freeze authorities active but deeply liquid with distributed holders.\",\n  \"checks\": {\n    \"mint_authority\": {\n      \"status\": \"ACTIVE\",\n      \"authority\": \"...\",\n      \"risk\": \"SAFE\"\n    },\n    \"freeze_authority\": {\n      \"status\": \"RENOUNCED\",\n      \"authority\": null,\n      \"risk\": \"SAFE\"\n    },\n    \"top_holders\": { \"top_10_percentage\": 12.5, \"risk\": \"SAFE\" },\n    \"liquidity\": {\n      \"liquidity_rating\": \"DEEP\",\n      \"lp_locked\": true,\n      \"risk\": \"SAFE\"\n    },\n    \"honeypot\": { \"can_sell\": true, \"risk\": \"SAFE\" },\n    \"metadata\": { \"mutable\": false, \"risk\": \"SAFE\" },\n    \"token_age_hours\": 8760\n  },\n  \"changes\": null,\n  \"alerts\": []\n}\n```\n\nDelta detection is automatic — `changes` and `alerts` populate when a token's state differs from its previous check.\n\n## Response (Lite Check)\n\n```json\n{\n  \"mint\": \"So11111111111111111111111111111111111111112\",\n  \"name\": \"Wrapped SOL\",\n  \"symbol\": \"SOL\",\n  \"risk_score\": 5,\n  \"risk_level\": \"LOW\",\n  \"summary\": \"Low risk. ...\",\n  \"authorities_renounced\": true,\n  \"trusted_authority\": false,\n  \"has_liquidity\": true,\n  \"can_sell\": true,\n  \"data_confidence\": \"complete\",\n  \"is_token_2022\": false,\n  \"has_risky_extensions\": false,\n  \"full_report\": {\n    \"url\": \"https://tokensafe-production.up.railway.app/v1/check?mint=So11111111111111111111111111111111111111112\",\n    \"price_usd\": \"$0.02\",\n    \"payment_protocol\": \"x402\",\n    \"includes\": \"authority addresses, holder breakdown, LP lock status, honeypot details, delta detection\"\n  }\n}\n```\n\n## x402 Payment Flow\n\n```\nAgent  →  GET /v1/check?mint=<TOKEN>\nServer →  402 + PAYMENT-REQUIRED header (base64 JSON)\nAgent  →  wallet auto-signs $0.02 USDC transfer\nAgent  →  GET /v1/check?mint=<TOKEN> + PAYMENT-SIGNATURE header\nServer →  200 + full analysis + PAYMENT-RESPONSE receipt\n```\n\nUSDC settles to the operator's Solana wallet via the Coinbase CDP facilitator\n(configurable with `FACILITATOR_URL`).\n\n## Verifiable attestations\n\nEvery full check is Ed25519-signed over `{mint, checked_at, rpc_slot, risk_score}`.\nThe response carries `response_signature` and `signer_pubkey` (also exposed at\n`/health`). Anyone can confirm the verdict is genuine — no need to trust whoever\nforwarded it:\n\n```bash\ncurl -s -X POST https://tokensafe-production.up.railway.app/v1/verify \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"mint\":\"<MINT>\",\"checked_at\":\"<ISO>\",\"rpc_slot\":<N>,\"risk_score\":<N>,\"response_signature\":\"<hex>\"}'\n# → { \"valid\": true, \"signer_pubkey\": \"<hex>\" }\n```\n\nBecause the score is computed from raw chain state (not resold from a\nthird-party API), the signature is a real proof of provenance — a treasury or\ncompliance agent can store it as auditable proof-of-diligence. Operators should\nset a persistent `RESPONSE_SIGNING_KEY` (`npm run signing-key:generate`) so\nattestations stay verifiable across deploys.\n\n## Self-Hosting\n\n```bash\ngit clone https://github.com/ampactor-labs/tokensafe\ncd tokensafe\ncp .env.example .env\n# Set TREASURY_WALLET_ADDRESS and HELIUS_API_KEY in .env\nnpm install\nnpm run dev\n```\n\nRequires: Node 22+, a Solana wallet, and a free [Helius](https://helius.dev) API key.\n\n## Architecture\n\nTypeScript + Express. Every check reads raw Solana blockchain state via Helius RPC. No GoPlus, no RugCheck, no off-chain databases, no ML models.\n\n- 6-9 RPC calls + 1-2 HTTP calls per check\n- 5-minute in-memory LRU cache (10K entries)\n- Ed25519 response signing for audit trail\n- Docker-ready (node:22-slim, non-root user)\n\n## Verification\n\n18 test files, 525 cases, run with `npm test` (vitest). They cover the risk scoring, the Jupiter quote paths, the audit ledger, the delta endpoint, and the x402 payment middleware.\n\n`npm run test:smoke` hits a running instance end to end: it pays a real 402 challenge and checks that the Ed25519 signature on the response verifies. That is the check that matters here, because a signature nobody verifies is decoration.\n\nThere is no CI workflow in this repo. Deploys go through Railway, so treat the signed response and the on-chain payment as the receipts rather than a badge.\n\n## Weak spots\n\nThis reads chain state, so it can only catch what chain state shows. A developer who simply sells, an off-chain social rug, or a compromised team wallet all produce a clean report right up until they do not. A SAFE verdict means the checks below found nothing, not that the token is safe.\n\nHoneypot detection compares a Jupiter buy quote with a sell quote, which misses conditional logic that only refuses some sellers or only after some time. LP-lock detection recognizes nine known locker programs, so liquidity locked in an unrecognized contract reads as unlocked and scores worse than it deserves.\n\nNo CI runs in this repo. The signing key, the treasury address, and the deploy live in Railway, so the receipts here are the signed response and the on-chain payment, not a green badge.\n\n## License\n\nMIT\n",
  "bytes": 10073,
  "sha": "68f6d7d37bbe8a52d6787587685c0bb5f4a73c6ef4c0f565f7a6effde1f0b4dd",
  "repo_slug": "ampactor-labs/tokensafe",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ampactor_labs_tokensafe_tokensafe_29f8a622/readme"
}