# Devil's Advocate — API overview

**Production origin:** `https://devadv.top`

Devil's Advocate combines two paid JSON APIs (when **x402** billing is on): **`POST /check_risk`** runs a **thesis risk audit** (curated headline archive → bear-case style report, **narrative heat**, assumptions checklist; optional `ticker` / `tickers`). **`POST /check_risk_stocks`** returns a **single US equity** multi-agent view (`summary` + `agent_analysis`; optional `start_date` / `end_date`). **`GET /health`** is free. Responses are JSON for agents and dashboards.

---

## Endpoints

| Method | Path | Billing | Summary |
|--------|------|---------|---------|
| `GET` | `/health` | None | Plain text body: `ok`. |
| `POST` | `/check_risk` | **x402 v2** (USDC on Base) when enabled | Thesis stress-test; optional symbols for retrieval. |
| `POST` | `/check_risk_stocks` | **x402 v2** with a **separate** USDC price when enabled | One ticker; six fixed analysts + portfolio action; long-running (minutes). |

When **x402** is enabled, an unpaid `POST` may return **HTTP 402** with **`PAYMENT-REQUIRED`** (base64 JSON). Retry the **same URL, method, and JSON body** with **`PAYMENT-SIGNATURE`**. On success, **`PAYMENT-RESPONSE`** usually appears on **200**. It can also appear on a controlled **5xx** if settlement succeeded but downstream work failed—**treat billing and product outcome separately**.

---

## Billing (typical values)

Exact amounts always come from the live offer in **`PAYMENT-REQUIRED`** (`accepts[].amount`, **6 decimals** for USDC). Defaults in the bot’s `.env.example` are often:

| Path | Typical `amount` (minimal units) | Rough USDC |
|------|----------------------------------|------------|
| **`POST /check_risk`** | `500000` | **~0.50 USDC** |
| **`POST /check_risk_stocks`** | `5000000` | **~5.00 USDC** |

Network: **Base mainnet** (`eip155:8453`). Asset: **USDC** (`accepts[].asset`). **`resource.url`** in the offer must match the path you pay for (`…/check_risk` vs `…/check_risk_stocks`).

---

## `POST /check_risk`

- **URL:** `https://devadv.top/check_risk`
- **Content-Type:** `application/json`
- **Body:** `{ "thesis": "<required text>", "ticker": "<optional>", "tickers": ["<optional>"] }`

**Successful response (200):** JSON object

- `task_id` — correlation id for support and logs  
- `check_risk_response` — full text report  
- `narrative_heat` — `low` \| `medium` \| `high` (or empty if parsing failed)  
- `narrative_heat_score` — integer 0–100  

**Client header:** `X-Client` — optional label for your integration (logged server-side).

### x402 v2 payment flow

When billing is active for this route:

1. **First** `POST` without `PAYMENT-SIGNATURE` → **HTTP 402** with header **`PAYMENT-REQUIRED`** (base64 JSON `PaymentRequired`).  
2. Complete payment per `accepts[]` (scheme `exact`, network `eip155:8453`, USDC on Base, amount in minimal units, `payTo` as advertised).  
3. **Retry** the same URL, method, and JSON body with header **`PAYMENT-SIGNATURE`** (base64 JSON `PaymentPayload` per x402 v2).  
4. **200** includes the report JSON and, when applicable, header **`PAYMENT-RESPONSE`** (settlement).

Use a maintained **x402 client/SDK** to build `PAYMENT-SIGNATURE`; do not hand-roll EIP-3009 / Permit2 payloads.

### Example (discovery `curl`, may return 402)

```bash
curl -sS -D - -o /tmp/body.json \
  -H 'Content-Type: application/json' \
  -H 'X-Client: partner-integration' \
  -d '{"thesis":"Long BTC on ETF flows; main risk is regulation","ticker":"btc"}' \
  'https://devadv.top/check_risk'
```

### Worked example: BTC thesis (HTTP 200 after payment)

**Request**

```json
{
  "thesis": "BTC is a long-term portfolio anchor: fixed supply narrative and institutional adoption outweigh short-term volatility; we accept deep drawdowns for asymmetric upside over a multi-year horizon.",
  "ticker": "BTC"
}
```

