fix:adding idempotency to readme (#267)

### TL;DR

Added comprehensive idempotency documentation to the OpenAPI README,
covering requirements for money movement endpoints, implementation
details, and SDK usage examples.

### What changed?

Added a new "Idempotency" section to the OpenAPI README that includes:

- Requirements for endpoints that trigger money movement to support
idempotency
- Reference to the IETF Idempotency-Key HTTP Header Field specification
- Table listing specific endpoints requiring idempotency (`POST /quotes`
with `immediatelyExecute: true`, `POST /quotes/{quoteId}/execute`, `POST
/transfer-in`, `POST /transfer-out`)
- Detailed explanation of how idempotency works with different response
scenarios (2xx/4xx stored, 5xx retried)
- Code examples for TypeScript and Kotlin SDKs showing idempotency key
usage
- Design guidelines for adding new money movement endpoints

### How to test?

Review the documentation for accuracy and completeness. Verify that the
listed endpoints and SDK examples align with the actual API
implementation and SDK interfaces.

### Why make this change?

This documentation ensures developers understand how to properly
implement idempotency for financial operations, preventing duplicate
transactions that could occur due to retries, network failures, or
client timeouts. Clear guidelines also help maintain consistency when
adding new money movement endpoints.

Author: pengying

mintlify/openapi.yaml

@@ -616,6 +616,62 @@ All errors follow a consistent structure:
 
 ---
 
+## Idempotency
+
+Any API endpoint that triggers money movement **must** support idempotency to prevent duplicate transactions caused by retries, network failures, or client timeouts.
+
+We follow the [IETF Idempotency-Key HTTP Header Field](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) specification.
+
+### Endpoints Requiring Idempotency
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /quotes` (with `immediatelyExecute: true`) | Creates and executes a quote in one step |
+| `POST /quotes/{quoteId}/execute` | Executes a previously created quote |
+| `POST /transfer-in` | Initiates an inbound transfer |
+| `POST /transfer-out` | Initiates an outbound transfer |
+
+### How It Works
+
+Clients include an `Idempotency-Key` header with a unique value (typically a UUID) on the request. The server uses this key to deduplicate requests:
+
+- **First request**: Processes normally and stores the response keyed by the idempotency key.
+- **Subsequent requests with the same key (2xx or 4xx)**: Returns the stored response without reprocessing. The response status code and body will match the original response.
+- **Subsequent requests with the same key (5xx)**: Server errors are not stored — the request will be retried and processed again, allowing recovery from transient failures.
+- **Different key**: Treated as a new request.
+
+```
+POST /quotes/{quoteId}/execute
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+```
+
+### SDK Support
+
+Our SDKs support idempotency keys via request options:
+
+```typescript
+// TypeScript
+await client.quotes.execute('Quote:123', {
+  idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
+});
+```
+
+```kotlin
+// Kotlin
+client.quotes().execute("Quote:123", RequestOptions.builder()
+    .idempotencyKey("550e8400-e29b-41d4-a716-446655440000")
+    .build())
+```
+
+### Design Guidelines
+
+When adding a new endpoint that triggers money movement:
+
+1. Document that the endpoint supports idempotency in the operation description
+2. Include the `Idempotency-Key` header in the OpenAPI spec parameters
+
+---
+
 ## Stainless SDK Patterns
 
 Our SDKs are generated by [Stainless](https://www.stainless.com/) from the OpenAPI spec.

openapi.yaml

@@ -22,6 +22,16 @@ post:
     - Cross-Currency Transfers
   security:
     - BasicAuth: []
+  parameters:
+    - name: Idempotency-Key
+      in: header
+      required: false
+      description: >
+        A unique identifier for the request. If the same key is sent multiple times,
+        the server will return the same response as the first request.
+      schema:
+        type: string
+        example: <uuid>
   requestBody:
     required: true
     content:

openapi/README.md

@@ -21,6 +21,15 @@ post:
       schema:
         type: string
       example: Quote:019542f5-b3e7-1d02-0000-000000000001
+    - name: Idempotency-Key
+      in: header
+      required: false
+      description: >
+        A unique identifier for the request. If the same key is sent multiple times,
+        the server will return the same response as the first request.
+      schema:
+        type: string
+        example: <uuid>
   responses:
     '200':
       description: >