fix(gemini-titan): add terms acceptance flow before order submission

[AbhilashG12]

What this PR does

Adds automatic terms acceptance for Gemini-Titan orders.

The problem

Gemini now requires users to accept their Prediction Markets terms before placing orders. New API keys can't place any orders until terms are accepted.

The fix

PMXT now:

1. Checks if terms are accepted before placing an order
2. Auto-accepts terms if needed
3. Then places the order

Changes

• Added 3 new endpoints for terms management
• Updated order flow to check terms first
• Added unit tests (14 tests passing)

Fixes #1068

[realfishsam]

PR Review: FAIL

What This Does

Adds a Gemini Titan terms-acceptance preflight before submitOrder, plus new terms helpers and tests. This matters to SDK consumers because Gemini Titan order submission would now perform an extra venue-authenticated terms status/acceptance flow before submitting the order.

Blast Radius

Gemini Titan trading path only: GeminiFetcher.submitRawOrder() now calls ensureTermsAccepted() before /v1/prediction-markets/order. The change also adds Gemini terms endpoints to a new venue spec file and changes Gemini error mapping/export surface.

Consumer Verification

Before (base branch):
No terms preflight exists; submitRawOrder() directly posts the order payload to /v1/prediction-markets/order.

// base core/src/exchanges/gemini-titan/fetcher.ts
async submitRawOrder(payload) {
  return this.postAuthenticated('/v1/prediction-markets/order', payload);
}

After (PR branch):
The order path now calls ensureTermsAccepted(), but the preflight uses postAuthenticated() for the terms status endpoint:

// PR core/src/exchanges/gemini-titan/fetcher.ts:155-164
async getTermsStatus() {
  return this.postAuthenticated('/v1/prediction-markets/terms/status', {});
}

The same PR's OpenAPI/spec declares that endpoint as GET /v1/prediction-markets/terms/status (core/specs/gemini-titan/GeminiTitan.yaml:124-126). I could not verify against live Gemini credentials in this cron environment, but the code/spec mismatch means the consumer order path is very likely to send the wrong HTTP verb during the new preflight.

Test Results

• Build: PASS (npm run build --workspace=pmxt-core)
• Unit tests: PASS (6 passed, 0 failed via npm test --workspace=pmxt-core -- --runTestsByPath test/exchanges/gemini-titan-terms.test.ts --runInBand)
• Server starts: NOT VERIFIED (not needed to identify the blocking method/verb mismatch)
• E2E smoke: NOT VERIFIED (Gemini trading requires live venue credentials; not available in cron)

Findings

1. core/src/exchanges/gemini-titan/fetcher.ts:160 — getTermsStatus() sends POST /v1/prediction-markets/terms/status, while the PR's own spec defines GET /v1/prediction-markets/terms/status at core/specs/gemini-titan/GeminiTitan.yaml:124-126. Because submitRawOrder() now always runs this preflight first (fetcher.ts:212-214), a venue that only supports the documented GET status endpoint will reject the preflight before every order. The new Jest test does not catch this because it mocks getTermsStatus() instead of asserting the HTTP method/path used by the real implementation.
2. core/src/exchanges/gemini-titan/fetcher.ts:145-149 — getTerms() has the same verb mismatch: the PR spec defines GET /v1/prediction-markets/terms (GeminiTitan.yaml:99-101), but the implementation uses postAuthenticated(). This makes the new helper unusable if the venue follows the documented spec.

PMXT Pipeline Check

• Field propagation (3-layer): N/A
• OpenAPI sync: ISSUE — the added spec and implementation disagree on HTTP verbs for read-only terms endpoints.
• Financial precision: N/A
• Type safety: OK — core TypeScript build passed.
• Auth safety: OK — no credentials are logged; however, the new success/warn console output is noisy for library consumers.

Semver Impact

patch -- intended Gemini Titan trading bug fix with no SDK API break.

Risk

