Sentinel docs

Sentinel sits between an AI agent and its Solana wallet. It scores the token, builds and simulates the transaction, applies the owner's policy and returns a decision with an unsigned transaction. It never holds keys.

Overview

Quickstart

Replace direct signing with one request. Sign only when decision is allow.

curl -X POST https://sentinel-clawpump.vercel.app/api/execute \
  -H 'content-type: application/json' \
  -d '{
  "intent": { "type": "buy", "wallet": "<agent wallet>", "mint": "<token CA>", "sol": 0.5 },
  "policy": { "limits": { "per_tx_sol": 2 } }
}'

With the SDK, which also checks the transaction locally before signing:

import { Sentinel } from 'clawpump-sentinel';
const sentinel = new Sentinel();
const res = await sentinel.executeAndSend({ type: 'buy', wallet, mint, sol: 0.5 }, agentKeypair, connection);
// res.signature is set only when the decision was "allow" and the local check passed

Decisions

Every check ends in one of four decisions. The strictest reason wins.

With "mode": "warn" the same analysis runs, enforced is false and the transaction is returned whatever Bastion decides, so you can watch verdicts before enforcing them. A token that fails Scan still returns no transaction.

Execute an intent

Scans the token being bought, builds the trade through Jupiter (or a plain SOL transfer), simulates it and applies the policy. Never signs.

Request

slippageBps is 1 to 5000, default 100. wallet is the agent's address; the returned transaction has it as fee payer and signer.

Response

{
  "decision": "allow",                 // allow | confirm | block | freeze
  "enforced": true,                    // false in warn mode
  "transaction": "AQAAAA…",            // unsigned base64, null on block / freeze
  "requiresOwnerConfirmation": false,
  "reasons": [],                        // see Reason codes
  "intent": { … },
  "scan": { "mint", "symbol", "score", "verdict", "criticalFlags" },   // null for sells and transfers
  "bastion": { … },                     // full Bastion result, see Check a transaction
  "journalId": "f91daca5-…",
  "durationMs": 1840
}

Check a transaction

For agents that build their own transactions. Send one before signing and get Bastion's verdict.

{
  "decision": "confirm", "enforced": true, "wallet": "…",
  "reasons": [{ "id": "new_recipient", "action": "confirm", "message": "Transfer of 0.5 SOL to a new address …" }],
  "simulation": { "success": true, "error": null, "logsTail": [], "unitsConsumed": 450 },
  "changes": { "sol": -0.500005, "tokens": [{ "mint", "symbol", "amount", "valueSol" }] },
  "spend": { "txSol", "perTxLimitSol", "day24hSol", "perDayLimitSol", "txLastHour" },
  "programs": [{ "id", "name", "allowed" }],
  "recipients": [{ "address", "amount", "asset", "isNew" }],
  "tokenScans": [{ "mint", "score", "verdict", "critical" }],
  "slippageBps": null,
  "rulesVersion": "bastion-v1.0", "durationMs": 912, "journalId": "…"
}

Bastion runs, in order: simulation, drainer patterns, program allowlist, per-trade and daily limits, recipients, a Scan of every token the wallet receives, effective slippage against a fresh Jupiter quote, and the kill-switch rules.

Score a token

0 to 100 risk score for any SPL or Token-2022 mint on mainnet, with flags and a per-block breakdown. Results are cached for 60 seconds (cached: true).

{
  "mint": "…", "name": "…", "symbol": "…",
  "score": 71, "verdict": "warn", "risk": "medium",
  "criticalFlags": [], "flags": [{ "id", "severity", "message" }],
  "blocks": [{ "id": "holders", "label": "Holders", "weight": 20, "score": 12.1, "status": "ok", "details": { … }, "flags": [] }],
  "rulesVersion": "scan-v1.1", "scannedAt": "…", "durationMs": 1063, "cached": false,
  "disclaimer": "The score is a risk indicator, not financial advice."
}

See Scoring rules for how the score and verdict are computed.

Decision log

Every execute, check, freeze and unfreeze with its reasons and rules version, newest first. limit defaults to 50, max 200.

