# MarketSchema Research

> Agent-native equity research. MarketSchema Research builds cited Deep Dive
> dossiers on public companies: primary sources are read, claims are verbatim-
> verified against their live source, and every export is a machine-readable
> Dossier Contract Object (DCO). Content only — not investment advice, and no
> buy/sell/price-target signal is ever exported.

Base URL: https://research.marketschema.com

## Final four-door product structure

Main navigation is locked in this exact order:

1. **Board** — `/`, the free front-door instrument.
2. **Deep Dive** — `/ticker/:symbol` (canonical default `/ticker/NVDA`), the paid question.
3. **Vault** — `/vault`, the proof surface for owned, cited documents.
4. **API** — `/developers`, the machine door.

Every other page lives in the footer or behind a locked page's tabs or disclosures. There is no fifth main-nav door.

## For agents and bots

- [Developer docs](https://research.marketschema.com/developers): endpoints, authentication, scopes, DCO object, rate limits, and errors.
- [Public validation scorecard](https://research.marketschema.com/scorecard): forward-outcome track record; stays INSUFFICIENT / null-signal until the archive earns it.
- [MS/1 discovery](https://api.marketschema.com/.well-known/ms1): the hub is the signing-key and countersign authority. Research's [same-origin door](https://research.marketschema.com/.well-known/ms1) permanently redirects here.
- Discovery availability does not mean every Research packet is signed. Trust each packet's explicit `signature.status` and verify signed packets against the hub key.

## Machine contracts (JSON Schema)

- [DCO v1 schema](https://research.marketschema.com/bot-contract/dco.v1.schema.json): the Dossier Contract Object — the full cited dossier export.
- [DCO read-envelope v1 schema](https://research.marketschema.com/bot-contract/dco-read-envelope.v1.schema.json): the envelope wrapping DCO read responses.
- [Evidence-delta SSO v1 schema](https://research.marketschema.com/bot-contract/evidence-delta.sso.v1.schema.json): the corroboration feed; cited context only, numeric values withheld.
- [Insight v1 schema](https://research.marketschema.com/bot-contract/insight.v1.schema.json): the content-only insight packet.
- [MS/1 v0 schema](https://research.marketschema.com/bot-contract/ms1.v0.schema.json): the Research measurement envelope and signature contract.

## Authentication

- Send a per-customer key in the `X-API-Key` header. Keys carry scopes; the server stores only a hash. Malformed or duplicate key records are ignored fail-closed.
- Scopes: `board:read` (GET /api/research/v1/board) and `dossiers:read` (GET /api/research/v1/dossiers/{ticker}, /ticker/{ticker}/latest, /ticker/{ticker}/history, /dossier/{run_id}, /evidence-delta). `GET /api/customer/usage` accepts any valid key.
- All key-scoped DCO read responses are customer-specific: `Cache-Control: private, no-store, max-age=0` with `Vary: X-API-Key`.

## Notes

- MCP read-plane wrapper: planned. Today the machine surface is the DCO read API + the JSON Schemas above.
- Everything served here is descriptive research provenance, not a recommendation, ranking, index, score, or trade input.