[API]: Define a versioned OpenAPI contract and generate typed clients

[grantfox-oss]

Context

API handlers currently use different methods, pagination shapes, success envelopes, validation approaches, and error payloads. Client services manually encode these contracts, making drift difficult to detect.

Scope

• Inventory all routes and define a versioned OpenAPI 3.1 specification.
• Standardize resource naming, methods, status codes, pagination metadata, filters, and error envelopes.
• Use shared Zod schemas as runtime validation and contract sources where practical.
• Generate a typed client consumed by frontend services instead of handwritten response casts.
• Add request/correlation IDs and stable machine-readable error codes.
• Provide a compatibility/deprecation plan for existing consumers.

Acceptance criteria

• Every existing endpoint and auth requirement appears in the specification.
• Request params/body and success/error responses are validated at runtime.
• CI fails when generated artifacts or route contracts drift.
• Frontend payout, auth, support, and bounty services use the generated types/client.
• Pagination and validation errors have one documented shape.
• A migration guide documents breaking and non-breaking evolution rules.

Relevant areas

src/app/api/**, module schemas/services, src/lib/axios.ts, response entity types.

[mubking]

Hi, I'm Mubarak — a Full-Stack & Blockchain Developer with 3+ years of experience. I've reviewed this issue and I'm confident I can handle it. I'll submit a clean PR within 2–3 days. Please assign it to me!