Premium · 5 tADAHire on SokosumiMCP tool run_trade_gatekeeper·Run it in the playground →

Give it a token, an order size and optionally your rules. It runs the CoinGraph check, measures the real on-chain price impact of your size (DEX aggregator quote) against order-book depth and daily volume, reads leverage, onchain flows and contract risk, and returns ALLOW, REDUCE (with the largest safe size) or BLOCK, with every reason sourced.

When to use it #

A trading agent is about to place an order and needs a go / no-go.
A person wants to know whether a size fits the market before clicking buy.
A fund wants an auditable pre-trade check attached to every order.

Built for: Trading-agent developers · AI wallets

How it decides #

Runs the full token check sized to your order.
Prices the order on the best route: exchange order books (asks for a buy, bids for a sell) or a live on-chain quote from ParaSwap, KyberSwap or Jupiter on the token's home chain.
Impact limit: max_impact_pct if you set it, otherwise 1% for top-20 tokens and 2% for the rest.
BLOCK if one of your rules fails, the check says avoid, or even the best route costs more than twice the limit.
REDUCE if impact is over the limit or the order is more than 1% of daily volume, with the largest safe size.
ALLOW otherwise, with any caution from the check passed on as a warning.

Verdicts #

Verdict	Meaning
ALLOW	The order fits current liquidity and nothing in the check stops it.
REDUCE	Go ahead with a smaller order; result.size.max_safe_usd says how much.
BLOCK	Do not place this order now; the reasons say why.

Input #

POST/v1/agents/trade-gatekeeper

Body

tokenstringrequired
Token: CoinGecko id (chainlink), symbol (LINK) or contract address
size_usdnumber (…–10000000000)optionaldefault 10000
Order size in USD
side"buy" | "sell"optionaldefault "buy"
max_impact_pctnumber (…–50)optional
Largest acceptable price impact; default 1% for top-20 tokens, 2% otherwise
policyobjectoptional
policy.min_depth_usdnumberoptional
policy.max_top10_holder_pctnumberoptional
policy.max_funding_pctnumberoptional
policy.max_exchange_inflow_usdnumberoptional
policy.allow_mint_authoritybooleanoptional

Examples #

Real runs, captured from the live service.

ALLOW: buy $5K of SOL

Request

curl -X POST "https://coingraph.ai/api/v1/agents/trade-gatekeeper" \
  -H "content-type: application/json" \
  -d '{"token":"solana","size_usd":5000,"side":"buy"}'

Response · real, captured 2026-10-06 23:24 UTC · long lists trimmed

{
  "object": "agent_run",
  "id": "run_2620bb88435002c82aed",
  "as_of": "2026-10-06T23:21:51.905Z",
  "data": {
    "run_id": "run_2620bb88435002c82aed",
    "agent": "trade-gatekeeper",
    "agent_version": "1.0.0",
    "as_of": "2026-10-06T23:21:51.905Z",
    "verdict": "ALLOW",
    "summary": "ALLOW: $5K buy of SOL fits current liquidity (under 0.01% impact via exchange order books).",
    "result": {
      "token": {
        "id": "solana",
        "symbol": "SOL"
      },
      "side": "buy",
      "size": {
        "requested_usd": 5000,
        "max_safe_usd": 5000
      },
      "impact": {
        "best_route": "exchange order books",
        "best_pct": 0,
        "routes": [
          {
            "route": "exchange order books",
            "impact": 0
          }
        ],
        "limit_pct": 1,
        "share_of_daily_volume_pct": 0
      },
      "check": {
        "verdict": "proceed",
        "confidence": 0.86,
        "dimensions": {
          "momentum": "ok",
          "liquidity": "ok",
          "leverage": "ok",
          "onchain": "ok",
          "supply": "ok",
          "context": "ok",
          "contract": "unassessed"
        },
        "evaluation_id": "eval_301dfef4e441c9d2fb81"
      },
      "policy": null,
      "latest_brief": null
    },
    "reasons": [
      {
        "text": "$5K buy: under 0.01% impact on the best route (exchange order books; limit 1%), check verdict proceed",
        "source": "coingraph:evaluate"
      }
    ],
    "warnings": [],
    "links": {
      "proof": "/api/v1/verify/eval_301dfef4e441c9d2fb81"
    },
    "disclaimer": "CoinGraph never trades, holds funds or gives financial advice. The caller decides.",
    "hash": "56e179df3b8f7f9d5ffeb8284e305c7f3d0294e9d33e6b3d5e18b2df05e4ea55",
    "verify_url": "https://coingraph.ai/api/v1/verify/run_2620bb88435002c82aed"
  },
  "sources": []
}

