2.14 FeeSlippageEstimator

1. Bot Identity

Operational profile

2. Purpose

Stamps every approved OrderIntent with an explicit fee + slippage estimate before the order shaper sees it. The estimate is a structured object (maker_fee_bps, taker_fee_bps, expected_slippage_bps, total_cost_usd) that downstream tools and UIs all read instead of guessing.

3. Why This Bot Matters

• Hidden cost surprises

  Without a per-order estimate, post-trade reports are the first place anyone learns the order was unprofitable after fees.

• Inconsistent cost models

  Each strategy inventing its own cost estimate produces inconsistent reports and dashboards.

• Affiliate/builderCode accounting

  The builder-fee component on V2 must be visible per order to track attribution correctly.

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

{ "maker_fee_bps": 0 }

fee += notional * p.maker_fee_bps/10000;

{ "taker_fee_bps": 200 }

fee += notional * p.taker_fee_bps/10000;

{ "builder_fee_bps": 0 }

fee += notional * p.builder_fee_bps/10000;

{ "slippage_safety_factor": 1.5 }

slip_bps *= p.slippage_safety_factor;

8. Default Configuration

{
  "maker_fee_bps": 0,
  "taker_fee_bps": 200,
  "builder_fee_bps": 0,
  "slippage_safety_factor": 1.5
}

9. Implementation Flow

— not yet authored —

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.

depth = walk_book(book, intent.side, intent.price, intent.size_usd)
slip_bps = (depth.vwap - book.mid) / book.mid * 10000 * p.slippage_safety_factor
fee_bps = p.taker_fee_bps + p.builder_fee_bps
stamp(intent, cost_estimate={maker:p.maker_fee_bps, taker:p.taker_fee_bps, builder:p.builder_fee_bps, slip:slip_bps, total_bps:fee_bps+slip_bps, total_usd: ...})

11. Wire Examples

Input — what arrives on the wire

{
  "intent_id": "intent_004",
  "market_id": "0xabc",
  "size_usd": 500,
  "side": "BUY",
  "price": 0.62
}

Output — what the bot emits

{
  "intent_id": "intent_004",
  "cost_estimate": {
    "slippage_bps": 35,
    "total_cost_bps": 235,
    "total_cost_usd": 11.75
  },
  "vote": "ANNOTATE"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "intent_id": "intent_004",
  "cost_estimate": {
    "maker_fee_bps": 0,
    "taker_fee_bps": 200,
    "builder_fee_bps": 0,
    "slippage_bps": 35,
    "total_cost_bps": 235,
    "total_cost_usd": 2.35,
    "method": "linear_with_safety_factor"
  },
  "vote": "ANNOTATE"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Dashboards

• 2.14 overview dashboard

16. Developer Reporting

"Per estimate: intent_id, market_id, size_usd, marketable_depth_usd, slippage_bps, fee_bps, total_cost_bps."

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Stateless. Reads live book + config; no persistence required.

State stores

Cold-start recovery

Cold-start hydrates from fast KV; missing keys default to safe fallback.

On restart

All in-flight decisions are re-evaluated; no bot decision is trusted across restart without re-emit.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Requires (graph.requires)

intel.orderflowanalyzer

Required before (graph.required_before)

exec.smart_router exec.order_shaper

23. Security Surfaces

No external surface; reads internal config + live book.

Signing surface

None — bot does not sign or submit.

Mitigations

• Rate-limit per source
• Audit-log every override
• Require role-based authz on admin paths

24. Polymarket V2 Compatibility

25. Versioning & Migration

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

If estimated-vs-realised drifts > 25%, re-tune slippage_safety_factor on a weekly cadence.

On-call actions

Manual overrides

• polytraders bot pause 2.14 — Disables the bot's enforcement layer; downstream consumers fall back to safe defaults.

Healthcheck

GET /healthz/fee_slippage_estimator → 200 if last successful evaluation < 60s ago.

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%