Developers
Documentation and examples for the KushBitx agent checks: MCP, AgentKit, SDK and HTTP x402.
KushBitx MCP server
The same checks as MCP tools for Claude, Cursor, Cloudflare Agents and any MCP client. No account or API key.
https://kushbitx.com/mcpTools: spendguard_evaluate (free), kushbitx_preflight (0.005 USDC, the full KushBitx Preflight), quick_check, token_risk, preflight (0.001 USDC each; preflight is the limited Simulation Check) and verify_payment (0.00288 USDC). signature_check (0.003 USDC). Seven tools in all. Paid tools use x402 in the Cloudflare Agents paidTool format: an unpaid call returns the payment requirement in _meta["x402/error"] and charges nothing; retry with _meta["x402/payment"]. Listed in the official MCP Registry as com.kushbitx/agentproof. KushBitx never signs, holds keys or moves funds.
Quick Check
Base chain identity + official USDC contract-presence check.
A small deterministic check on Base. No request body is needed. Not a Token Risk report, transaction simulation, payment proof, or smart-contract audit.
Existing API documentation
Reference documentation for SpendGuard and the paid KushBitx checks. Paid API checks use USDC over x402.
One client for SpendGuard and the paid checks
npm install @kushbitx/sdk
import { KushBitxClient } from '@kushbitx/sdk';
const kushbitx = new KushBitxClient();GET /api/agentproof-quick-checkQuick Check · 0.001 USDC / call. Base chain identity and official USDC contract presence; no request body. PASS does not mean a payment is safe.
ExamplePOST /api/token-riskToken sellability, controls, concentration and market risk.
POST /api/transaction-preflightUnsigned call simulation and dangerous approval detection only; no token or recipient screening and no single verdict for spending. Simulation Check returns ALLOW, WARN, BLOCK or INCOMPLETE; KushBitx Preflight returns ALLOW, REVIEW or BLOCK.
POST /api/verify-paymentBase USDC transfer verification with confirmation count.
POST /api/preflightKushBitx Preflight · 0.005 USDC / call. One verdict (ALLOW, REVIEW, BLOCK) before money moves: transaction simulation, approval and transfer decoding, token and recipient or spender screening, optional protected SpendGuard policy. Fail-closed. Does not detect prompt injection. Protected SpendGuard can cap what an agent pays if your signer enforces its decisions; it does not detect prompt injection either. MCP tool: kushbitx_preflight. Version 1.1: send from; each verdict is valid 60 seconds for one transactionDigest. What changed.
Batches, smart accounts, UserOperations and EIP-7702
Preflight can also check:
- a batch of up to 10 calls from one account (
calls, the EIP-5792wallet_sendCallsshape); - a smart-account transaction (
executeBatch, ERC-7579 or ERC-7821execute, Safe 4337executeUserOp), detected from the calldata; - an ERC-4337 UserOperation (
userOperationandentryPoint; EntryPoint v0.6, v0.7 or v0.8; deployed accounts only); - an EIP-7702 transaction (
authorizationList, up to 5 authorizations).
One request costs the same 0.005 USDC, up to 10 calls. Each call is simulated after the earlier calls, from the account that runs them, and judged by the same rules as a single transaction.
Any call in a batch that KushBitx does not interpret makes the whole batch REVIEW. A call to a verified swap router is checked as a swap only when its simulation shows exactly one asset leaving the account and one asset arriving. Then only the output's arrival is checked, unless you send intent, expectedTokenOut and minAmountOut for that call.
REVIEW (fail-closed): an unknown EIP-7702 delegate; an authorization for all chains or another chain; an account that is not deployed (or a UserOperation that deploys one); an account type or execution mode KushBitx does not decode; asset movements the decoded calls do not explain.
Not checked: signatures, the account's own validation, gas, and paymaster terms.
Digests: batches have no transactionDigest; use batchDigest. So canSign in @kushbitx/sdk returns false for batches.
Beta means the response fields may still change. Fields and reason codes: /api/services.
Signed verdicts
Every KushBitx Preflight response includes executionDigest: the EIP-712 hash of what will be executed. That is the account, every call in order (to, value, data), and any EIP-7702 authorizations. A contract or any EIP-712 library can recompute it. transactionDigest is unchanged.
Only ALLOW is signed. When the verdict is ALLOW, the response also carries signedVerdict, an EIP-712 PreflightVerdict signed by a KushBitx key. It binds:
- the account and chainId 8453;
- the
executionDigest; - the account's nonce;
- the verdict;
- the block used;
- the rules version;
- a request ID.
REVIEW and BLOCK responses carry signedVerdict: null with the reason.
Expiry: a signed verdict expires 60 seconds after it is issued, and never later than the report's expiresAt.
Safe: send safeTransaction (safe, to, value, data, operation) instead of to and data. On ALLOW, KushBitx also returns safeCoSignature: a 65-byte signature over the Safe transaction hash with every gas and refund field zero, the format used by the Safe Policy Engine's CoSignerPolicy. KushBitx co-signs only when that hash matches the Safe's own getTransactionHash. A delegatecall is never co-signed.
Not signed yet: ERC-4337 UserOperations and Safe MultiSend (delegatecall).
Keys: the signing key signs verdicts only. It holds no funds and cannot move them. Active keys are published at /.well-known/kushbitx-preflight-signers.json with their key ID and validity (90 days). Accept a signature only if its signer is listed there as active at the verdict's issuedAt.
Rotation and revocation: rotation adds a new key before the old one expires. Revocation sets the key's entry to revoked, and signing with that key stops at once.
A signed ALLOW is not a guarantee. It covers the chain state at the block used, for 60 seconds.
KushBitx Preflight 1.1: stricter, bound to one transaction
Some transactions that were ALLOW in 1.0 are now REVIEW. The price stays 0.005 USDC.
- Send
from. Without it the verdict is REVIEW (sender_unknown), because the transaction cannot be simulated from the signing wallet. - Sign only the transaction that was checked. Each response carries
transactionDigest,checkedAtandexpiresAt(60 seconds). Compute the same digest from the transaction you are about to sign: sha256 ofJSON.stringify({chainId,from,to,value,data})in that key order, with from, to and data in lowercase and value as a decimal wei string. If it differs or the time has passed, check again. - Swaps: add
expectedTokenOut, and optionallyminAmountOut(token units) andexpectedRecipient(defaultfrom). The simulated output is checked against them; if it cannot be checked, the verdict is REVIEW. - Effects are simulated with
eth_simulateV1from the sender, including internal calls. Assets leaving the sender or approvals that the transaction does not declare give REVIEW (an undeclared approval for a whole collection gives BLOCK). So do Safe delegatecall execution, Multicall3aggregate3Value, Universal Router commands we do not interpret, and calls with no transfer or approval event we can read.
| ETH transfer | sender, simulation, destination, effects |
|---|---|
| ERC-20 transfer | sender, simulation, calldata_decode, recipient, token, effects |
| approve, setApprovalForAll | sender, calldata_decode, spender, token (ERC-20), effects |
| swap | sender, simulation, effects, swap_outputs, token (output, unless native ETH) |
| other contract call | sender, simulation, destination, effects |
| with policy | all of the above, plus policy (Protected SpendGuard) |
The same matrix is in /api/services (requiredChecks), and the 200 response schema is in openapi.json. Preflight still does not detect prompt injection. Protected SpendGuard can cap what an agent pays if your signer enforces its decisions; it does not detect prompt injection either.
Transfers: send expectedRecipient. For an ETH or ERC-20 transfer, a different actual recipient is BLOCK (EXPECTED_RECIPIENT_MISMATCH). Without it, Preflight still compares the recipient with the addresses the sender paid or was paid by (its last 1,000 transfers each way): a look-alike (same first and last 4 characters, different address) is REVIEW (ADDRESS_POISONING_SUSPECTED), and BLOCK (ADDRESS_POISONING_PLANTED) when a planted fake-token, zero or dust line connects them. A recipient the sender never dealt with gets an information note (FIRST_TIME_RECIPIENT). The result is in addressPoisoning.
Token-security and address-risk signals: Powered by GoPlus Security
Connect KushBitx to your AI coding tool
Add the KushBitx MCP server to your editor. The free spendguard_evaluate tool works right away. Paid tools return an x402 payment requirement that Cursor, Claude Code and VS Code cannot pay by themselves yet; for paid checks from your code, use a snippet below. Machine-readable instructions: /llms.txt.
claude mcp add --transport http kushbitx https://kushbitx.com/mcpYour key stays out of code and chat: put it in a .env file listed in .gitignore, and use a dedicated wallet with a small USDC balance on Base. Every snippet caps a payment at 0.005 USDC per call by default (enough for KushBitx Preflight) (one line to change); the cap protects you if a price changes.
Node.js: @kushbitx/sdk with x402
npm install @kushbitx/sdk @x402/fetch @x402/evm viem
echo "EVM_PRIVATE_KEY=" >> .env # open .env in your editor and paste your key after "="
echo ".env" >> .gitignore
node --env-file=.env app.mjsnpm install @kushbitx/sdk @x402/fetch @x402/evm viem
Add-Content .env "EVM_PRIVATE_KEY=" # open .env in your editor and paste your key after "="
Add-Content .gitignore ".env"
node --env-file=.env app.mjsimport { KushBitxClient } from "@kushbitx/sdk";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const MAX_PER_CALL = "$0.005"; // protects you if a price changes; edit this line
// Free checks: no wallet needed
const kushbitx = new KushBitxClient();
console.log(await kushbitx.previewToken("0x940181a94A35A4569E4529A3CDfB74e38FD98631"));
// Paid checks: x402, USDC on Base. The key comes from .env, never from code.
const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY) });
client.setSpendControls({ maxAmountPerPayment: MAX_PER_CALL });
const paidFetch = wrapFetchWithPayment(fetch, client);
const res = await paidFetch("https://kushbitx.com/api/token-risk", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ chain: "base", address: "0x940181a94A35A4569E4529A3CDfB74e38FD98631" }),
});
console.log(await res.json()); // INCOMPLETE means missing evidence, never "safe"Coinbase AgentKit: @kushbitx/agentkit
npm install @kushbitx/agentkit @coinbase/agentkit zod
echo "EVM_PRIVATE_KEY=" >> .env # open .env in your editor and paste your key after "="
echo ".env" >> .gitignore
node --env-file=.env app.mjsnpm install @kushbitx/agentkit @coinbase/agentkit zod
Add-Content .env "EVM_PRIVATE_KEY=" # open .env in your editor and paste your key after "="
Add-Content .gitignore ".env"
node --env-file=.env app.mjsimport { AgentKit } from "@coinbase/agentkit";
import { kushbitxActionProvider } from "@kushbitx/agentkit";
const agentkit = await AgentKit.from({
walletProvider, // your AgentKit EVM wallet on Base mainnet; keep its key in .env (EVM_PRIVATE_KEY), never in code
actionProviders: [kushbitxActionProvider({ maxPaymentUsdc: "0.005" })], // per-call cap; protects you if a price changes
});Cloudflare agents: see Use KushBitx from a Cloudflare agent.
Use KushBitx from a Cloudflare agent
The KushBitx MCP server works with the Cloudflare Agents SDK x402 client (withX402Client from agents/x402). A paid tool returns an x402 requirement; the client asks your confirmation callback, signs a USDC payment on Base and retries. Use a dedicated low-balance wallet and keep a callback that checks network, recipient and amount.
npx wrangler secret put EVM_PRIVATE_KEY # prompts for the key; it is never shown or saved in your code
# Local development: put EVM_PRIVATE_KEY=... in .dev.vars and add .dev.vars to .gitignoreimport { Agent } from "agents";
import { withX402Client } from "agents/x402";
import { privateKeyToAccount } from "viem/accounts";
const KUSHBITX_PAY_TO = "0x0d68028d06af13379c872fee032568b4be712f22";
const MAX_ATOMIC = 5000n; // 0.005 USDC per call; protects you if a price changes
export class SafePayAgent extends Agent<Env> {
x402Client;
async onStart() {
const { id } = await this.mcp.connect("https://kushbitx.com/mcp");
this.x402Client = withX402Client(this.mcp.mcpConnections[id].client, {
network: "base", // KushBitx charges USDC on Base mainnet
account: privateKeyToAccount(this.env.EVM_PRIVATE_KEY), // dedicated low-balance wallet, stored as a Worker secret
maxPaymentValue: MAX_ATOMIC,
});
}
// Pay only Base USDC to KushBitx, up to the cap. Return false to decline.
confirm = async (accepts) =>
accepts.every(a => a.network === "eip155:8453" && a.payTo.toLowerCase() === KUSHBITX_PAY_TO && BigInt(a.amount) <= MAX_ATOMIC);
async checkToken(address) {
return this.x402Client.callTool(this.confirm, {
name: "token_risk",
arguments: { chain: "base", address },
});
}
}Free first: call spendguard_evaluate without a wallet. Paid tools: kushbitx_preflight (0.005 USDC, the full KushBitx Preflight: one verdict before money moves), quick_check, token_risk, preflight (0.001 USDC each; preflight is the limited Simulation Check) and verify_payment (0.00288 USDC). INCOMPLETE means missing evidence, never zero risk. Verified end to end with agents 0.30.1 on Base Sepolia (staging, test USDC) on 26 October 2026; the published code targets Base mainnet (eip155:8453) and real USDC.
Decisions: what your agent should do
Sign or pay automatically only on ALLOW, APPROVE or VERIFIED. Quick Check PASS does not mean a payment is safe: it only confirms that the network is Base and the official USDC contract is present. Anything else: stop, or ask a person. The same table is in /api/services (decisions).
| Service | Proceed | Ask a person | Stop |
|---|---|---|---|
| KushBitx Preflight (0.005) | ALLOW, if transactionDigest matches and it has not expired (SDK canSign) | REVIEW (a risk signal, or a required check that could not run: see checksUnavailable). With technicalReview: true a check failed on our side or at a provider: credits are returned automatically. | BLOCK |
| Token Risk (0.001) | ALLOW | WARN, INCOMPLETE | BLOCK |
| Simulation Check (0.001, formerly Transaction Preflight) | ALLOW | WARN, INCOMPLETE | BLOCK |
| SpendGuard (free) | APPROVE | HUMAN_APPROVAL | BLOCK |
| Quick Check (0.001) | — (PASS only confirms Base and the official USDC contract; it is not a payment verdict) | — | FAIL |
| Payment Proof (0.00288) | VERIFIED | PENDING_OR_NOT_FOUND (check again later) | MISMATCH, FAILED |
| Signature Check (0.003) | ALLOW, if typedDataDigest is the digest of the exact typed data you sign | REVIEW (unknown typed data, unverified spender, long validity, or a check that could not run) | BLOCK |
On REVIEW: read findings and checksUnavailable in the answer. If technicalReview is true, a check failed on our side or at a provider: retry after a short wait.
Otherwise a person decides, using those findings, whether to go ahead; do not resend the same transaction hoping for ALLOW.
Signature Check: before signing typed data
POST /api/signature-check with {"chainId":8453,"signer":"0x…","typedData":{…}} (the exact EIP-712 object), and for x402 payments expectedPayTo and expectedAmount, for permits expectedSpender. It covers EIP-3009 (x402 payments), EIP-2612 Permit and Permit2 (allowance and signature transfer). It checks the chain and token domain, payTo and amount, the spender (our verified list, a plain wallet is BLOCK), unlimited amounts and long validity. Any other typed data is REVIEW. The answer is bound to typedDataDigest. 0.003 USDC with x402, or 1 credit. MCP tool: signature_check.
Free token coverage check
POST /api/token-coverage with {"chain":"base","address":"0x…"} tells you, before you pay, which Token Risk checks have data for that token (market, contract, ownership). It is free, rate-limited (60 requests per hour per source), and not a security verdict. If every market provider is down it answers 503 with Retry-After.
Prepaid credits
Top up once with x402 (POST /api/credits/topup, 1 to 50 USDC), then send X-KushBitx-Credit-Key and a unique Idempotency-Key on any paid route instead of a per-call payment. 1 credit = 0.001 USDC: KushBitx Preflight 5 credits, Token Risk, Simulation Check and Quick Check 1 credit, Payment Proof 2 credits. Details on Pricing and in /api/services (credits).
Listed on
Third-party directories where KushBitx is listed. Some still use our earlier name, KushBitx AgentProof; it is the same service.
Give your agent its first Base check
Copy these instructions into an agent that can make HTTP requests. It can fetch market data and check data availability before you consider a paid report. No account or wallet needed.
Invite another builder to try it
Share this free starting point. The link contains no wallet information or private report details.
Paid services are optional: Quick Check 0.001 USDC, payment verification 0.00288 USDC, unsigned transaction preflight 0.001 USDC, token report 0.001 USDC. A delivered INCOMPLETE report still carries the displayed fee.
Start with a free API request
Send this JSON request to the same domain. A successful response includes token identity and trading-pair market data. The preview does not include a security verdict.
POST /api/token-preview
Content-Type: application/json
{"chain":"base","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}How a paid request works
- Use GET with no request body for Quick Check, or POST input JSON for Token Risk, Simulation Check and Payment Proof. The initial HTTP 402 response is a payment request; it does not charge your wallet.
- Use an x402 v2 client to read the PAYMENT-REQUIRED header and authorize the displayed USDC amount on Base.
- Retry the same request with the PAYMENT-SIGNATURE header. HTTP 200 returns the completed report. Handle non-200 responses before using a result.
Run the SDK-supported reports from one agent example
Node.js 22 or later. The free token and SpendGuard previews need no package installation. Download the example above, then start free.
node agent.mjs
node agent.mjs --spendguard
# Explicit paid runs. Paid mode requires viem and a dedicated wallet.
npm install viem
# Set EVM_PRIVATE_KEY in your local secret manager first.
node agent.mjs --paid --service=token-risk
TX_TO=0x… node agent.mjs --paid --service=preflight
TX_HASH=0x… EXPECTED_TO=0x… EXPECTED_AMOUNT=1.00 node agent.mjs --paid --service=payment
# Restore the same saved report without paying again
node agent.mjs --restore --service=token-riskThe example checks the recipient, token, network and exact price before signing. It saves a private recovery file before payment, never submits the transaction being inspected, and never trades. An INCOMPLETE verdict or null score means missing evidence.
Keep each recovery file private. Preflight and payment proof use service-specific default filenames. To reconcile an interrupted settled payment, set PAYMENT_TX_HASH before running --restore. Preserve each recovery file before starting a new report.