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. Stacks tokens (STX, sBTC, USDCx, stSTX, ZEST, LEO, USDh, aeUSDC, stBTC) add the Bitflow DEX venue: price impact at YOUR size from a live route quote, the pools and bins the swap crosses, and their TVL; STX and sBTC keep their CEX perp legs, DEX-only tokens report funding/OI n/a and contract risk unscreened (no GoPlus coverage on Stacks)..
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.
| name | type | required | description |
|---|---|---|---|
symbol | string | yes | Asset to check, e.g. 'ETH', 'BTC', 'SOL' |
size_usd | number | no | Intended position size in USD (drives the slippage check) |
side | string | no | Trade direction (funding carry is side-aware) |
venue | string | no | Where the trade executes. auto (default): CEX books for majors, Bitflow for Stacks tokens, both for STX/sBTC. bitflow: price the swap on Bitflow only; cex: skip Bitflow |
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) |
verdict (ok/caution/avoid), factors{liquidity,carry,crowding,security} each with level + reason, components{orderbook_depth,funding_rates,open_interest}, symbol, side, size_usd
{
"symbol": "ETH",
"side": "long",
"size_usd": 50000,
"venue": "cex",
"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": "n/a",
"reason": "ETH is a native chain asset \u2014 no token contract to screen"
}
},
"not_checked": [
"security"
]
}
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 listing the payment options: USDC on Base (gasless
# EIP-3009) or Stellar, sBTC on Stacks. Pay one, retry with the proof
# header. The SDK below does this for you. The body may also be the
# bare parameters object, without the envelope.
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
npx -y @romudille/agentpay-mcp # keyless; exposes pre_trade_check to any MCP agent runtime