**Response** — long `check_risk_response` trimmed with `…` in the middle; full text in harness artifact **`x402-consumer`** repo: `docs/responses/devadv-check_risk.btc.json` (same `task_id` / fields as **прогон P** in `devadv-checkrisk.md` §9).

```json
{
  "task_id": "b59931be-92e5-412a-ac7e-9fa3e41ebbf3",
  "check_risk_response": "1) Fixed supply doesn't equal stable monetary premium; …\n\n2) Institutional adoption can increase correlation …\n\n3) Tail risks are not just volatility—they're protocol/governance …\n\nnarrative heat: high (78/100)\n\nAssumptions checklist\n- …",
  "narrative_heat": "high",
  "narrative_heat_score": 78
}
```

---

## `POST /check_risk_stocks`

- **URL:** `https://devadv.top/check_risk_stocks`
- **Content-Type:** `application/json`
- **Body:** `{ "ticker": "AAPL", "start_date": "<optional YYYY-MM-DD>", "end_date": "<optional YYYY-MM-DD>" }` — one symbol only; do **not** send a `tickers` array. Dates are optional and inclusive; if both are omitted, the upstream window is the last three calendar months through today. If only `end_date` is set, the start defaults to three months before that end. If only `start_date` is set, the end defaults to today. If both are set, `start_date` must be on or before `end_date`.

**Successful response (200):** JSON with `task_id`, `summary` (ticker, portfolio-level `action`, bullish/bearish/neutral counts from six fixed analysts), and `agent_analysis` (per-analyst rows: display name, `signal`, `confidence`, `reasoning`).

**Timeouts:** upstream analysis can take **minutes**; use a long HTTP read timeout (nginx uses a higher limit for this path than for `/check_risk`).

The x402 flow matches `/check_risk` (402 → pay → retry with `PAYMENT-SIGNATURE`), but **`resource.url` and the billed amount** are specific to `/check_risk_stocks`.

### Worked example: BABA (HTTP 200 after payment)

**Request**

```json
{
  "ticker": "BABA",
  "start_date": "2026-04-15",
  "end_date": "2026-06-15"
}
```

**Response** — abbreviated; the full payload has **six** `agent_analysis` entries. Full JSON: **`x402-consumer`** `docs/responses/devadv-check_risk_stocks.baba.json`; request / headers / decoded **`PAYMENT-RESPONSE`**: `devadv-check_risk_stocks.baba.debug.txt`.

```json
{
  "task_id": "1af4f1b9-6b9c-4a98-9cc8-ee96a20fc514",
  "summary": {
    "ticker": "BABA",
    "action": "HOLD",
    "bullish": 1.0,
    "bearish": 2.0,
    "neutral": 3.0
  },
  "agent_analysis": [
    {
      "agent": "Fundamentals Analyst",
      "signal": "bearish",
      "confidence": 50.0,
      "reasoning": {
        "profitability_signal": {
          "signal": "bearish",
          "details": "ROE: 9.10%, Net Margin: 9.10%, Op Margin: 12.82%"
        },
        "growth_signal": {
          "signal": "bearish",
          "details": "Revenue Growth: 0.46%, Earnings Growth: -26.54%"
        },
        "financial_health_signal": {
          "signal": "neutral",
          "details": "Current Ratio: 1.33, D/E: 0.74"
        },
        "price_ratios_signal": {
          "signal": "neutral",
          "details": "P/E: 25.79, P/B: 2.30, P/S: 2.35"
        }
      }
    }
  ]
}
```

---

## Machine-readable descriptors & operations

| Resource | URL |
|----------|-----|
| OpenAPI 3.1 | `https://devadv.top/x402/openapi.json` |
| Agent catalog | `https://devadv.top/.well-known/agent-catalog.json` |
| AI plugin manifest | `https://devadv.top/.well-known/ai-plugin.json` |

**Operations:** nginx applies per-IP **rate limits** on API paths (expect **429** if you burst). Production uses **HTTPS** (`https://devadv.top/...`).