The preflight is on the order-submission path, so if Gemini's terms status endpoint is GET-only, all Gemini Titan order submissions will fail before reaching /order even for users whose terms are already accepted.

[AbhilashG12]

PR Updated ✅

Fix applied:

• getTerms() now uses GET (was POST)
• getTermsStatus() now uses GET (was POST)
• acceptTerms() remains POST ✅
• Unit tests updated to verify HTTP methods

[realfishsam]

PR Review: PASS (NOT VERIFIED)

What This Does

This adds a Gemini Titan terms-acceptance preflight before authenticated order submission. Before posting an order, the fetcher checks /v1/prediction-markets/terms/status, accepts /terms/accept when needed, then submits the original order payload.

Blast Radius

Gemini Titan authenticated trading paths only: submitRawOrder() / createOrder() now perform terms-status and possibly terms-accept API calls before /v1/prediction-markets/order. The PR also adds local Gemini API spec documentation and terms-specific error mapping. Market-data, normalizers, SDK shims, and generated files are not changed.

Consumer Verification

Before (base branch):
A direct consumer-path probe against the compiled base fetcher showed submitRawOrder() signing and posting only the order request; there was no terms status or accept call before order submission:

[
  ["headers", {"request":"/v1/prediction-markets/order","nonce":123,"symbol":"PM-GEMINI","side":"buy"}],
  ["POST", "https://api.gemini.com/v1/prediction-markets/order", {}, {"headers":{"X-GEMINI-PAYLOAD":"mock"}}]
]

After (PR branch):
The same compiled fetcher probe with mocked Gemini HTTP responses (hasAcceptedLatest: false) now checks status, accepts terms, and only then posts the original order:

[
  ["headers", {"request":"/v1/prediction-markets/terms/status","nonce":123}],
  ["GET", "https://api.gemini.com/v1/prediction-markets/terms/status", {"headers":{"X-GEMINI-PAYLOAD":"mock"}}],
  ["headers", {"request":"/v1/prediction-markets/terms/accept","nonce":123}],
  ["POST", "https://api.gemini.com/v1/prediction-markets/terms/accept", {}, {"headers":{"X-GEMINI-PAYLOAD":"mock"}}],
  ["headers", {"request":"/v1/prediction-markets/order","nonce":123,"symbol":"PM-GEMINI","side":"buy"}],
  ["POST", "https://api.gemini.com/v1/prediction-markets/order", {}, {"headers":{"X-GEMINI-PAYLOAD":"mock"}}]
]

I could not verify the real Gemini terms endpoints against production because this review environment does not have Gemini trading credentials and should not place live orders.

Test Results

• Build: PASS (npm run build --workspace=pmxt-core)
• Unit tests: PASS (npm test --workspace=pmxt-core: 708 passed, 3 skipped, 29 suites passed, 1 skipped)
• Server starts: PASS (GET /health returned {"status":"ok",...})
• E2E smoke: PASS for the local authenticated-order fetcher call sequence with mocked Gemini HTTP; NOT VERIFIED against live Gemini.

Findings

No blocking findings.

PMXT Pipeline Check

• Field propagation (3-layer): N/A — no unified response fields or SDK model fields were added.
• OpenAPI sync: N/A — no PMXT sidecar OpenAPI/SDK generation surface changed; the added YAML is a cached venue spec/documentation artifact.
• Financial precision: OK — order price/quantity serialization is unchanged by this PR.
• Type safety: OK — no observed runtime mismatch in the compiled fetcher path; the new tests cover status, accept, session cache, and order preflight behavior.
• Auth safety: OK — credentials are only used to build Gemini auth headers and are not logged or exposed in errors.

Semver Impact

patch -- authenticated Gemini order submission now performs a required venue preflight/acceptance flow without changing the public PMXT API.

Risk

The unverified risk is the exact live Gemini terms endpoint contract and whether the venue accepts authenticated GET for /terms/status with the same header-payload scheme used here. Local mocked consumer verification confirms PMXT calls the intended sequence, but live behavior remains credential-gated.