# 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.

```bash
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:

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

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

```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)

```bash
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

```bash
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`.