[{ "id", "at", "kind": "execute", "wallet", "summary": "buy USDC for 0.02 SOL", "decision", "enforced", "reasons", "rulesVersion" }]

Guarded wallets

A guarded wallet is a Squads v4 multisig with threshold 1. The owner has every permission, the agent can propose and execute, Sentinel can only vote. Nothing executes without a vote and the agent has none, so funds move only when Sentinel (or the owner) approves. The check is enforced by the Squads program on-chain.

All guard endpoints are POST, rate limited, and accept "cluster": "mainnet" | "devnet" (default mainnet).

Guard intents use agent instead of wallet: buy (mint, sol), sell (mint, amount) and transfer (to, sol). Funds move from the vault.

Owner-side endpoints used by the approval page: /api/guard/proposal, /api/guard/approve, /api/guard/reject, /api/guard/send, /api/guard/unfreeze-message and /api/guard/unfreeze. Unfreezing requires the owner's signature over the message. GET /api/guard/sentinel returns Sentinel's voting key.

Health and defaults

Service status and the active rules versions.

The default policy as JSON.

Policy

Send any subset; missing fields fall back to the defaults.

Reason codes

Scoring rules

Seven blocks add up to 100. A block whose data source fails gets half its weight and status: "error", so one outage cannot pass or sink a token on its own.

Verdict

• block when there is any critical flag or the score is below 60
• warn when the score is 60 to 74
• allow at 75 and above

Critical flags

Each one blocks the token regardless of score:

Warning flags: bundle_launch, creator_funded_holders, creator_rugs, dev_dump, fresh_creator, funding_cluster, high_price_impact, high_transfer_fee, impersonation, low_liquidity, metadata_mutable, metadata_unreachable, mint_close_authority, no_liquidity, no_sells, price_crash, price_spike, serial_launcher, snipers_heavy, top10_concentrated, transfer_hook, wash_trading_suspected, whale.

The full rules are open source in src/scan.

Benchmarks

Measured on October 1, 2026 with rules scan-v1.1. The samples are small and the numbers will move as the rules change. Both scripts are in the repository, so anyone can rerun them.

Speed

npm run bench scans tokens once each through the hosted API, skipping cached answers, and reads durationMs from the response (server time, without your network).

Accuracy

npm run calibrate scans two labeled sets. Labels come from market outcomes, not from Sentinel.

What these numbers do and do not show:

• Sentinel does not block established tokens, but it is cautious: most well-known memecoins get warn because of whale concentration or mutable metadata. The default min_token_score of 60 lets them through.
• Dead tokens are scanned after they died, and all of them were caught by no_real_liquidity. This shows an agent will not buy into a token that has already been drained. It does not show how early Sentinel spots a rug before it happens; that needs a forward test and is not measured yet.
• The established set and the four hand-picked dead tokens were used while tuning scan-v1.1, so they are not an independent test. The other dead tokens are found fresh on every run.

Errors and limits

Errors come back as { "error": "message" }.

• Request body up to 256 KB
• One request runs up to 30 seconds; a scan block that takes over 12 seconds gets the half-weight fallback
• Scan results are cached for 60 seconds

TypeScript SDK

npm i clawpump-sentinel @solana/web3.js

Local check before signing

Before executeAndSend and guard.run sign, the SDK simulates the transaction on your own connection and compares the result with the intent:

• SOL leaving the wallet stays within the intent amount plus 0.005 SOL for fees and rent
• no other token balance drops; on a sell, at most the amount you asked to sell leaves
• on a buy the token you asked for arrives; on a transfer the recipient you named gets paid
• no token account gets a delegate or a new owner, and the wallet is not reassigned

A mismatch throws VerificationError and nothing is signed. You can run it on any transaction with verifyTransaction(connection, tx, expectationFor(intent, wallet)). Requests time out after 30 seconds (new Sentinel({ timeoutMs })).

MCP server

Streamable HTTP, stateless. Add it to your agent as a custom connector:

https://sentinel-clawpump.vercel.app/api/mcp

MCP and REST clients get the server-side checks. The local check before signing is part of the SDK.