Add request idempotency key support to POST /api/stellar/send

[Codex723]

ISSUE #15

---

Category: Stellar API Routes
Difficulty: intermediate
Labels: backend, api, reliability, intermediate

Files involved

• src/app/api/stellar/send/route.ts

Background

A double-click or retried request currently creates duplicate pending Transactions. Accept an optional Idempotency-Key header and return the existing transaction if seen before.

This issue is part of the RemitX contributor backlog, generated from a full codebase audit of the project. RemitX is a Stellar-based remittance platform (Next.js 16, Prisma/Postgres, the Stellar SDK, and a Soroban escrow contract) currently at the "foundation build" stage: auth and the data model are real, while the Stellar integration, escrow contract internals, and several frontend pages are intentionally scaffolded with TODO(contributor) markers. See FOUNDATION.md in the repo root for the full project map and current status of every subsystem before starting.

Suggested approach

1. Review the current implementation in src/app/api/stellar/send/route.ts and confirm the stub/gap described below.
2. A double-click or retried request currently creates duplicate pending Transactions. Accept an optional Idempotency-Key header and return the existing transaction if seen before.
3. Handle the edge cases and failure modes called out in the acceptance criteria below (e.g. duplicate requests with the same key return the same transaction).
4. Manually verify the change against the acceptance criteria below before opening a PR.
5. Update any relevant comments/docs (e.g. remove the TODO(contributor) marker this issue resolves, if applicable).

Acceptance criteria

• Duplicate requests with the same key return the same transaction
• Keys expire after a reasonable TTL
• Documented in API docs

Notes for contributors

• Keep the change scoped to this issue — if you notice other stubs or bugs nearby, open a separate issue rather than bundling fixes into this PR.
• Match the existing code style in the surrounding file. This codebase uses TypeScript strict mode, Zod for input validation, and the shared successResponse/errorResponse helpers in src/lib/api-response.ts for every API route.
• If this issue depends on another issue in this area being done first, check the related issues below before starting — some subsystems (e.g. the escrow contract's release() authorization) need a design decision made before implementation can proceed.
• Please reference this issue number in your PR description, and check off acceptance criteria as you satisfy them.

Related issues in this area

• Wire POST /api/stellar/send to real rate + XDR build (end-to-end) #12 Wire POST /api/stellar/send to real rate + XDR build (end-to-end)
• Wire POST /api/stellar/submit to update Escrow record when applicable #13 Wire POST /api/stellar/submit to update Escrow record when applicable
• Add rate-limiting to /api/stellar/rate #14 Add rate-limiting to /api/stellar/rate
• Add pagination metadata and sorting options to GET /api/transactions #16 Add pagination metadata and sorting options to GET /api/transactions
• Add a GET /api/stellar/account route to fetch current user's Stellar balance #17 Add a GET /api/stellar/account route to fetch current user's Stellar balance