REDUCE: buy $10K of RAIN with a 0.25% impact limit

Request

curl -X POST "https://coingraph.ai/api/v1/agents/trade-gatekeeper" \
  -H "content-type: application/json" \
  -d '{"token":"rain","size_usd":10000,"side":"buy","max_impact_pct":0.25}'

Response · real, captured 2026-10-06 23:24 UTC · long lists trimmed

{
  "object": "agent_run",
  "id": "run_ff11c1335d4a157942c6",
  "as_of": "2026-10-06T23:23:52.499Z",
  "data": {
    "run_id": "run_ff11c1335d4a157942c6",
    "agent": "trade-gatekeeper",
    "agent_version": "1.0.0",
    "as_of": "2026-10-06T23:23:52.499Z",
    "verdict": "REDUCE",
    "summary": "REDUCE: cut the RAIN buy to about $6.1K — 0.41% price impact on the best route (limit 0.25%).",
    "result": {
      "token": {
        "id": "rain",
        "symbol": "RAIN"
      },
      "side": "buy",
      "size": {
        "requested_usd": 10000,
        "max_safe_usd": 6097
      },
      "impact": {
        "best_route": "exchange order books",
        "best_pct": 0.41,
        "routes": [
          {
            "route": "exchange order books",
            "impact": 0.41
          }
        ],
        "limit_pct": 0.25,
        "share_of_daily_volume_pct": 0.106
      },
      "check": {
        "verdict": "caution",
        "confidence": 0.69,
        "dimensions": {
          "momentum": "ok",
          "liquidity": "caution",
          "leverage": "unassessed",
          "onchain": "unassessed",
          "supply": "ok",
          "context": "ok",
          "contract": "unassessed"
        },
        "evaluation_id": "eval_440120df45a35b28aa6b"
      },
      "policy": null,
      "latest_brief": {
        "id": 39,
        "headline": "RAIN +1.8% in 2h, rising from $0.01099 to $0.01124 as BTC/ETH sit flat; thin volume",
        "at": "2026-10-06T20:02:41.049Z"
      }
    },
    "reasons": [
      {
        "text": "$10K is too large: 0.41% price impact on the best route (limit 0.25%); about $6.1K fits",
        "source": "ccxt:fetchOrderBook"
      }
    ],
    "warnings": [
      "liquidity: $49K available within 2% of the price across exchanges (CoinGecko) — thin"
    ],
    "links": {
      "proof": "/api/v1/verify/eval_440120df45a35b28aa6b",
      "brief": "/investigations/39"
    },
    "disclaimer": "CoinGraph never trades, holds funds or gives financial advice. The caller decides.",
    "hash": "772ac77e30ca2ac64ba3ab223dcc154e5650ba28584d64879d085eb7d393919a",
    "verify_url": "https://coingraph.ai/api/v1/verify/run_ff11c1335d4a157942c6"
  },
  "sources": []
}

BLOCK: buy $10K of LEO

Request

curl -X POST "https://coingraph.ai/api/v1/agents/trade-gatekeeper" \
  -H "content-type: application/json" \
  -d '{"token":"leo-token","size_usd":10000,"side":"buy"}'

Response · real, captured 2026-10-06 23:24 UTC · long lists trimmed

