fix:adding idempotency to readme

Author: pengying

openapi/README.md

@@ -567,6 +567,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.