Document GET /v2/markets and provider rate position in API reference

[chibie]

Parent issue: paycrest/aggregator#808 (sub-issue — API reference for markets orderbook and provider rate position)

User Story

As an integrator or provider reading Paycrest docs, I want the API reference to document the new public GET /v2/markets orderbook endpoint and the extended GET /provider/rates/{token}/{fiat} response (including per-side position), so I can integrate against the live markets feed and understand provider rate benchmarking without reading aggregator source code.

Acceptance Criteria

1. GIVEN parent issue paycrest/aggregator#808 is merged WHEN docs are published THEN openapi-v2.yaml documents GET /v2/markets and the updated provider market-rate schemas.
2. GIVEN GET /v2/markets THEN a new MDX page exists under API Reference (General group, v2 tab) describing the endpoint, auth (none), CORS, response shape { as_of, aggregates, book }, and example JSON.
3. GIVEN each book row THEN docs describe: provider_id, side (buy|sell), token, fiat, network, rate, balance, balance_ccy, balance_usd, success_pct, settled — and how sell vs buy liquidity/rate are derived (aligned with #808).
4. GIVEN aggregates THEN docs list network-wide stats returned (24h/7d/30d/all-time volume & txns, success rate windows, live liquidity USD, active providers/apps, median delivery seconds, corridor/token/network counts).
5. GIVEN GET /provider/rates/{token}/{fiat} (v1 and v2 provider routes) THEN existing Get Market Rate page and OpenAPI schema are updated to document optional nested position on each side (buy, sell).
6. GIVEN position THEN docs describe exactly three fields: bestPublicRate, yourEffectiveRate, deltaVsBest (yourEffectiveRate - bestPublicRate); sell best = highest effective sell; buy best = lowest effective buy; computed across all enabled non-testnet networks (no network query param).
7. GIVEN position semantics THEN docs explain when position is omitted/null, that reference fields (marketRate, minimumRate, maximumRate) are unchanged, and how to interpret deltaVsBest per side for competitive pricing.
8. GIVEN navigation THEN docs.json v2 API Reference includes the new markets page; provider get-market-rate remains in the Provider group.
9. GIVEN release visibility THEN resources/changelog.mdx includes a Q2 2026 entry linking to both updated pages (after aggregator release).
10. GIVEN v1 provider market rate page THEN get-market-rate-v1.mdx notes the same position shape applies when served from aggregator v1/v2 provider routes (response parity).

Tech Details

• OpenAPI (openapi-v2.yaml):
  • Add GET /markets under General (or Markets) tag — public, no security.
  • Add schemas: MarketsResponse, MarketsAggregates, MarketOffer, MarketPosition.
  • Extend MarketRateSide with optional position → $ref: MarketPosition.
• New MDX: api-reference/general/get-markets.mdx — follow pattern of get-token-rate.mdx (path params if any, example request/response, field tables, errors).
• Update MDX: api-reference/provider/get-market-rate.mdx — extend response table and add position example JSON; keep v1 note.
• Update MDX: api-reference/provider/get-market-rate-v1.mdx — brief cross-link to v2 page for full position documentation.
• Nav: add api-reference/general/get-markets to docs.json v2 → General group (suggest after get-token-rate).
• Changelog: new subsection under Q2 2026 after aggregator ships.
• Coordinate field names and types with aggregator types/types.go from #808 (decimals as strings in JSON examples, matching existing docs convention).
• Do not document a separate /benchmark endpoint — only the extended provider rates route.

Notes/Assumptions

• Blocked by parent paycrest/aggregator#808; docs PR can be drafted against the issue spec but should merge after or with the aggregator release.
• Public markets intentionally expose balances and success rates — state that clearly on the markets page.
• Qualifying offer filters match #808 (public, active, funded, is_available, enabled fiat/token, non-testnet network).
• Dashboard UI for displaying position is out of scope (separate dashboard ticket); docs cover API only.
• Optional: add a short cross-link from provider-setup-guide.mdx to Get Market Rate position section.

References

• Parent: paycrest/aggregator#808
• Related: paycrest/aggregator#806 (per-fiat visibility may affect qualifying pool — note when shipped)