1.14 FeeAndGasGuard

1. Bot Identity

Operational profile

2. Purpose

FeeAndGasGuard estimates the total transaction cost (CLOB maker/taker fee plus Polygon gas) for a proposed order and rejects or downsizes it when the cost-to-edge ratio exceeds the configured ceiling. It prevents strategies from placing orders where fee drag exceeds the expected edge, turning a positive-expected-value intent into a negative-EV execution.

3. Why This Bot Matters

• Fee drag exceeds edge

  Placing an order where fees exceed the expected edge results in a systematically negative-EV trade that erodes capital over many repetitions.

• Gas spike not accounted for

  Polygon gas spikes during congestion can materially increase transaction cost; ignoring gas makes fee estimates unreliable during high-traffic periods.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "max_fee_to_edge_ratio": 0.5 }

if (totalCost / expectedEdge > params.max_fee_to_edge_ratio) return reject('FEE_GUARD_COST_EXCEEDS_EDGE');

{ "max_fee_bps": 100 }

if (effectiveFeeBps > params.max_fee_bps) return reject('FEE_GUARD_RATE_ANOMALY');

{ "min_order_usd": 10 }

if (intent.size_usd < params.min_order_usd) return reject('FEE_GUARD_ORDER_TOO_SMALL');

8. Default Configuration

