---
title: "Pre Trade Check"
method: POST
path: "/check"
---

# Pre Trade Check

`POST /check`

## Request

- Base URL: `https://api.n0brains.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.n0brains.com/check`
- Auth: none declared

Ask n0brains First — graded pre-trade CONDITIONS ASSESSMENT for a
proposed trade. Body: {asset, side (long/short), entry?, stop?, target?,
leverage?, horizon_hours? (default 24)}. Returns grade A..F, flags
(crowding, event risk inside horizon, liquidation-distance vs realized
vol, stop-vs-noise, proven-edge conflicts, TA extension), supporting
factors, and falsifiers to watch. Every check is logged and resolved at
its horizon; cross-grade performance stays withheld until the weekly truth
gate clears. Free tier:
FREE_CHECKS_PER_DAY checks/day; Pro unlimited (within rate limits).
Analytical, not advice.

## Headers

- `Idempotency-Key` string: Printable, at most 128 characters.

## Request body

- object: POST /check body. asset + side are required; everything else refines the assessment (a bare check is honestly graded on direction alone).
  - `asset` string, required: Asset symbol, e.g. BTC / NVDA / GOLD. maxLength 10 is documentation of the route's own check: overlength is the route's BUSINESS-SEMANTIC typed 400 (never an automatic schema 422 — this schema is doc-only and never bound to the handler).
  - `side` string, required: long/buy/bullish or short/sell/bearish.
  - `entry` number, nullable: Intended entry price.
  - `stop` number, nullable: Stop price.
  - `target` number, nullable: Target price.
  - `leverage` number, nullable: Position leverage; must be > 0 when given (0 or negative is a 400 VALIDATION_ERROR).
  - `horizon_hours` integer, nullable: Assessment horizon in hours (default 24).
  - `chart` boolean, nullable: When true, a branded PNG chart is attached as `chart_png_b64` (web surface; mobile should omit). Boolean or absent ONLY — any other JSON type is a typed 422.

## Response `200`

Graded assessment (typed; additive-only — ignore unknown fields). A replay of an earlier submission under the same key is byte-identical to the original response and carries no replay marker.

- CheckResponse: POST /check 200 — the graded assessment. Additive contract: new fields may appear at any time; clients must ignore unknown fields. `grade` uses the ACTIVE v3 set only (historical `B+` never appears here).
  - `asset` string, required
  - `side` 'bullish' | 'bearish', required
  - `entry` number, nullable
  - `spot` number, nullable
  - `stop` number, nullable
  - `target` number, nullable
  - `leverage` number, nullable
  - `horizon_hours` integer, required
  - `venue_ticker` string, nullable
  - `price_note` string, nullable
  - `unlock_events` CheckUnlockEvent[], nullable
    - `unlock_ts` integer, required
    - `amount_usd` number, nullable
    - `pct_circ_supply` number, nullable
    - `category` string, nullable
  - `grade` 'A' | 'B' | 'C' | 'D' | 'F', required
  - `score` number, required: Calibrated win probability 0..1 (equals scoring.applied.p_cal; 0.0 on fatal geometry).
  - `verdict` string, required
  - `flags` CheckFlag[], required
    - `check` string, required: Flag family identifier.
    - `severity` string, nullable: fatal/high/medium/low — DISCLOSURE ONLY except fatal (structural tier). Flags never move the probability in v3.
    - `note` string, nullable
    - `falsifier` string, nullable
  - `supports` CheckSupport[], required
    - `check` string, required
    - `support` boolean, nullable
    - `note` string, nullable
  - `falsifiers` string[], required
  - `viability` CheckViability, required
    - `caps` CheckViabilityCap[], required
      - `constraint` string, required: liq_distance / stop_placement / risk_reward / stop_missing
      - `cap` string, required: The letter ceiling this cap applies (C or F).
      - `binding` string, required
      - `falsifier` string, required
    - `note` string, required
  - `unchecked` string[], required
  - `terrain` CheckTerrain
    - `funding_z` number, nullable
    - `daily_vol_pct` number, nullable
    - `nearest_resistance` CheckTerrainLevel
      - `price` number, required
      - `dist_pct` number, nullable
      - `strength` number, nullable
    - `nearest_support` CheckTerrainLevel
      - `price` number, required
      - `dist_pct` number, nullable
      - `strength` number, nullable
    - `nearest_liq_above` CheckTerrainLevel
      - `price` number, required
      - `dist_pct` number, nullable
      - `strength` number, nullable
    - `nearest_liq_below` CheckTerrainLevel
      - `price` number, required
      - `dist_pct` number, nullable
      - `strength` number, nullable
    - `notes` string[], nullable
  - `regime` string, nullable
  - `state_direction` string, nullable
  - `realized_daily_vol_pct` number, nullable
  - `asset_class` string, nullable
  - `hip3_market` string, nullable
  - `engine_version` string, required
  - `scoring` CheckScoring, required
    - `engine_version` string, required
    - `model` string, nullable
    - `definition` string, nullable
    - `probability_model` string, nullable
    - `calibration` CheckCalibrationMeta
      - `spec` string, nullable
      - `fitted_at` integer, nullable
      - `corpus` CheckCalibrationCorpus
        - `start_ts` integer, nullable
        - `end_ts` integer, nullable
        - `n_geo` integer, nullable
        - `n_bare` integer, nullable
        - `skipped` integer, nullable
        - `prior_weight` number, nullable
      - `note` string, nullable
    - `severity_semantics` string, nullable
    - `grade_bands` array[], nullable
      - unknown[]
        - unknown
    - `applied` CheckScoringApplied, required: The values actually used for THIS grade — reconstructs the letter exactly (pure-gate contract).
      - `fatal` boolean, required
      - `bare` boolean, nullable
      - `method` string, nullable: lattice / gambler_no_sigma / prior_no_geometry / prior_no_sigma; null when fatal.
      - `p_raw` number, nullable
      - `p_cal` number, nullable
      - `calibration_bin` CheckCalibrationBin
        - `lo` number, nullable
        - `hi` number, nullable
        - `n` integer, nullable
        - `wins` integer, nullable
      - `band_from_probability` string, nullable
      - `letter_caps_applied` CheckLetterCap[], required
        - `cap` string, required: 'fatal' or 'viability:<constraint>'.
        - `to` string, nullable
        - `from` string, nullable
      - `grade` 'A' | 'B' | 'C' | 'D' | 'F', required
      - `score` number, required
    - `bands_active` string[], required
    - `bands_note` string, nullable
    - `derivation` string, nullable
  - `receipts` string, nullable: Proof provenance reference (n0brains.com/proof). Mobile v1 does not render it as an external link.
  - `note` string, nullable
  - `disclaimer` CheckDisclaimer, required
    - `en` string, required
    - `tr` string, required
  - `server_timestamp` integer, required
  - `free_checks_remaining_today` integer, nullable
  - `chart_png_b64` string, nullable
  - `measurement_recorded` boolean, nullable

