# Do Not Act Agent Docs

Do Not Act exposes authenticated dispute and resolution-intelligence endpoints plus anonymous discovery assets.

## Endpoints

- `GET /v1/preflight/{venue}/{market_id}`
- `GET /v1/resolution-risk/{venue}/{market_id}`
- `GET /v1/dispute/{venue}/{market_id}`
- `POST /v1/watchlist`
- `GET /v1/watchlist`
- `DELETE /v1/watchlist/{venue}/{market_id}`
- `GET /v1/alerts`

Public discovery:

- `GET /dispute-risk`
- `GET /dispute-risk.json`

## Required Agent Behavior

Preserve `verdict`, Risk Gateway `decision`, `component_scores`, `risk_factors`, `risk_factor_bitmap`, `risk_factor_bit_index`, `blocking_reasons`, `warning_reasons`, `safe_operating_limits`, `checks_evaluated`, `no_trade_reasons`, `what_would_change_this`, `not_advice`, `receipt`, alert payloads, and evidence gaps.

Never treat Do Not Act as a broker, custodian, signer, execution venue, or order router.

`DO_NOT_ACT` and `INSUFFICIENT_EVIDENCE` are blocking states. Agents should not continue until the evidence named in `what_would_change_this` changes.

## Contract

Use `/openapi.json` as the source of truth.

## Risk Gateway Preflight

`GET /v1/preflight/{venue}/{market_id}` keeps the original v1.1 response fields and adds Risk Gateway v1.2 fields for action-aware diagnostics.

Optional query parameters:

- `intent`: `enter`, `exit`, `hold`, `redeem`, or `monitor`.
- `side`: `buy_yes`, `buy_no`, `sell_yes`, `sell_no`, or `none`.
- `notional_usd` / `notional_eur`: context only; not a recommendation.
- `max_slippage_bps`: caller policy constraint.
- `policy`: `conservative`, `balanced`, or `aggressive`.
- `horizon`: `intraday`, `hold_to_resolution`, or `unknown`.

Preserve these additive fields when present: `risk_gateway_schema_version`, `risk_gateway_context`, `decision`, `risk_score`, `liquidity_confidence_score`, `liquidity_confidence_status`, `liquidity_confidence_basis`, `component_scores`, `risk_factors`, `risk_factor_bitmap`, `risk_factor_bit_index`, `blocking_reasons`, `warning_reasons`, `repair_hints`, `safe_operating_limits`, `freshness`, and `fail_closed`.

`safe_operating_limits` are conservative operational diagnostics derived from live CLOB/public orderbook evidence, not a Gamma-only flag. They are not trading advice, not position sizing, and not a guarantee of execution.

## Early-Warning Workflow

1. Call `POST /v1/watchlist` with a Polymarket `market_id`.
2. Optionally include `webhook_url` for push delivery.
3. Poll `GET /v1/alerts` as a backup and to inspect delivery status.
4. Treat `uma_dispute_already_active` and `uma_dispute_detected` as blocking alerts unless the operator explicitly decides otherwise.

Minimal watchlist body:

```json
{
  "venue": "polymarket",
  "market_id": "580810",
  "webhook_url": "https://agent.example/webhooks/donotact"
}
```

Delivery states:

- `sent`: webhook returned HTTP 2xx.
- `failed`: delivery failed or returned non-2xx.
- `queued`: alert is waiting for delivery.
- `not_configured`: no webhook/email target was configured.

Webhook failures are retried by the dispute-ledger refresh cycle up to the configured attempt limit. The alert feed reports aggregate delivery state under `delivery.webhook_delivery`.

Webhook requests include verification and routing headers:

- `X-DoNotAct-Webhook-Schema`
- `X-DoNotAct-Alert-Id`
- `X-DoNotAct-Alert-Type`
- `X-DoNotAct-Venue`
- `X-DoNotAct-Market-Id`
- `X-DoNotAct-Delivery-Attempt`
- `X-DoNotAct-Receipt-Status`
- `X-DoNotAct-Receipt-Key-Id` when signed
- `X-DoNotAct-Receipt-Signature` when signed
- `X-DoNotAct-Receipt-Payload-SHA256` when available

Agents should verify the receipt payload with `/.well-known/donotact-receipt-key.json` before treating a webhook as authenticated evidence.

## Access Requests

Use `X-API-Key: demo` on proof-set markets for immediate verification, or create a free account at `/signup` and generate a real key in `/account`. `POST /keys/request` is only the assisted review path.

Required JSON fields:

```json
{
  "email": "builder@example.com",
  "requested_tier": "free",
  "intended_use": "agent diagnostics integration",
  "accepts_terms": true
}
```

After a key is created in `/account`, operators can run `scripts/donotact_authenticated_smoke.py` in dry-run mode first, then with `--execute` only when `DONOTACT_API_KEY` is deliberately provided. The script must never print the key. The smoke covers the authenticated dispute, preflight, resolution-risk, and read-only alert-feed surfaces.

## Rejection Classes

Use `/docs/rejection-classes` for the synchronized R1-R8 `NoTradeReason.class` taxonomy. Preserve class and code values exactly.

## SDK Integration

Use `/examples/sdk-integration.md` for minimal Python, JavaScript, and direct HTTP examples. Agents must preserve blocking verdicts and receipts.

Use `/docs/integration-proof` for the black-box proof harness that validates direct HTTP and Python SDK `agent_guard` behavior against real markets `580810` and `541000`.

For the shortest integration path, use the composed SDK guard helpers:

- Python: `client.agent_guard(...)`
- JavaScript: `client.agentGuard(...)`

These helpers combine dispute lookup, optional watchlist registration, and alert polling into one fail-closed decision.

## MCP Integration

MCP-compatible agents can use these Do Not Act tools:

- `donotact_preflight`
- `donotact_resolution_risk`
- `donotact_dispute`
- `donotact_watchlist_add`
- `donotact_alerts`

For early-warning, use `donotact_dispute` for current lifecycle state, `donotact_watchlist_add` for recurring monitoring, and `donotact_alerts` as the delivery-status and backup feed.

Install metadata:

- Machine-readable: `/mcp.json`
- Well-known mirror: `/.well-known/mcp.json`
- Human install guide: `/docs/mcp`

## Receipts

Use `/docs/receipts` to understand the `receipt` object and offline verification flow. A receipt proves what Do Not Act returned; it is not permission to continue after a blocking verdict.

## Monthly Incident Reports

Use `/docs/monthly-incident-reports` for the offline export-and-report flow. Reports count diagnostic calls, fail-closed responses, source attribution, and reason-code distribution. They are not monetary savings reports, not outcome predictions, and not trading-performance reports.

## Agent Evaluation

Use `/docs/agent-evaluation` and `/examples/agent-evaluation-golden-prompts.json` to check whether an agent preserves the authenticated v1.1 contract, fail-closed verdicts, and product boundaries.

---

## Agent Discovery

- llms.txt: `/llms.txt`
- Full context: `/llms-full.txt`
- Agent manifest: `/agent.json`
- OpenAPI: `/openapi.json`
- Discovery docs: `/docs/discovery`