# Echo Oracle API Reference

Use the production Bankr endpoint for paid public calls and the VPS base for controlled review, discovery, and smoke tests.

```text
Production paid endpoint:
POST https://x402.bankr.bot/0x2a16625fad3b0d840ac02c7c59edea3781e340ae/echo-oracle

Review API base:
http://46.202.177.190:8793
```

## Request

```json
{
  "action": "Should my agent publish this launch announcement?",
  "context": "Optional facts, draft text, constraints, risk notes, or execution context.",
  "audience": "Base builders and autonomous agent developers",
  "risk_tolerance": "medium",
  "mode": "quick"
}
```

## Quick Curl

Review smoke call:

```bash
curl -s http://46.202.177.190:8793/api/ask \
  -H 'content-type: application/json' \
  -H 'x-payment: dev:test' \
  -d '{
    "action": "Should my agent publish this launch announcement?",
    "audience": "Base builders",
    "risk_tolerance": "medium",
    "mode": "quick"
  }'
```

Production paid callers should use the Bankr endpoint and normal x402 payment flow:

```bash
curl -i https://x402.bankr.bot/0x2a16625fad3b0d840ac02c7c59edea3781e340ae/echo-oracle \
  -H 'content-type: application/json' \
  -d '{
    "action": "Should my agent publish this launch announcement?",
    "audience": "Base builders",
    "risk_tolerance": "medium",
    "mode": "quick"
  }'
```

## Deep Curl

```bash
curl -i http://46.202.177.190:8793/api/ask \
  -H 'content-type: application/json' \
  -d '{
    "action": "Should my agent make this campaign the main public launch narrative?",
    "context": "We want a deeper social and market reaction read.",
    "mode": "deep"
  }'
```

## Response Fields

```json
{
  "decision": {
    "answer": "reframe",
    "confidence": 0.78,
    "risk": "medium",
    "recommendation": "Proceed only after reframing the action.",
    "reason": "The action has support, but the framing needs work.",
    "best_next_action": "Rewrite the action around concrete utility, proof, and expected user benefit.",
    "suggested_revision": "...",
    "expected_reaction": "...",
    "evidence": {}
  },
  "deep_run": null,
  "payment": {
    "rail": "x402",
    "status": "settled",
    "price_usd": 1
  }
}
```

Deep mode response:

```json
{
  "decision": {
    "answer": "maybe",
    "recommendation": "Deep simulation is queued. Wait for the MiroShark report before taking the external action."
  },
  "deep_run": {
    "run_id": "run_...",
    "status": "queued",
    "wait_url": "https://x402.miroshark.xyz/wait/run_...",
    "stages": ["ingest", "ontology", "graph_build", "create", "prepare", "simulate", "report"]
  }
}
```

## Errors

- `400`: invalid body or field.
- `402`: x402 payment required.
- `429`: rate limited; back off.
- `5xx`: retry with exponential backoff.

For deep mode, do not blindly retry paid requests after a network failure. Check whether the upstream run/payment already landed.

## Enforcement Notes

- `yes`: allow only if the caller has permission and budget.
- `reframe`: revise using `best_next_action` / `suggested_revision`, then resubmit if risk remains meaningful.
- `maybe`: wait, gather context, or review the deep report.
- `no`: deny by default.
- `dont_do_it`: hard deny unless an explicit override policy exists.