← all AgentPay tools

pre_trade_check

One-call pre-trade sanity check: 'I want to long $X of SYMBOL — is now sane?' Combines live orderbook slippage at YOUR size, cross-exchange funding (carry cost), open-interest crowding, and contract security (GoPlus) into a single ok/caution/avoid verdict with a per-factor breakdown. Major ERC-20 addresses (LINK, UNI, ARB, OP, AAVE, PEPE, SHIB) resolve automatically; native assets (BTC, ETH, SOL, ...) report security n/a; an unrecognized token without token_address reads 'unknown' and caps the verdict at caution — an unscreened contract can never read 'ok'. Replaces four API integrations and the judgment layer on top of them. Raw component data embedded so you can apply your own thresholds..

When agents use this

An agent (or human) is about to enter a position and wants one verdict covering liquidity, carry, crowding, and security — instead of four raw feeds plus its own synthesis.

Parameters

name	type	required	description
side	string	no	Trade direction (funding carry is side-aware)
symbol	string	yes	Asset to check, e.g. 'ETH', 'BTC', 'SOL'
size_usd	number	no	Intended position size in USD (drives the slippage check)
token_address	string	no	Optional ERC-20 contract address for the GoPlus security scan. Auto-resolved for major tokens; required for a full verdict on tokens the resolver doesn't know (otherwise security reads 'unknown' and caps the verdict at caution)

Returns

verdict (ok/caution/avoid), factors{liquidity,carry,crowding,security} each with level + reason, components{orderbook_depth,funding_rates,open_interest}, symbol, side, size_usd

Example response

{
  "symbol": "ETH",
  "side": "long",
  "size_usd": 50000,
  "verdict": "caution",
  "factors": {
    "liquidity": {
      "level": "ok",
      "slippage_pct": 0.011,
      "bucket_usd": 50000,
      "reason": "fills within 0.011% of best ask"
    },
    "carry": {
      "level": "caution",
      "median_funding_pct": 0.062,
      "annualized_pct": 67.9,
      "reason": "longs paying elevated funding"
    },
    "crowding": {
      "level": "ok",
      "long_short_ratio": 1.4,
      "oi_change_24h_pct": 3.2,
      "reason": "positioning unremarkable"
    },
    "security": {
      "level": "skipped",
      "reason": "no token_address provided"
    }
  }
}

Call it — HTTP (x402)

curl -X POST https://agentpay.tools/tools/pre_trade_check/call \
  -H 'Content-Type: application/json' \
  -d '{"parameters": {"symbol": "Asset to check, e.g. 'ETH', 'BTC', 'SOL'"}, "agent_address": "<your wallet or any identifier>"}'
# → HTTP 402 challenge → pay USDC on Base (gasless EIP-3009) or Stellar,
#   retry with the payment proof header. The SDK below does this for you.

Call it — Python SDK

from agentpay import quickstart  # pip install agentpay-x402

s = quickstart(max_spend=0.10)   # hard budget cap; mints a wallet, no funding needed
r = s.call("pre_trade_check", {"symbol": "Asset to check, e.g. 'ETH', 'BTC', 'SOL'"})
print(r.data)                    # + r.cost, r.tx, r.network — full receipt

Call it — MCP

npx -y @romudille/agentpay-mcp   # keyless; exposes pre_trade_check to any MCP agent runtime