x402-perpcheck / tree / README.md · raw (this view has old GitHub links rewritten for the mirror; raw is byte-exact)

PerpCheck: Hyperliquid pre-trade order check for trading agents (x402 API + MCP)

Will this Hyperliquid perp order be rejected, and what does it cost and risk? Send the order your agent is about to place (coin, side, size or notional, optional limit price, leverage, cross/isolated, reduce-only). PerpCheck answers REJECT_LIKELY / CAUTION / OK with every exchange-rule problem and a fix value, plus the risk facts.

Not financial advice; the exchange decides whether an order is accepted. PerpCheck is a read-only pre-trade check: it never places, signs or holds orders, has no custody and never asks for keys.

API: https://api.youraitools.co/perpcheck
Remote MCP: https://api.youraitools.co/perpcheck/mcp (tool check_perp_order, 30 full checks/day per IP free, then x402)
stdio MCP: run from source (npm publishing is paused), see below
Source: https://agentgate-source.pages.dev/x402-perpcheck/ (MIT)

What it checks

Check	Code	Fix value
Size decimals (szDecimals)	`size_decimals`	rounded size
Price tick: 5 significant figures and 6 - szDecimals decimals (integers always OK)	`price_tick`	rounded price
$10 minimum order value (not for reduce-only)	`min_notional`
Max leverage by margin tier at this notional	`leverage`	max leverage
Isolated-only coins with cross margin	`isolated_only`
Coin at its open-interest cap (not for reduce-only)	`oi_cap`
Delisted coin	`delisted`
Limit price > 80% from mark	`price_band`

Warnings: marketable limit, tight liquidation, thin book / high impact, expensive funding carry, size > 1% of 24 h volume, and oi_cap_unknown / impact_unknown when a source failed.

The full tier adds the isolated liquidation estimate and distance (cross margin: isolated-equivalent worst case), taker impact and average fill from the live L2 book (market orders), funding carry per day (who pays), mark/oracle premium, open interest and size vs 24 h volume.

Pricing (x402, USDC on Base, Polygon, Arbitrum One or Solana; or a prepaid credits key)

Route	Price	Returns
`GET/POST /v1/lite`	$0.003	verdict, issues with fix values, warnings, coin rules, confidence, sources_failed
`GET/POST /v1/full`	$0.01	lite + liquidation, execution (impact), funding, market
`GET /v1/preview`	free (10/min per IP)	verdict, issue and warning codes only
`POST /mcp`	free 30/day per IP, full result	then an MCP payment_required result with the x402 URL

Only HTTP 200 answers are settled. Bad input (400), unknown coins (404) and upstream failures (503) are never charged.

curl -s "https://api.youraitools.co/perpcheck/v1/preview?coin=ETH&side=long&size=0.0012345&price=3000.123&leverage=60"
curl -i "https://api.youraitools.co/perpcheck/v1/lite?coin=BTC&side=long&size=0.001&leverage=10"   # 402 with x402 terms

Fail-closed

Data comes only from the public Hyperliquid info API (metaAndAssetCtxs, perpsAtOpenInterestCap, l2Book), tried on api.hyperliquid.xyz, then api-ui.hyperliquid.xyz, then the primary again, each with a short timeout. If the OI-cap list or the book can't be read, the answer is never OK: it is at best CAUTION, lists sources_failed and lowers confidence. Without market metadata the answer is 503 with verdict UNKNOWN and nothing is charged.

MCP install (one line)

Claude Code:

claude mcp add --transport http perpcheck https://api.youraitools.co/perpcheck/mcp

Cursor (~/.cursor/mcp.json):

{ "mcpServers": { "perpcheck": { "url": "https://api.youraitools.co/perpcheck/mcp" } } }

Claude Desktop: Settings > Connectors > Add custom connector with https://api.youraitools.co/perpcheck/mcp.

Self-host the stdio server (no npm)

git clone https://agentgate-source.pages.dev/x402-perpcheck/x402-perpcheck.git && cd x402-perpcheck && npm install --omit=dev --ignore-scripts
# { "mcpServers": { "perpcheck": { "command": "node", "args": ["/absolute/path/to/x402-perpcheck/src/mcp-stdio.js"] } } }

The stdio server returns the free preview. Set PERPCHECK_X402_PRIVATE_KEY (a small Base USDC wallet, not your trading key) and install @x402/fetch @x402/evm viem in the checkout to get full checks ($0.01 per call; spend guard: Base USDC only, max $0.01 per payment, only to the PerpCheck payTo). Docker: docker build -t perpcheck-mcp . && docker run -i --rm perpcheck-mcp.

Develop

npm install && npm test        # offline tests (mocked Hyperliquid)
node src/cli.js coin=BTC side=long size=0.001 leverage=10   # live, read-only
npx wrangler deploy

Payouts: EVM 0x3c1A1E01e790Cd326495631B3b38Bd7068F08d6F, Solana FH73WbbUe2UyNzfy72MJs5nT3NxyDf9GrqE7kzjL2Jte.

agentgate-source: code mirror on Cloudflare Pages. All repos