{
  "object": "agent_run",
  "id": "run_c06127b3d593356a48d8",
  "as_of": "2026-10-06T23:24:06.858Z",
  "data": {
    "run_id": "run_c06127b3d593356a48d8",
    "agent": "trade-gatekeeper",
    "agent_version": "1.0.0",
    "as_of": "2026-10-06T23:24:06.858Z",
    "verdict": "BLOCK",
    "summary": "BLOCK: do not buy LEO now — contract: Owner can change holders' balances (ETH).",
    "result": {
      "token": {
        "id": "leo-token",
        "symbol": "LEO"
      },
      "side": "buy",
      "size": {
        "requested_usd": 10000,
        "max_safe_usd": 0
      },
      "impact": {
        "best_route": "exchange order books",
        "best_pct": 0.23,
        "routes": [
          {
            "route": "exchange order books",
            "impact": 0.23
          },
          {
            "route": "on-chain via paraswap (ETH)",
            "impact": 85.78
          }
        ],
        "limit_pct": 1,
        "share_of_daily_volume_pct": 6.109
      },
      "check": {
        "verdict": "avoid",
        "confidence": 0.95,
        "dimensions": {
          "momentum": "ok",
          "liquidity": "caution",
          "leverage": "ok",
          "onchain": "ok",
          "supply": "avoid",
          "context": "ok",
          "contract": "avoid"
        },
        "evaluation_id": "eval_4e04acad90cfc539e247"
      },
      "policy": null,
      "latest_brief": null
    },
    "reasons": [
      {
        "text": "contract: Owner can change holders' balances (ETH)",
        "source": "coingraph:evaluate"
      },
      {
        "text": "liquidity: $85.7K available within 2% of the price across exchanges (CoinGecko) — thin",
        "source": "coingecko:/coins/{id}/tickers"
      },
      {
        "text": "liquidity: A $10K order is 6.11% of daily volume and would move the price ~0.23%",
        "source": "ccxt:fetchOrderBook"
      },
      "… 3 more"
    ],
    "warnings": [],
    "links": {
      "proof": "/api/v1/verify/eval_4e04acad90cfc539e247"
    },
    "disclaimer": "CoinGraph never trades, holds funds or gives financial advice. The caller decides.",
    "hash": "c4065ce48dfad59dfaaa7e34bf7b9fa3cadf4a1a3ae5fa9edc37fbabad17ead5",
    "verify_url": "https://coingraph.ai/api/v1/verify/run_c06127b3d593356a48d8"
  },
  "sources": []
}

Result fields #

Inside data.result:

Field	Contents
`size`	requested_usd and max_safe_usd (0 on BLOCK).
`impact`	best_route, best_pct, every route priced, limit_pct and share_of_daily_volume_pct.
`check`	The underlying check: verdict, confidence, dimension ratings and evaluation_id.
`policy`	Your rules, pass / fail / unknown.
`latest_brief`	The latest brief when the token is rated caution or avoid.

i

Note

For liquid tokens such as ADA, LINK and SOL, an order of a few thousand dollars barely moves the price, so the answer is usually ALLOW. REDUCE and BLOCK show up on thin tokens, on tokens with contract or concentration risks, or when you set a tight max_impact_pct. Native coins (SOL, ADA, ETH, BTC) have no token contract, so their contract dimension reads unassessed; GoPlus covers token contracts only. Policy example: { "max_top10_holder_pct": 60, "allow_mint_authority": false, "min_depth_usd": 500000 }.

Use it from Claude #

With CoinGraph connected (how), ask in plain words, or call the tool directly:

MCP tools/call

{
  "name": "run_trade_gatekeeper",
  "arguments": {
    "token": "solana",
    "size_usd": 5000,
    "side": "buy"
  }
}

The proof for any run: https://coingraph.ai/proof/run_…

Trade Gatekeeper

When to use it #

How it decides #

Verdicts #

Input #

Examples #

Result fields #

Use it from Claude #