## Other responses

- `202`: Data still warming — no grade yet, no quota consumed, no history row written. `Retry-After` is set; REUSE THE SAME KEY, which keeps the logical identity of the check and stops a second engine run.
- `400`: BUSINESS-SEMANTIC validation failure: leverage <= 0, an invalid side value, an unknown asset, an asset symbol over 10 characters, or a malformed Idempotency-Key. error.code=VALIDATION_ERROR.
- `401`: No/invalid credentials. error.code distinguishes SESSION_EXPIRED (sign out) from INVALID_API_KEY.
- `409`: Two distinct situations, told apart by `error.code`. `IDEMPOTENCY_CONFLICT` — the Idempotency-Key cannot be used for this request, because either its request payload conflicts with the original request under that key, or the key refers to a legacy incomplete result that cannot be safely replayed. Both are terminal: mint a fresh key. `error.message` states which of the two applies. `IDEMPOTENCY_IN_PROGRESS` — the key is currently being computed; retry the SAME key after `Retry-After` / `error.retry_after_seconds`.
- `422`: STRUCTURAL/PARSING failure: malformed JSON, non-object body, missing asset/side, wrong field type, or a non-integer horizon_hours. error.code=VALIDATION_ERROR; never a sign-out signal. (Contract requires JSON numbers for numeric fields.)
- `429`: Two distinct situations, told apart by `error.code`. `CHECK_DAILY_LIMIT` — the free tier's daily successful-check quota is spent; `error.reset_at` carries the next 00:00 UTC reset (ISO-8601) and `Retry-After`/`error.retry_after_seconds` the wait. `RATE_LIMITED` — transient per-minute limit; retry after `Retry-After`. No response body contains a pricing or upgrade URL.
- `503`: Recording/measurement layer unavailable — a check that cannot be logged is not served. error.code=SERVICE_TEMPORARILY_UNAVAILABLE. Data warming is NEVER a 503 on this route; warming is the typed 202 only.

---

[API](https://skmtc.dev/n0brains/apis/n0brains-signals-api.md) · [All operations](https://skmtc.dev/n0brains/apis/n0brains-signals-api/llms.txt) · [OpenAPI document](https://skmtc.dev/n0brains/apis/n0brains-signals-api/revisions/ac21b5aebd10?raw)