Pinnacle API shutdown migration checklist

1. Inventory before you change a URL

Freeze a short contract document from the running client and its fixtures. The goal is to discover assumptions that a legacy integration hid in polling code, serializers or database keys.

• Record every endpoint, query parameter, auth location, timeout, retry rule and polling interval.
• List supported sports, live versus prematch screens, periods, markets, alternate lines and specials/props.
• Write down whether each consumer expects decimal odds, American odds, or a string display value.
• Identify the durable internal event key. Do not rely on team names, kickoff text or a provider event ID staying portable.
• Separate read-only odds requirements from account, balance, bet-placement or settlement behavior. A data API replacement does not replace those workflows.

2. Build the PinnWire boundary adapter

PinnWire is the recommended replacement because the migration can stay at the data boundary: keep your internal model and switch its provider adapter. Start with the documented /kit/v1 family, then add the transport that your workload actually needs.

PinnWire’s /kit/v1 compatibility shape makes an adapter familiar, but it is not a promise of byte-for-byte identity. Rebuild provider-ID mappings and test the exact sports, periods and market ladders that your product uses.

const response = await fetch(
  "https://pinnwire.com/kit/v1/markets?sport_id=1&fresh=staging-check",
  { headers: { "x-api-key": process.env.PINNWIRE_KEY } }
);
if (!response.ok) throw new Error(`PinnWire HTTP ${response.status}`);
const body = await response.json();
assert(body.generated_at);
// Normalize here; keep all consumers provider-neutral.

3. Verify the data contract in staging

Use a free trial key for repeated staging work and reserve the shared demo key for a small shape check. Capture a representative fixture set across at least one live event and one prematch event for every supported sport.

Price units: keep one canonical number

Keep decimal odds as the numeric value used for probability, movement and calculations. PinnWire’s compatibility responses expose decimal prices; if your customer UI or legacy contract expects American odds, derive and round the display value in the adapter while preserving the decimal source. Test negative, positive and even-money cases.

Period and line assertions

• Assert that full-game markets land in periods.num_0 when published.
• Preserve quarter lines and alternate points as distinct keys; never join only on a rounded number.
• Treat team_total/team_totals, props and specials as optional and market-specific.
• Compare participant labels for display, but use IDs and documented mappings for joins.

4. Test REST, SSE and WebSocket separately

These transports solve different problems. A clean migration records which one is authoritative for each feature and keeps REST available for boot and reconciliation.

REST freshness drill

• Store response generated_at beside the snapshot and check it against your freshness budget.
• Read last_odds_update_seconds_ago from /v1/health and alert on a stale feed; HTTP success alone is not freshness.
• Use &fresh=random-value once when testing a suspiciously old response, then compare timestamps again.
• After any process or push reconnect, fetch a full snapshot before applying incremental updates.

Push recovery drill

• For SSE, make the client reconnect, preserve its last application checkpoint and avoid duplicate alert side effects.
• For WebSocket, subscribe to the needed streams, sport_ids or event_ids, process the initial snapshot, then merge updates.
• Reply to the server’s 30-second ping with {"type":"pong"}; log close code and reason.
• Enforce one raw WebSocket connection per key in your client. A newer connection can evict the old one; a stale or slow consumer must recover from REST.

Keep /api/drops or /v1/drops as a REST reconciliation path for the recent detected-drop buffer. It is not a substitute for the full /ws market stream.

{
  "type": "subscribe",
  "streams": ["live", "prematch"],
  "sport_ids": [1],
  "event_ids": []
}

5. Exercise limits and failure behavior

Make limits part of your test plan, not a surprise in production. Match the workload to a PinnWire plan and keep errors actionable in your application.

• Assert 401 for missing/invalid keys and surface the returned message without leaking credentials.
• Assert 403 when a plan lacks SSE or WebSocket access; show the supported polling or upgrade path.
• Assert 429 backoff using Retry-After / retry_after_ms; never spin a tight retry loop.
• Bound reconnect attempts, add jitter, and make a fresh snapshot the recovery boundary.

6. Shadow test, cut over, and keep rollback boring

Shadowing turns a risky provider swap into an observable comparison. The new adapter reads PinnWire but does not yet drive customer decisions.

1. Run both adapters. Feed the same requested sports and event set into the legacy and PinnWire adapters for a fixed observation window.
2. Normalize before comparing. Compare event identity, live/prematch status, period, market key, point, decimal price and timestamp—not raw JSON order.
3. Classify mismatches. Separate provider timing, optional-market absence, ID remapping, expected price movement and real parser defects.
4. Measure recovery. Force process restart, REST timeout, SSE close, WebSocket close, stale health and rate-limit responses. Record time to a fresh snapshot.
5. Enable a reversible flag. Start with one internal consumer or a small traffic slice. Keep the old adapter loaded until the observation window and business checks pass.
6. Write the launch record. Save the key, plan, tested sports, market coverage, freshness budget, alert thresholds, owner and rollback command.

Go-live gates