{
  "bot_id": "risk.fee_and_gas_guard",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_fee_to_edge_ratio": 0.5,
    "max_fee_bps": 100,
    "min_order_usd": 10
  },
  "locked": {
    "max_fee_bps": {
      "max": 100
    },
    "min_order_usd": {
      "min": 1
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent with market_id, side, size_usd, price, and expected_edge_bps from strategy.
2. Check KillSwitch; if active, HARD_REJECT(KILL_SWITCH_ACTIVE).
3. Fetch current market probability p = (best_ask + best_bid) / 2 from CLOB.
4. Fetch operator-set fee rate for the market from CLOB (taker: max 100 bps; maker: max 50 bps).
5. Compute CLOB fee: fee_usd = size_usd * fee_rate_bps / 10000 * p * (1-p).
6. Fetch current Polygon gas price; estimate gas cost for CTFExchangeV2.matchOrders().
7. Compute total_cost_usd = fee_usd + gas_cost_usd.
8. If intent.size_usd < min_order_usd, HARD_REJECT(FEE_GUARD_ORDER_TOO_SMALL).
9. If effective_fee_bps > max_fee_bps, HARD_REJECT(FEE_GUARD_RATE_ANOMALY).
10. Compute edge_usd = size_usd * expected_edge_bps / 10000.
11. If total_cost_usd / edge_usd > max_fee_to_edge_ratio, HARD_REJECT(FEE_GUARD_COST_EXCEEDS_EDGE).
12. APPROVE with fee_estimate_usd and cost_to_edge_ratio attached.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION evaluateFeeAndGas(intent):
  ks = FETCH internal.killswitch.status
  IF ks.active: EMIT RiskVote(HARD_REJECT, KILL_SWITCH_ACTIVE); RETURN

  IF intent.size_usd < params.min_order_usd:
    EMIT RiskVote(HARD_REJECT, FEE_GUARD_ORDER_TOO_SMALL); RETURN

  feeRate = FETCH clob_public.fee_rate(intent.market_id)
  prices = FETCH clob_public.prices(intent.market_id)
  gasPrice = FETCH onchain.gas_price()
  IF feeRate IS NULL OR prices IS NULL OR gasPrice IS NULL:
    EMIT RiskVote(HARD_REJECT, FEE_GUARD_DATA_UNAVAILABLE); RETURN

  IF feeRate.bps > params.max_fee_bps:
    EMIT RiskVote(HARD_REJECT, FEE_GUARD_RATE_ANOMALY); RETURN

  p = (prices.ask + prices.bid) / 2
  feeUsd = intent.size_usd * (feeRate.bps / 10000) * p * (1 - p)
  gasUsd = estimateGasCost(gasPrice, 'matchOrders')
  totalCost = feeUsd + gasUsd

  edgeUsd = intent.size_usd * (intent.expected_edge_bps / 10000)
  ratio = totalCost / edgeUsd

  IF ratio > params.max_fee_to_edge_ratio:
    EMIT RiskVote(HARD_REJECT, FEE_GUARD_COST_EXCEEDS_EDGE,
                  total_cost=totalCost, ratio=ratio); RETURN
  IF ratio > params.max_fee_to_edge_ratio * 0.7:
    annotations.append(WARN(FEE_GUARD_COST_APPROACHING, ratio=ratio))

  EMIT RiskVote(APPROVE, fee_estimate_usd=totalCost, cost_to_edge=ratio)

SDK calls used

• clob_public.fee_rate(market_id)
• clob_public.prices(market_id)
• onchain.gas_price()
• internal.killswitch.status()

Complexity: O(1)

11. Wire Examples

Input — what arrives on the wire

OrderIntent — fee check — internal

{
  "intent_id": "int_f6a7b8c9d0e10006",
  "market_id": "0x4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
  "size_usd": 150,
  "price": 0.5,
  "expected_edge_bps": 40,
  "generated_at_ms": 1746800000000
}

Output — what the bot emits

RiskVote — HARD_REJECT cost exceeds edge

{
  "guard_id": "risk.fee_and_gas_guard",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "FEE_GUARD_COST_EXCEEDS_EDGE",
  "message": "Cost 4.20 pUSD / edge 6.00 pUSD = ratio 0.70 exceeds ceiling 0.50.",
  "constraints": {},
  "checked_at": "2026-05-10T13:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.fee_and_gas_guard",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "FEE_GUARD_COST_EXCEEDS_EDGE",
  "message": "Estimated cost 4.20 pUSD (ratio 0.70) exceeds max_fee_to_edge_ratio 0.50 for edge 6.00 pUSD.",
  "constraints": {},
  "inputs_used": [
    "clob_public.fee_rate",
    "clob_public.prices",
    "onchain.gas_price",
    "internal.expected_edge"
  ],
  "checked_at": "2026-05-10T13:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "risk.fee_and_gas_guard",
  "decision": "HARD_REJECT",
  "reason_code": "FEE_GUARD_COST_EXCEEDS_EDGE",
  "inputs_used": [
    "clob_public.fee_rate",
    "clob_public.prices",
    "onchain.gas_price"
  ],
  "metrics": {
    "fee_usd": 3.8,
    "gas_usd": 0.4,
    "total_cost_usd": 4.2,
    "edge_usd": 6.0,
    "cost_to_edge_ratio": 0.7,
    "fee_rate_bps": 60,
    "prob": 0.5
  },
  "checked_at": "2026-05-10T13:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, both caches populated from CLOB and onchain oracle before first evaluation.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Inflating expected_edge_bps in the intent to make the cost-to-edge ratio appear acceptable
• Submitting during low-gas windows to bypass gas-inclusive cost checks, then executing during high-gas periods

Mitigations

• expected_edge_bps is validated against a per-strategy cap from the internal config; values above the cap are clipped
• Gas price is fetched at evaluation time, not at intent generation time

24. Polymarket V2 Compatibility

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

FeeAndGasGuard incidents typically involve a gas spike or an anomalous fee rate on a newly listed market. Verify gas price normality before adjusting parameters.

On-call actions

Manual overrides

• polytraders risk set-gas-override --gas-usd <value> --duration 300s — During a gas oracle outage; sets a conservative fixed gas estimate to unblock orders.

Healthcheck

GET /internal/health/feeandgasguard → green: CLOB fee rate cache age < 60s, gas price cache age < 15s, no FEE_GUARD_RATE_ANOMALY in last 5m; red: Fee or gas data cache expired or unavailable

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%