openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "StreamPay API",
    "version": "2.0.0",
    "description": "REST API for the StreamPay payment-streaming platform on Stellar.\n\nAll error responses use the canonical envelope:\n```json\n{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"Human-readable detail.\", \"request_id\": \"req_...\" } }\n```\n\nv1 stream paths (`/api/streams`) are deprecated and will be removed. Use `/api/v2/streams`."
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque",
        "description": "Obtain a token via POST /api/auth/wallet, then pass it as `Authorization: Bearer <token>`."
      }
    },
    "schemas": {
      "MultiRecipientLegV2": {
        "type": "object",
        "required": [
          "rank",
          "stream_id",
          "address",
          "percentage",
          "amount"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "1-based position of this leg within the allocation."
          },
          "stream_id": {
            "type": "string",
            "description": "Id of the stream leg written for this recipient; fetch it with GET /api/v2/streams/{id}."
          },
          "address": {
            "type": "string",
            "description": "Stellar ed25519 public key or registered email address, as supplied."
          },
          "percentage": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{4})?$",
            "description": "Share of the total, as a fixed 4-decimal string."
          },
          "amount": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{7})?$",
            "description": "Amount owed to this leg, as a fixed 7-decimal string. The legs sum exactly to total_amount."
          }
        }
      },
      "MultiRecipientStreamV2": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "name",
          "token",
          "status",
          "total_amount",
          "allocated_percentage",
          "recipient_count",
          "start_at",
          "end_at",
          "created_at",
          "settlement",
          "recipients",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the fan-out itself. It is not a stream; the legs are.",
            "example": "stream-multi-8f3c1a90"
          },
          "kind": {
            "type": "string",
            "enum": [
              "multi_recipient"
            ]
          },
          "name": {
            "type": "string"
          },
          "token": {
            "type": "string",
            "enum": [
              "XLM",
              "USDC"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft"
            ],
            "description": "Every leg is created in `draft`; drive them with the start/pause/stop/settle endpoints."
          },
          "total_amount": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{7})?$",
            "description": "Total distributed across all legs, as a fixed 7-decimal string."
          },
          "allocated_percentage": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{4})?$",
            "description": "Sum of the allocation, as a fixed 4-decimal string. Always 100.0000 for an accepted request."
          },
          "recipient_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          },
          "start_at": {
            "type": "string",
            "format": "date-time"
          },
          "end_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "settlement": {
            "type": "object",
            "nullable": true,
            "description": "Always present; null until a leg settles."
          },
          "recipients": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/MultiRecipientLegV2"
            }
          },
          "links": {
            "type": "object",
            "required": [
              "self",
              "collection"
            ],
            "properties": {
              "self": {
                "type": "string"
              },
              "collection": {
                "type": "string"
              }
            }
          }
        }
      },
      "CircuitBreakerState": {
        "type": "object",
        "required": [
          "open",
          "updatedAt",
          "updatedBy"
        ],
        "properties": {
          "open": {
            "type": "boolean",
            "description": "True when the breaker is tripped and dispatch is halted."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "ISO-8601 timestamp of the last toggle; null if never toggled."
          },
          "updatedBy": {
            "type": "string",
            "nullable": true,
            "description": "Admin address that last toggled this breaker; null if never toggled."
          }
        }
      },
      "CircuitBreakers": {
        "type": "object",
        "required": [
          "indexer",
          "webhook"
        ],
        "properties": {
          "indexer": {
            "$ref": "#/components/schemas/CircuitBreakerState"
          },
          "webhook": {
            "$ref": "#/components/schemas/CircuitBreakerState"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code.",
                "example": "NOT_FOUND"
              },
              "message": {
                "type": "string",
                "description": "Human-readable description safe to display to clients.",
                "example": "The requested stream does not exist."
              },
              "request_id": {
                "type": "string",
                "description": "Opaque identifier for this request, useful for log correlation.",
                "example": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "StreamV1": {
        "type": "object",
        "description": "v1 payment stream shape. **Deprecated** \u2014 use `StreamV2` via `/api/v2/streams`.",
        "required": [
          "id",
          "recipient",
          "rate",
          "schedule",
          "status",
          "nextAction",
          "token",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique stream identifier.",
            "example": "stream-abc12345"
          },
          "recipient": {
            "type": "string",
            "description": "Stellar public key of the payment recipient.",
            "example": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG"
          },
          "rate": {
            "type": "string",
            "description": "Numeric payment amount per schedule interval.",
            "example": "120"
          },
          "schedule": {
            "type": "string",
            "enum": [
              "second",
              "minute",
              "hour",
              "day",
              "week",
              "month",
              "year"
            ],
            "description": "Payment interval.",
            "example": "month"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "active",
              "paused",
              "ended"
            ],
            "description": "Current lifecycle state of the stream."
          },
          "nextAction": {
            "type": [
              "string",
              "null"
            ],
            "description": "The next permitted action for the authenticated user.",
            "example": "start"
          },
          "token": {
            "type": "string",
            "description": "Stellar asset code.",
            "example": "XLM"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 creation timestamp.",
            "example": "2024-01-15T10:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 last-updated timestamp.",
            "example": "2024-01-15T10:00:00.000Z"
          }
        }
      },
      "StreamV2": {
        "type": "object",
        "required": [
          "id",
          "recipient",
          "rate",
          "status",
          "allowed_actions",
          "created_at",
          "settlement"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique stream identifier.",
            "example": "stream_lf3k9z"
          },
          "recipient": {
            "type": "string",
            "description": "Stellar public key of the payment recipient.",
            "example": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG"
          },
          "rate": {
            "type": "string",
            "description": "Human-readable payment rate.",
            "example": "120 XLM/month"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "active",
              "paused",
              "ended"
            ],
            "description": "Current lifecycle state of the stream."
          },
          "allowed_actions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Actions the authenticated user may perform on this stream. Replaces v1 `actions`.",
            "example": [
              "pause",
              "stop"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 creation timestamp. Replaces v1 `createdAt`.",
            "example": "2024-01-15T10:00:00.000Z"
          },
          "settlement": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "settled_at",
                  "amount",
                  "currency"
                ],
                "properties": {
                  "settled_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2024-02-01T12:00:00.000Z"
                  },
                  "amount": {
                    "type": "string",
                    "example": "360 XLM"
                  },
                  "currency": {
                    "type": "string",
                    "example": "XLM"
                  }
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Settlement details once the stream has been settled, otherwise `null`. Clients must handle `null` explicitly."
          }
        }
      },
      "WalletChallenge": {
        "type": "object",
        "required": [
          "challenge",
          "expires_at"
        ],
        "properties": {
          "challenge": {
            "type": "string",
            "description": "One-time nonce the client must sign with their Stellar private key.",
            "example": "streampay_auth_1716000000000_x7k2m"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Challenge expiry (5 minutes from issuance).",
            "example": "2024-01-15T10:05:00.000Z"
          }
        }
      },
      "WalletToken": {
        "type": "object",
        "required": [
          "token",
          "expires_at"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Opaque bearer token. Pass as `Authorization: Bearer <token>`.",
            "example": "tok_R0FCQzEyMzQ1Njc4OTA"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Token expiry (24 hours from issuance).",
            "example": "2024-01-16T10:00:00.000Z"
          }
        }
      },
      "AuditActor": {
        "type": "object",
        "required": [
          "id",
          "role"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "user",
              "support",
              "admin",
              "finance",
              "security",
              "compliance",
              "system"
            ]
          }
        }
      },
      "AuditTarget": {
        "type": "object",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "stream",
              "account"
            ]
          },
          "id": {
            "type": "string"
          },
          "account": {
            "type": "string"
          }
        }
      },
      "AuditEntry": {
        "type": "object",
        "required": [
          "id",
          "actor",
          "target",
          "action",
          "requestId",
          "timestamp",
          "entryHash",
          "retentionUntil"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "actor": {
            "$ref": "#/components/schemas/AuditActor"
          },
          "target": {
            "$ref": "#/components/schemas/AuditTarget"
          },
          "action": {
            "type": "string"
          },
          "beforeHash": {
            "type": [
              "string",
              "null"
            ]
          },
          "afterHash": {
            "type": [
              "string",
              "null"
            ]
          },
          "diffHash": {
            "type": [
              "string",
              "null"
            ]
          },
          "requestId": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "prevHash": {
            "type": [
              "string",
              "null"
            ]
          },
          "entryHash": {
            "type": "string"
          },
          "retentionUntil": {
            "type": "string",
            "format": "date-time"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ]
            }
          }
        }
      },
      "AuditResponse": {
        "type": "object",
        "required": [
          "access",
          "data",
          "links",
          "meta"
        ],
        "properties": {
          "access": {
            "type": "object",
            "required": [
              "actorId",
              "role"
            ],
            "properties": {
              "actorId": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "enum": [
                  "user",
                  "support",
                  "admin",
                  "finance",
                  "security",
                  "compliance",
                  "system"
                ]
              }
            }
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditEntry"
            }
          },
          "links": {
            "type": "object",
            "required": [
              "self"
            ],
            "properties": {
              "self": {
                "type": "string"
              }
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "chainIntact",
              "retentionDays",
              "total"
            ],
            "properties": {
              "chainIntact": {
                "type": "boolean"
              },
              "retentionDays": {
                "type": "number"
              },
              "total": {
                "type": "number"
              }
            }
          }
        }
      },
      "ActivityEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "timestamp",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique event identifier.",
            "example": "evt_a1b2c3d4"
          },
          "type": {
            "type": "string",
            "description": "Event type classification.",
            "example": "stream.created"
          },
          "streamId": {
            "type": "string",
            "description": "Associated stream identifier, if applicable.",
            "example": "stream-abc12345"
          },
          "actorAddress": {
            "type": "string",
            "description": "Wallet that produced a non-stream event (for example wallet.connected).",
            "example": "GABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMNOPQRSTUV"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp of the event.",
            "example": "2026-04-28T09:00:00Z"
          },
          "description": {
            "type": "string",
            "description": "Human-readable event description.",
            "example": "Stream 'Design Retainer' created and set to draft."
          },
          "isDeleted": {
            "type": "boolean",
            "description": "Whether the associated stream no longer exists. Such events are not linkable."
          }
        }
      },
      "PaginatedMeta": {
        "type": "object",
        "required": [
          "hasNext",
          "nextCursor",
          "total"
        ],
        "properties": {
          "hasNext": {
            "type": "boolean",
            "description": "Whether additional results are available."
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "description": "Opaque base64-encoded cursor for the next page. Null when hasNext is false.",
            "example": "MjAyNi0wNC0yN1QyMDowMDowMFp8ZXZ0LTI="
          },
          "total": {
            "type": "integer",
            "description": "Total number of items matching the filter criteria.",
            "example": 42
          }
        }
      },
      "ActivityResponse": {
        "type": "object",
        "required": [
          "data",
          "meta",
          "links"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActivityEvent"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginatedMeta"
          },
          "links": {
            "type": "object",
            "required": [
              "self"
            ],
            "properties": {
              "self": {
                "type": "string",
                "description": "Canonical URL for this request.",
                "example": "/api/activity?limit=20"
              }
            }
          }
        }
      },
      "StreamHistoryEntry": {
        "type": "object",
        "required": ["id", "streamId", "type", "toStatus", "at"],
        "description": "Immutable lifecycle event for a stream. No PII — actor wallet truncated to 6 chars.",
        "properties": {
          "id":         { "type": "string", "description": "Unique entry id.", "example": "3c4d5e6f-7a8b-9c0d-e1f2-a3b4c5d6e7f8" },
          "streamId":   { "type": "string", "description": "Owning stream id.", "example": "stream-abc12345" },
          "type":       { "type": "string", "enum": ["created","started","paused","resumed","stopped","settled","withdrawn","cancelled"] },
          "fromStatus": { "type": "string", "nullable": true, "description": "Status before transition; absent for 'created'." },
          "toStatus":   { "type": "string", "description": "Status after transition." },
          "at":         { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp.", "example": "2026-06-01T09:00:00.000Z" },
          "actor":      { "type": "string", "nullable": true, "description": "First 6 chars of actor wallet (no PII).", "example": "GABCDE" },
          "txHash":     { "type": "string", "nullable": true, "description": "On-chain tx hash (once indexer is wired)." },
          "amountRaw":  { "type": "string", "nullable": true, "description": "Human-readable amount label, e.g. '120 XLM'." }
        }
      },
      "StreamHistoryResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/StreamHistoryEntry" },
            "description": "History entries, newest first."
          },
          "meta": {
            "type": "object",
            "required": ["nextCursor"],
            "properties": {
              "nextCursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page; null when none remain." }
            }
          }
        }
      }
    },
    "responses": {
      "400": {
        "description": "Bad request \u2014 invalid input.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "BAD_REQUEST",
                "message": "Request body must include 'recipient' and 'rate'.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "401": {
        "description": "Unauthorized \u2014 missing or invalid bearer token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "UNAUTHORIZED",
                "message": "Bearer token required.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "403": {
        "description": "Forbidden.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "FORBIDDEN",
                "message": "This endpoint is not available in production.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "404": {
        "description": "Not found \u2014 the requested resource does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "STREAM_NOT_FOUND",
                "message": "Stream 'stream-abc12345' not found.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "409": {
        "description": "Conflict \u2014 the operation is not valid for the current stream state.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "STREAM_INACTIVE_STATE",
                "message": "Cannot delete a stream that is active or paused. Stop it first.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "422": {
        "description": "Unprocessable entity \u2014 request body failed schema validation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "VALIDATION_ERROR",
                "message": "One or more fields are invalid.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      },
      "500": {
        "description": "Internal server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "example": {
              "error": {
                "code": "INTERNAL_SERVER_ERROR",
                "message": "An unexpected error occurred.",
                "request_id": "req_01HZ9ABCDEF"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/activity": {
      "get": {
        "operationId": "listActivity",
        "summary": "List activity events",
        "description": "Returns a paginated, cursor-based list of activity events for the authenticated caller. Only events for streams the caller sends or receives, plus the caller's own wallet events, are returned. Events are sorted by (timestamp desc, id desc) for stable ordering. Supports filtering by streamId and event type.",
        "tags": [
          "Activity"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of events to return (1-100, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque base64-encoded composite cursor (timestamp|id) for cursor-based pagination. Obtained from meta.nextCursor of the previous response.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "streamId",
            "in": "query",
            "description": "Filter events by associated stream identifier. Must match the id charset [A-Za-z0-9._:-]+ and belong to the caller; a non-owned streamId returns 404.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter events by a known type (e.g. stream.created, wallet.connected).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of activity events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivityResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized \u2014 missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "UNAUTHORIZED",
                    "message": "Missing or invalid authorization header",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found \u2014 the requested streamId does not exist or is not owned by the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "STREAM_NOT_FOUND",
                    "message": "Stream 'stream-abc12345' not found",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity \u2014 invalid limit (INVALID_LIMIT), type, streamId, or cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests \u2014 rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/audit": {
      "get": {
        "operationId": "listAuditLogs",
        "summary": "List audit logs",
        "description": "Returns a paginated list of audit events. Requires audit log access.",
        "tags": [
          "Audit"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of records to return (1-250, default 50).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 250,
              "default": 50
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "Filter by action.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actorId",
            "in": "query",
            "description": "Filter by actor ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "requestId",
            "in": "query",
            "description": "Filter by request ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "description": "Filter by actor role.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "targetId",
            "in": "query",
            "description": "Filter by target ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit log list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/auth/wallet": {
      "get": {
        "operationId": "getWalletChallenge",
        "summary": "Issue a wallet authentication challenge",
        "description": "Returns a one-time nonce the client must sign with their Stellar private key, then submit to `POST /api/auth/wallet`.",
        "security": [],
        "tags": [
          "Auth"
        ],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "description": "Stellar public key (G\u2026, 56 characters).",
            "schema": {
              "type": "string",
              "pattern": "^G[A-Z2-7]{55}$",
              "example": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Challenge issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletChallenge"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "429": {
            "description": "IP rate limit exceeded for challenge issuance (20 req/min per IP).",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the client may retry.",
                "schema": {
                  "type": "integer"
                }
              },
              "x-request-id": {
                "description": "Correlation ID for this response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "rate_limit_exceeded",
                    "message": "Too many requests. Please try again later.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "post": {
        "operationId": "verifyWalletSignature",
        "summary": "Verify a signed challenge and issue a bearer token",
        "description": "Wallet login endpoint. Rate-limited to 5 requests per minute per client IP to mitigate brute-force attempts.",
        "security": [],
        "tags": [
          "Auth"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address",
                  "challenge",
                  "signature"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "description": "Stellar public key.",
                    "example": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG"
                  },
                  "challenge": {
                    "type": "string",
                    "description": "The nonce returned by GET /api/auth/wallet.",
                    "example": "streampay_auth_1716000000000_x7k2m"
                  },
                  "signature": {
                    "type": "string",
                    "description": "Base64-encoded Ed25519 signature of the challenge.",
                    "example": "dGVzdHNpZ25hdHVyZQ=="
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletToken"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "429": {
            "description": "IP rate limit exceeded for wallet login (5 req/min per IP).",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the client may retry.",
                "schema": {
                  "type": "integer"
                }
              },
              "x-request-id": {
                "description": "Correlation ID for this response.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "rate_limit_exceeded",
                    "message": "Too many requests. Please try again later.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams": {
      "get": {
        "operationId": "listStreams",
        "summary": "List payment streams (v1, deprecated)",
        "description": "Returns a cursor-paginated list of streams owned by the authenticated identity. **Deprecated** \u2014 use `GET /api/v2/streams` instead.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of streams to return (1\u2013100, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20,
              "example": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque pagination cursor from a previous response `meta.nextCursor` field.",
            "schema": {
              "type": "string",
              "example": "c3RyZWFtLWFiYzEyMzQ1"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter results to streams with this status.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "active",
                "paused",
                "ended"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated stream list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "links",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StreamV1"
                      }
                    },
                    "links": {
                      "type": "object",
                      "required": [
                        "self"
                      ],
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "/api/v1/streams?limit=20"
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "required": [
                        "hasNext",
                        "nextCursor",
                        "total"
                      ],
                      "properties": {
                        "hasNext": {
                          "type": "boolean",
                          "example": false
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "example": null
                        },
                        "total": {
                          "type": "integer",
                          "example": 1
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "single-active-stream": {
                    "summary": "One active stream, no further pages",
                    "value": {
                      "data": [
                        {
                          "id": "stream-abc12345",
                          "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                          "rate": "120",
                          "schedule": "month",
                          "status": "active",
                          "nextAction": "pause",
                          "token": "XLM",
                          "createdAt": "2024-01-15T10:00:00.000Z",
                          "updatedAt": "2024-01-16T08:30:00.000Z"
                        }
                      ],
                      "links": {
                        "self": "/api/v1/streams?limit=20"
                      },
                      "meta": {
                        "hasNext": false,
                        "nextCursor": null,
                        "total": 1
                      }
                    }
                  },
                  "empty-list": {
                    "summary": "No streams exist yet",
                    "value": {
                      "data": [],
                      "links": {
                        "self": "/api/v1/streams?limit=20"
                      },
                      "meta": {
                        "hasNext": false,
                        "nextCursor": null,
                        "total": 0
                      }
                    }
                  },
                  "paginated-first-page": {
                    "summary": "First page of a multi-page result",
                    "value": {
                      "data": [
                        {
                          "id": "stream-abc12345",
                          "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                          "rate": "50",
                          "schedule": "week",
                          "status": "draft",
                          "nextAction": "start",
                          "token": "XLM",
                          "createdAt": "2024-01-15T10:00:00.000Z",
                          "updatedAt": "2024-01-15T10:00:00.000Z"
                        }
                      ],
                      "links": {
                        "self": "/api/v1/streams?limit=1"
                      },
                      "meta": {
                        "hasNext": true,
                        "nextCursor": "c3RyZWFtLWFiYzEyMzQ1",
                        "total": 3
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Malformed cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_CURSOR",
                    "message": "Malformed cursor",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "post": {
        "operationId": "createStream",
        "summary": "Create a payment stream (v1, deprecated)",
        "description": "Creates a new payment stream in `draft` status. **Deprecated** \u2014 use `POST /api/v2/streams` instead.\n\nSupplying an `Idempotency-Key` header makes this request idempotent; replaying the same key and body returns the cached response.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Client-generated key (UUID recommended) to make the request idempotent.",
            "schema": {
              "type": "string",
              "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recipient",
                  "rate",
                  "schedule"
                ],
                "properties": {
                  "recipient": {
                    "type": "string",
                    "description": "Stellar public key of the payment recipient (56-character G\u2026 address).",
                    "example": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG"
                  },
                  "rate": {
                    "type": "string",
                    "description": "Positive decimal payment amount per schedule interval (max 7 decimal places).",
                    "example": "120"
                  },
                  "schedule": {
                    "type": "string",
                    "enum": [
                      "second",
                      "minute",
                      "hour",
                      "day",
                      "week",
                      "month",
                      "year"
                    ],
                    "description": "Payment interval.",
                    "example": "month"
                  },
                  "token": {
                    "type": "string",
                    "description": "Stellar asset code (optional, defaults to XLM).",
                    "example": "XLM"
                  }
                }
              },
              "examples": {
                "minimal-xlm": {
                  "summary": "Minimal request — XLM (default token)",
                  "value": {
                    "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                    "rate": "120",
                    "schedule": "month",
                    "token": "XLM"
                  }
                },
                "with-usdc-token": {
                  "summary": "Full request with USDC token",
                  "value": {
                    "recipient": "GDEF1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFGH",
                    "rate": "500",
                    "schedule": "week",
                    "token": "USDC"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stream created. Initial status is `draft`; call `POST /api/streams/{id}/start` to activate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "links"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    },
                    "links": {
                      "type": "object",
                      "required": [
                        "self"
                      ],
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "/api/v1/streams/stream-abc12345"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "draft-xlm": {
                    "summary": "Newly created XLM stream in draft status",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120",
                        "schedule": "month",
                        "status": "draft",
                        "nextAction": "start",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T10:00:00.000Z"
                      },
                      "links": { "self": "/api/v1/streams/stream-abc12345" }
                    }
                  },
                  "links": {
                    "self": "/api/v1/streams/stream-abc12345"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "409": {
            "description": "Idempotency key reused with a different request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency key has been used with a different request.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/422"
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams/search": {
      "get": {
        "operationId": "searchStreams",
        "summary": "Search payment streams with FTS and filters",
        "description": "Performs full-text search across stream fields (id, recipient, memo, label, email, senderAddress, partnerId, token) and filters by status, asset, sender, recipient, and creation date bounds.",
        "tags": [
          "Streams v1"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Full-text search query term.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by stream status (draft, active, paused, ended, withdrawn, cancelled).",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "active",
                "paused",
                "ended",
                "withdrawn",
                "cancelled"
              ]
            }
          },
          {
            "name": "asset",
            "in": "query",
            "description": "Filter by asset or token symbol.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sender",
            "in": "query",
            "description": "Filter by sender address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recipient",
            "in": "query",
            "description": "Filter by recipient.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "ISO-8601 creation date lower bound.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "ISO-8601 creation date upper bound.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (1-200, default 50).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset (default 0).",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta",
                    "links"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StreamV1"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "required": [
                        "total",
                        "limit",
                        "offset",
                        "count",
                        "query"
                      ],
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "query": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "required": [
                        "self"
                      ],
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "results-found": {
                    "summary": "Search returned matching streams",
                    "value": {
                      "data": [
                        {
                          "id": "stream-abc12345",
                          "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                          "rate": "120",
                          "schedule": "month",
                          "status": "active",
                          "nextAction": "pause",
                          "token": "XLM",
                          "createdAt": "2024-01-15T10:00:00.000Z",
                          "updatedAt": "2024-01-16T08:30:00.000Z"
                        }
                      ],
                      "meta": { "total": 1, "limit": 50, "offset": 0, "count": 1, "query": "abc12345" },
                      "links": { "self": "/api/streams/search?q=abc12345&limit=50" }
                    }
                  },
                  "no-results": {
                    "summary": "No streams matched the search query",
                    "value": {
                      "data": [],
                      "meta": { "total": 0, "limit": 50, "offset": 0, "count": 0, "query": "nonexistent" },
                      "links": { "self": "/api/streams/search?q=nonexistent&limit=50" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the client may retry.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream-abc12345"
          }
        },
        {
          "name": "x-tenant-id",
          "in": "header",
          "required": true,
          "description": "Tenant context for multi-tenant isolation. Must be a non-empty string.",
          "schema": {
            "type": "string",
            "example": "tenant-org-xyz"
          }
        }
      ],
      "get": {
        "operationId": "getStream",
        "summary": "Get a payment stream (v1, deprecated)",
        "description": "Returns a single stream by ID in the v1 shape. **Deprecated** \u2014 use `GET /api/v2/streams/{id}` instead.\n\nResponses are cached; a cache hit returns `X-Cache: HIT`.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "responses": {
          "200": {
            "description": "Stream found.",
            "headers": {
              "X-Cache": {
                "description": "Whether the response was served from cache (`HIT`) or fetched from the data store (`MISS`).",
                "schema": {
                  "type": "string",
                  "enum": [
                    "HIT",
                    "MISS"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "links"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    },
                    "links": {
                      "type": "object",
                      "required": [
                        "self"
                      ],
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "/api/v1/streams/stream-abc12345"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "draft-stream": {
                    "summary": "A newly created stream waiting to be started",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120",
                        "schedule": "month",
                        "status": "draft",
                        "nextAction": "start",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T10:00:00.000Z"
                      },
                      "links": {
                        "self": "/api/v1/streams/stream-abc12345"
                      }
                    }
                  },
                  "active-stream": {
                    "summary": "A running stream that can be paused or stopped",
                    "value": {
                      "data": {
                        "id": "stream-def67890",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "50",
                        "schedule": "week",
                        "status": "active",
                        "nextAction": "pause",
                        "token": "XLM",
                        "createdAt": "2024-01-10T08:00:00.000Z",
                        "updatedAt": "2024-01-16T09:15:00.000Z"
                      },
                      "links": {
                        "self": "/api/v1/streams/stream-def67890"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty `x-tenant-id` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "MISSING_TENANT",
                    "message": "Tenant ID header is required",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "post": {
        "operationId": "updateStream",
        "summary": "Update a payment stream (v1, deprecated)",
        "description": "Partially updates a stream by merging the request body fields. **Deprecated** \u2014 there is no direct v2 equivalent; update streams via their lifecycle action sub-routes.\n\nThe `updatedAt` field is always refreshed. Cache is invalidated on success.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Partial stream fields to update. Any top-level `StreamV1` field may be included.",
                "properties": {
                  "rate": {
                    "type": "string",
                    "description": "New rate amount.",
                    "example": "150"
                  },
                  "schedule": {
                    "type": "string",
                    "enum": [
                      "second",
                      "minute",
                      "hour",
                      "day",
                      "week",
                      "month",
                      "year"
                    ],
                    "example": "month"
                  },
                  "token": {
                    "type": "string",
                    "description": "New asset code.",
                    "example": "USDC"
                  }
                }
              },
              "example": {
                "rate": "150"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stream updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    }
                  }
                },
                "examples": {
                  "rate-updated": {
                    "summary": "Rate updated successfully",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "150",
                        "schedule": "month",
                        "status": "draft",
                        "nextAction": "start",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T11:30:00.000Z"
                      }
                    }
                  },
                  "rate-and-token-updated": {
                    "summary": "Rate and token updated",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "200",
                        "schedule": "month",
                        "status": "draft",
                        "nextAction": "start",
                        "token": "USDC",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T11:35:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing `x-tenant-id` header or invalid JSON body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "missing-tenant": {
                    "summary": "x-tenant-id header absent",
                    "value": {
                      "error": {
                        "code": "MISSING_TENANT",
                        "message": "Tenant ID header is required",
                        "request_id": "req_01HZ9ABCDEF"
                      }
                    }
                  },
                  "invalid-json": {
                    "summary": "Malformed JSON body",
                    "value": {
                      "error": {
                        "code": "INVALID_REQUEST",
                        "message": "Request body must be valid JSON",
                        "request_id": "req_01HZ9ABCDEF"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "delete": {
        "operationId": "deleteStream",
        "summary": "Delete a payment stream (v1, deprecated)",
        "description": "Permanently deletes a stream. **Deprecated** \u2014 use `DELETE /api/v2/streams/{id}` instead.\n\nA stream must be in `draft` or `ended` status before it can be deleted. Attempting to delete an `active` or `paused` stream returns 409. Cache is invalidated on success.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "responses": {
          "204": {
            "description": "Stream deleted. No response body."
          },
          "400": {
            "description": "Missing or empty `x-tenant-id` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "MISSING_TENANT",
                    "message": "Tenant ID header is required",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams/{id}/start": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream-abc12345"
          }
        },
        {
          "name": "x-tenant-id",
          "in": "header",
          "required": true,
          "description": "Tenant context for multi-tenant isolation. Must be a non-empty string.",
          "schema": {
            "type": "string",
            "example": "tenant-org-xyz"
          }
        },
        {
          "name": "Idempotency-Key",
          "in": "header",
          "required": false,
          "description": "Client-generated key (UUID recommended) to make the request idempotent.",
          "schema": {
            "type": "string",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          }
        }
      ],
      "post": {
        "operationId": "startStream",
        "summary": "Start a payment stream (v1, deprecated)",
        "description": "Transitions a stream from `draft` (or `paused`) to `active`, initiating payment disbursements. **Deprecated** \u2014 use `POST /api/v2/streams/{id}/start` instead.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "responses": {
          "200": {
            "description": "Stream started or resumed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    }
                  }
                },
                "examples": {
                  "draft-to-active": {
                    "summary": "Draft stream started, now active",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120",
                        "schedule": "month",
                        "status": "active",
                        "nextAction": "pause",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-15T10:05:00.000Z"
                      }
                    }
                  },
                  "paused-to-active": {
                    "summary": "Paused stream resumed, now active again",
                    "value": {
                      "data": {
                        "id": "stream-def67890",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "50",
                        "schedule": "week",
                        "status": "active",
                        "nextAction": "pause",
                        "token": "XLM",
                        "createdAt": "2024-01-10T08:00:00.000Z",
                        "updatedAt": "2024-01-16T09:20:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty `x-tenant-id` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "MISSING_TENANT",
                    "message": "Tenant ID header is required",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `draft` or `paused` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STREAM_STATE",
                    "message": "Cannot start a stream that is not in draft or paused status.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams/{id}/history": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "stream-abc12345" }, "description": "Stream identifier." },
        { "name": "x-tenant-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Tenant id — must match the stream's owner." }
      ],
      "get": {
        "operationId": "getStreamHistory",
        "summary": "Paginated lifecycle event history for a stream",
        "description": "Returns a newest-first paginated list of committed lifecycle events. No PII. Uses composite (at, id) cursor.",
        "tags": ["Streams"],
        "parameters": [
          { "name": "limit",  "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Max entries per page." },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from meta.nextCursor of the previous response." }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of lifecycle events.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamHistoryResponse" } } }
          },
          "400": { "$ref": "#/components/responses/400" },
          "404": { "$ref": "#/components/responses/404" },
          "422": { "$ref": "#/components/responses/422" },
          "500": { "$ref": "#/components/responses/500" }
        }
      }
    },
    "/api/streams/{id}/stop": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream-abc12345"
          }
        },
        {
          "name": "x-tenant-id",
          "in": "header",
          "required": true,
          "description": "Tenant context for multi-tenant isolation. Must be a non-empty string.",
          "schema": {
            "type": "string",
            "example": "tenant-org-xyz"
          }
        },
        {
          "name": "Idempotency-Key",
          "in": "header",
          "required": false,
          "description": "Client-generated key (UUID recommended) to make the request idempotent.",
          "schema": {
            "type": "string",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          }
        }
      ],
      "post": {
        "operationId": "stopStream",
        "summary": "Stop a payment stream (v1, deprecated)",
        "description": "Permanently stops a stream, transitioning it to `ended` status. Valid from `active` or `draft` states. This action is irreversible. **Deprecated** \u2014 use `POST /api/v2/streams/{id}/stop` instead.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "responses": {
          "200": {
            "description": "Stream stopped successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    }
                  }
                },
                "examples": {
                  "active-to-ended": {
                    "summary": "Active stream stopped, now ended",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120",
                        "schedule": "month",
                        "status": "ended",
                        "nextAction": "withdraw",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-16T12:00:00.000Z"
                      }
                    }
                  },
                  "draft-to-ended": {
                    "summary": "Draft stream cancelled, now ended",
                    "value": {
                      "data": {
                        "id": "stream-ghi11223",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "200",
                        "schedule": "month",
                        "status": "ended",
                        "nextAction": "withdraw",
                        "token": "USDC",
                        "createdAt": "2024-01-18T14:00:00.000Z",
                        "updatedAt": "2024-01-18T14:05:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty `x-tenant-id` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "MISSING_TENANT",
                    "message": "Tenant ID header is required",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `active` or `draft` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STREAM_STATE",
                    "message": "Only active or draft streams can be stopped.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams/{id}/pause": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream-abc12345"
          }
        },
        {
          "name": "x-tenant-id",
          "in": "header",
          "required": true,
          "description": "Tenant context for multi-tenant isolation. Must be a non-empty string.",
          "schema": {
            "type": "string",
            "example": "tenant-org-xyz"
          }
        },
        {
          "name": "Idempotency-Key",
          "in": "header",
          "required": false,
          "description": "Client-generated key (UUID recommended) to make the request idempotent.",
          "schema": {
            "type": "string",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          }
        }
      ],
      "post": {
        "operationId": "pauseStream",
        "summary": "Pause a payment stream (v1, deprecated)",
        "description": "Temporarily suspends an active stream, transitioning it to `paused` status. Payments are halted and `pausedAt` is recorded until the stream is resumed. Only valid when the stream is `active`. **Deprecated** \u2014 use `POST /api/v2/streams/{id}/pause` instead.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "responses": {
          "200": {
            "description": "Stream paused successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    }
                  }
                },
                "examples": {
                  "active-to-paused": {
                    "summary": "Active stream paused, payments halted",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120",
                        "schedule": "month",
                        "status": "paused",
                        "nextAction": "stop",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-01-16T11:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty `x-tenant-id` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "MISSING_TENANT",
                    "message": "Tenant ID header is required",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `active` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STREAM_STATE",
                    "message": "Cannot pause a stream that is not active.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/streams/{id}/settle": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream-abc12345"
          }
        },
        {
          "name": "x-tenant-id",
          "in": "header",
          "required": true,
          "description": "Tenant context for multi-tenant isolation. Must be a non-empty string.",
          "schema": {
            "type": "string",
            "example": "tenant-org-xyz"
          }
        },
        {
          "name": "Idempotency-Key",
          "in": "header",
          "required": false,
          "description": "Client-generated key (UUID recommended) to make the request idempotent.",
          "schema": {
            "type": "string",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          }
        }
      ],
      "post": {
        "operationId": "settleStream",
        "summary": "Settle a payment stream (v1, deprecated)",
        "description": "Finalises the stream on Stellar/Soroban, transitioning it to `ended` and recording the settlement transaction. Only valid when the stream is `active` or `paused`. **Deprecated** \u2014 use `POST /api/v2/streams/{id}/settle` instead.",
        "deprecated": true,
        "tags": [
          "Streams v1"
        ],
        "responses": {
          "200": {
            "description": "Stream settled successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV1"
                    }
                  }
                },
                "examples": {
                  "settle-active": {
                    "summary": "Active stream settled, now ended with settlement info",
                    "value": {
                      "data": {
                        "id": "stream-abc12345",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120",
                        "schedule": "month",
                        "status": "ended",
                        "nextAction": "withdraw",
                        "token": "XLM",
                        "createdAt": "2024-01-15T10:00:00.000Z",
                        "updatedAt": "2024-02-01T12:00:00.000Z"
                      }
                    }
                  },
                  "settle-paused": {
                    "summary": "Paused stream settled, now ended with settlement info",
                    "value": {
                      "data": {
                        "id": "stream-def67890",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "50",
                        "schedule": "week",
                        "status": "ended",
                        "nextAction": "withdraw",
                        "token": "XLM",
                        "createdAt": "2024-01-10T08:00:00.000Z",
                        "updatedAt": "2024-01-20T14:30:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty `x-tenant-id` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "MISSING_TENANT",
                    "message": "Tenant ID header is required",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `active` or `paused` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STREAM_STATE",
                    "message": "Only active or paused streams can be settled.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Too many requests. Retry after 30 seconds.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "502": {
            "description": "Settlement failed \u2014 Stellar/Soroban transaction could not be completed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "SETTLEMENT_FAILED",
                    "message": "Failed to settle stream on Stellar/Soroban",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/streams": {
      "get": {
        "operationId": "listStreamsV2",
        "summary": "List payment streams (v2)",
        "description": "Returns all streams owned by the authenticated user in the v2 shape (`allowed_actions`, `created_at`, `settlement`).",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated stream list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "streams"
                  ],
                  "properties": {
                    "streams": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StreamV2"
                      }
                    }
                  }
                },
                "examples": {
                  "one-active-stream": {
                    "summary": "Single active stream, no further pages",
                    "value": {
                      "streams": [
                        {
                          "id": "stream_lf3k9z",
                          "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                          "rate": "120 XLM/month",
                          "status": "active",
                          "allowed_actions": [
                            "pause",
                            "stop"
                          ],
                          "created_at": "2024-01-15T10:00:00.000Z",
                          "settlement": null
                        }
                      ],
                      "meta": { "hasNext": false, "nextCursor": null, "total": 1 },
                      "links": { "self": "/api/v2/streams?limit=20" }
                    }
                  },
                  "settled-stream": {
                    "summary": "Ended stream with settlement details",
                    "value": {
                      "streams": [
                        {
                          "id": "stream_lf3k9z",
                          "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                          "rate": "120 XLM/month",
                          "status": "ended",
                          "allowed_actions": [],
                          "created_at": "2024-01-15T10:00:00.000Z",
                          "settlement": {
                            "settled_at": "2024-02-01T12:00:00.000Z",
                            "amount": "360 XLM",
                            "currency": "XLM"
                          }
                        }
                      ],
                      "meta": { "hasNext": false, "nextCursor": null, "total": 1 },
                      "links": { "self": "/api/v2/streams?limit=20" }
                    }
                  },
                  "empty-list": {
                    "summary": "No streams for this user",
                    "value": {
                      "streams": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "post": {
        "operationId": "createStreamV2",
        "summary": "Create a payment stream (v2)",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recipient",
                  "rate",
                  "schedule"
                ],
                "properties": {
                  "recipient": {
                    "type": "string",
                    "description": "Stellar public key of the recipient (56-character G\u2026 address).",
                    "example": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG"
                  },
                  "rate": {
                    "type": "string",
                    "description": "Positive decimal payment amount per schedule interval (max 7 decimal places).",
                    "example": "120"
                  },
                  "schedule": {
                    "type": "string",
                    "enum": [
                      "second",
                      "minute",
                      "hour",
                      "day",
                      "week",
                      "month",
                      "year"
                    ],
                    "description": "Payment interval.",
                    "example": "month"
                  },
                  "token": {
                    "type": "string",
                    "description": "Stellar asset code (optional, defaults to XLM).",
                    "example": "XLM"
                  }
                }
              },
              "examples": {
                "minimal-xlm": {
                  "summary": "Minimal request — XLM (default token)",
                  "value": {
                    "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                    "rate": "120",
                    "schedule": "month"
                  }
                },
                "with-usdc-token": {
                  "summary": "Full request with USDC token",
                  "value": {
                    "recipient": "GDEF1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFGH",
                    "rate": "500",
                    "schedule": "week",
                    "token": "USDC"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stream created. Initial status is `draft`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamV2"
                },
                "example": {
                  "id": "stream_lf3k9z",
                  "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                  "rate": "120 XLM/month",
                  "status": "draft",
                  "allowed_actions": [
                    "start"
                  ],
                  "created_at": "2024-01-15T10:00:00.000Z",
                  "settlement": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "422": {
            "$ref": "#/components/responses/422"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/v2/streams/multi": {
      "post": {
        "operationId": "createMultiRecipientStreamV2",
        "summary": "Create a multi-recipient (fan-out) stream (v2)",
        "description": "Creates one stream leg per recipient, each locked to its share of a single total. Percentages must sum to 100 within 0.001 percentage points, and at most 20 recipients are accepted. The per-recipient amounts are recomputed by the server from the percentages. See docs/api/multi-recipient-stream.md.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "token",
                  "totalAmount",
                  "startTime",
                  "endTime",
                  "recipients"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "Human-readable name of the fan-out stream.",
                    "example": "GrantFox Q3 Distribution"
                  },
                  "token": {
                    "type": "string",
                    "enum": [
                      "XLM",
                      "USDC"
                    ],
                    "description": "Asset the stream is denominated in.",
                    "example": "XLM"
                  },
                  "totalAmount": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Total amount distributed across all recipients.",
                    "example": 10000
                  },
                  "startTime": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Start of the streaming window (ISO-8601).",
                    "example": "2026-09-01T09:00:00.000Z"
                  },
                  "endTime": {
                    "type": "string",
                    "format": "date-time",
                    "description": "End of the streaming window (ISO-8601). Must be strictly after startTime.",
                    "example": "2026-12-31T23:59:00.000Z"
                  },
                  "recipients": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 20,
                    "description": "At most 20 recipients. The percentage values must sum to 100 within 0.001 percentage points.",
                    "items": {
                      "type": "object",
                      "required": [
                        "address",
                        "percentage"
                      ],
                      "properties": {
                        "address": {
                          "type": "string",
                          "description": "Stellar ed25519 public key (Strkey) or a registered email address.",
                          "example": "GDSBCG3OKHCMMWS5EBH2X7XOYTJRWXN2YYQPCNS5OFBU4IDO4X7OFSQA"
                        },
                        "percentage": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100,
                          "description": "Share of totalAmount for this recipient. At most 4 decimal places.",
                          "example": 50
                        },
                        "amount": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Optional echo of percentage / 100 x totalAmount. Recomputed by the server when omitted; rejected with AMOUNT_MISMATCH when it disagrees.",
                          "example": 5000
                        }
                      }
                    }
                  }
                }
              },
              "examples": {
                "two-way-split": {
                  "summary": "Two recipients at 50% each",
                  "value": {
                    "name": "GrantFox Q3 Distribution",
                    "token": "XLM",
                    "totalAmount": 10000,
                    "startTime": "2026-09-01T09:00:00.000Z",
                    "endTime": "2026-12-31T23:59:00.000Z",
                    "recipients": [
                      {
                        "address": "GDSBCG3OKHCMMWS5EBH2X7XOYTJRWXN2YYQPCNS5OFBU4IDO4X7OFSQA",
                        "percentage": 50,
                        "amount": 5000
                      },
                      {
                        "address": "ada@example.com",
                        "percentage": 50,
                        "amount": 5000
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Fan-out created. Each recipient is returned with the id of the stream leg that was written for it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MultiRecipientStreamV2"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "409": {
            "description": "Idempotency-Key reused with a different request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/422"
          },
          "429": {
            "description": "Per-org daily stream quota exceeded. Retry-After is set to the seconds until UTC midnight.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/v2/streams/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream_lf3k9z"
          }
        }
      ],
      "get": {
        "operationId": "getStreamV2",
        "summary": "Get a payment stream (v2)",
        "description": "Returns a single stream by ID in the v2 shape.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "links"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StreamV2"
                    },
                    "links": {
                      "type": "object",
                      "required": [
                        "self"
                      ],
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "/api/v2/streams/stream_lf3k9z"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "draft-stream": {
                    "summary": "Newly created stream awaiting activation",
                    "value": {
                      "data": {
                        "id": "stream_lf3k9z",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120 XLM/month",
                        "status": "draft",
                        "allowed_actions": [
                          "start"
                        ],
                        "created_at": "2024-01-15T10:00:00.000Z",
                        "settlement": null
                      },
                      "links": {
                        "self": "/api/v2/streams/stream_lf3k9z"
                      }
                    }
                  },
                  "active-stream": {
                    "summary": "Running stream that can be paused or stopped",
                    "value": {
                      "data": {
                        "id": "stream_lf3k9z",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120 XLM/month",
                        "status": "active",
                        "allowed_actions": [
                          "pause",
                          "stop"
                        ],
                        "created_at": "2024-01-15T10:00:00.000Z",
                        "settlement": null
                      },
                      "links": {
                        "self": "/api/v2/streams/stream_lf3k9z"
                      }
                    }
                  },
                  "ended-settled-stream": {
                    "summary": "Ended stream with settlement details",
                    "value": {
                      "data": {
                        "id": "stream_lf3k9z",
                        "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                        "rate": "120 XLM/month",
                        "status": "ended",
                        "allowed_actions": [],
                        "created_at": "2024-01-15T10:00:00.000Z",
                        "settlement": {
                          "settled_at": "2024-02-01T12:00:00.000Z",
                          "amount": "360 XLM",
                          "currency": "XLM"
                        }
                      },
                      "links": {
                        "self": "/api/v2/streams/stream_lf3k9z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "delete": {
        "operationId": "deleteStreamV2",
        "summary": "Delete a payment stream (v2)",
        "description": "Permanently deletes a stream. The stream must be in `draft` or `ended` status; attempting to delete an `active` or `paused` stream returns 409.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "204": {
            "description": "Stream deleted. No response body."
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/v2/streams/{id}/start": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream_lf3k9z"
          }
        }
      ],
      "post": {
        "operationId": "startStreamV2",
        "summary": "Start a payment stream",
        "description": "Transitions a stream from `draft` to `active`, initiating payment disbursements. Only valid when the stream is in `draft` status.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream started successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamV2"
                },
                "examples": {
                  "draft-to-active": {
                    "summary": "Stream transitioned from draft to active",
                    "value": {
                      "id": "stream_lf3k9z",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "120 XLM/month",
                      "status": "active",
                      "allowed_actions": [
                        "pause",
                        "stop"
                      ],
                      "created_at": "2024-01-15T10:00:00.000Z",
                      "settlement": null
                    }
                  },
                  "paused-to-active": {
                    "summary": "Paused stream resumed to active",
                    "value": {
                      "id": "stream_lf3k9z",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "120 XLM/month",
                      "status": "active",
                      "allowed_actions": ["pause", "stop"],
                      "created_at": "2024-01-15T10:00:00.000Z",
                      "settlement": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `draft` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STATE_TRANSITION",
                    "message": "Cannot start a stream that is not in draft or paused status.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/v2/streams/{id}/stop": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream_lf3k9z"
          }
        }
      ],
      "post": {
        "operationId": "stopStreamV2",
        "summary": "Stop a payment stream",
        "description": "Permanently stops a stream, transitioning it to `ended` status. Valid from `active` or `paused` states. This action is irreversible.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream stopped successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamV2"
                },
                "examples": {
                  "stopped-from-active": {
                    "summary": "Active stream stopped, now ended",
                    "value": {
                      "id": "stream_lf3k9z",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "120 XLM/month",
                      "status": "ended",
                      "allowed_actions": [],
                      "created_at": "2024-01-15T10:00:00.000Z",
                      "settlement": null
                    }
                  },
                  "stopped-from-paused": {
                    "summary": "Paused stream stopped, now ended",
                    "value": {
                      "id": "stream_m7n2p1",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "50 XLM/week",
                      "status": "ended",
                      "allowed_actions": [],
                      "created_at": "2024-01-10T08:00:00.000Z",
                      "settlement": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `active` or `paused` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STATE_TRANSITION",
                    "message": "Cannot stop a stream that is not active or paused.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/v2/streams/{id}/pause": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream_lf3k9z"
          }
        }
      ],
      "post": {
        "operationId": "pauseStreamV2",
        "summary": "Pause a payment stream",
        "description": "Temporarily suspends an active stream, transitioning it to `paused` status. Payments are halted until the stream is resumed. Only valid when the stream is `active`.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream paused successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamV2"
                },
                "examples": {
                  "active-to-paused": {
                    "summary": "Active stream paused, payments halted",
                    "value": {
                      "id": "stream_lf3k9z",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "120 XLM/month",
                      "status": "paused",
                      "allowed_actions": [
                        "start",
                        "stop"
                      ],
                      "created_at": "2024-01-15T10:00:00.000Z",
                      "settlement": null
                    }
                  },
                  "high-value-paused": {
                    "summary": "High-value USDC stream paused",
                    "value": {
                      "id": "stream_q8r4s5",
                      "recipient": "GDEF1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFGH",
                      "rate": "5000 USDC/month",
                      "status": "paused",
                      "allowed_actions": ["start", "stop"],
                      "created_at": "2024-02-01T09:00:00.000Z",
                      "settlement": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `active` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "error": {
                    "code": "INVALID_STATE_TRANSITION",
                    "message": "Cannot pause a stream that is not active.",
                    "request_id": "req_01HZ9ABCDEF"
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/v2/streams/{id}/settle": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Stream identifier.",
          "schema": {
            "type": "string",
            "example": "stream_lf3k9z"
          }
        }
      ],
      "post": {
        "operationId": "settleStreamV2",
        "summary": "Settle a payment stream",
        "description": "Finalises the stream's payment balance and records settlement details. Can only be called on a stream in `ended` status. Populates the `settlement` field with amount, currency, and timestamp.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream settled successfully. The `settlement` field is now populated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamV2"
                },
                "examples": {
                  "success": {
                    "summary": "Ended stream settled with XLM balance",
                    "value": {
                      "id": "stream_lf3k9z",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "120 XLM/month",
                      "status": "ended",
                      "allowed_actions": [],
                      "created_at": "2024-01-15T10:00:00.000Z",
                      "settlement": {
                        "settled_at": "2024-02-01T12:00:00.000Z",
                        "amount": "360 XLM",
                        "currency": "XLM"
                      }
                    }
                  },
                  "zero-balance": {
                    "summary": "Stream settled with zero outstanding balance",
                    "value": {
                      "id": "stream_q8r4s5",
                      "recipient": "GABC1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFG",
                      "rate": "10 XLM/day",
                      "status": "ended",
                      "allowed_actions": [],
                      "created_at": "2024-01-20T09:00:00.000Z",
                      "settlement": {
                        "settled_at": "2024-01-20T09:05:00.000Z",
                        "amount": "0 XLM",
                        "currency": "XLM"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "description": "Conflict \u2014 stream is not in `ended` status or has already been settled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "examples": {
                  "not-ended": {
                    "summary": "Stream must be ended before settlement",
                    "value": {
                      "error": {
                        "code": "INVALID_STATE_TRANSITION",
                        "message": "Cannot settle a stream that is not in ended status.",
                        "request_id": "req_01HZ9ABCDEF"
                      }
                    }
                  },
                  "already-settled": {
                    "summary": "Stream has already been settled",
                    "value": {
                      "error": {
                        "code": "ALREADY_SETTLED",
                        "message": "This stream has already been settled.",
                        "request_id": "req_01HZ9ABCDEF"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/webhooks/dlq": {
      "post": {
        "operationId": "receiveDlqWebhook",
        "summary": "Receive a dead-letter-queue webhook event",
        "description": "Accepts failed webhook events for reprocessing. No authentication required (secured at the network/gateway level).",
        "security": [],
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Arbitrary webhook event payload.",
                "example": {
                  "event": "payment.failed",
                  "id": "evt_001"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "received"
                  ],
                  "properties": {
                    "received": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/webhooks/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "List webhook delivery attempts",
        "security": [],
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of records to return (1\u2013100, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque pagination cursor from a previous response.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deliveries",
                    "cursor",
                    "limit"
                  ],
                  "properties": {
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "limit": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/webhooks/health": {
      "get": {
        "summary": "Webhook delivery system health",
        "description": "Returns the health status of the webhook delivery system along with subscription and delivery statistics.",
        "responses": {
          "200": {
            "description": "Health status retrieved",
            "content": {
              "application/json": {
                "examples": {
                  "healthy": {
                    "summary": "All systems healthy",
                    "value": {
                      "status": "ok",
                      "checked_at": "2026-07-26T12:00:00.000Z",
                      "subscriptions": {
                        "total": 42,
                        "active": 42,
                        "degraded": 0,
                        "disabled": 0
                      },
                      "delivery_stats": {
                        "total": 1500,
                        "delivered": 1498,
                        "failed": 2,
                        "pending": 0,
                        "dlq": 0,
                        "success_rate_pct": 99.87
                      }
                    }
                  },
                  "degraded": {
                    "summary": "Some subscriptions degraded",
                    "value": {
                      "status": "degraded",
                      "checked_at": "2026-07-26T12:00:00.000Z",
                      "subscriptions": {
                        "total": 42,
                        "active": 40,
                        "degraded": 2,
                        "disabled": 0
                      },
                      "delivery_stats": {
                        "total": 1500,
                        "delivered": 1490,
                        "failed": 8,
                        "pending": 2,
                        "dlq": 3,
                        "success_rate_pct": 99.33
                      }
                    }
                  },
                  "unhealthy": {
                    "summary": "More than 50% of subscriptions degraded or disabled",
                    "value": {
                      "status": "unhealthy",
                      "checked_at": "2026-07-26T12:00:00.000Z",
                      "subscriptions": {
                        "total": 10,
                        "active": 3,
                        "degraded": 4,
                        "disabled": 3
                      },
                      "delivery_stats": {
                        "total": 200,
                        "delivered": 120,
                        "failed": 50,
                        "pending": 30,
                        "dlq": 15,
                        "success_rate_pct": 60
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Failed to retrieve health stats",
            "content": {
              "application/json": {
                "examples": {
                  "internalError": {
                    "summary": "Unexpected error retrieving health",
                    "value": {
                      "error": {
                        "code": "INTERNAL_SERVER_ERROR",
                        "message": "Failed to retrieve webhook health stats.",
                        "request_id": "req_01HZ9ABCDEF"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/webhooks/redeliver": {
      "post": {
        "operationId": "adminRedeliverWebhook",
        "summary": "Force-redeliver a webhook event",
        "description": "Creates a new delivery for an existing delivery ID, reusing the original endpoint and event payload.\n\n**Auth:** Internal-service HMAC or admin JWT required.\n\n**Data availability:** The original delivery must have full event/endpoint snapshots (deliveries created after snapshot support shipped).\n\n**Idempotency:** Not enforced at the endpoint level; each call creates a new delivery.",
        "tags": [
          "Webhooks",
          "Admin"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "deliveryId"
                ],
                "properties": {
                  "deliveryId": {
                    "type": "string",
                    "description": "The delivery ID to reissue.",
                    "example": "del-01HZ9ABCDEF"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Redelivery enqueued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "deliveryId",
                        "originalDeliveryId"
                      ],
                      "properties": {
                        "deliveryId": {
                          "type": "string",
                          "description": "The ID of the newly created delivery."
                        },
                        "originalDeliveryId": {
                          "type": "string",
                          "description": "The original delivery ID that was reissued."
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "delivery": {
                          "type": "string",
                          "description": "URL to query this delivery's status."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/admin/pause-by-sender": {
      "post": {
        "operationId": "adminPauseBySender",
        "summary": "Emergency-pause all streams by sender",
        "description": "Pauses all active payment streams belonging to the given sender address. Gated by admin auth \u2014 only the configured admin address may call this.\n\nNon-active streams (draft, paused, ended) are silently skipped.\n\n**Auth:** Admin wallet address via `Actor-Wallet-Address` header or JWT.\n\n**Idempotency:** Not enforced; repeat calls are safe (already-paused streams are skipped).",
        "tags": [
          "Admin"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "senderAddress"
                ],
                "properties": {
                  "senderAddress": {
                    "type": "string",
                    "description": "Stellar wallet address of the sender whose streams should be paused.",
                    "example": "GCVVMU4QAB7O6TZCZMF4FPL2KOHVPR2SJNX5O3H6X5Y5QK6HZ"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Streams paused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "paused",
                        "count",
                        "senderAddress"
                      ],
                      "properties": {
                        "paused": {
                          "type": "array",
                          "description": "Array of streams that were paused by this request.",
                          "items": {
                            "$ref": "#/components/schemas/StreamV1"
                          }
                        },
                        "count": {
                          "type": "integer",
                          "description": "Number of streams paused."
                        },
                        "senderAddress": {
                          "type": "string",
                          "description": "The sender address that was targeted."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "422": {
            "$ref": "#/components/responses/422"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/admin/circuit-breaker": {
      "get": {
        "operationId": "adminGetCircuitBreakers",
        "summary": "Read circuit breaker state",
        "description": "Returns the current state of every named circuit breaker.\n\n**Auth:** Admin wallet address via `Actor-Wallet-Address` header or JWT.",
        "tags": [
          "Admin"
        ],
        "responses": {
          "200": {
            "description": "Current breaker state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CircuitBreakers"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      },
      "post": {
        "operationId": "adminSetCircuitBreaker",
        "summary": "Toggle an indexer or webhook circuit breaker",
        "description": "Trips or resets a named subsystem circuit breaker. Gated by admin auth — only the configured admin address may call this.\n\nWhen `open` is true the named subsystem halts dispatch. For the `webhook` target this means no outbound delivery is attempted and the outbox drain is skipped; pending events are **held, not discarded**, and resume when the breaker is reset. For the `indexer` target the state is surfaced on `GET /api/indexer/status` as `breakerOpen`.\n\nThis global operator-controlled breaker is distinct from the automatic per-endpoint failure breaker, which trips itself after repeated delivery failures to a single endpoint and sends that endpoint's deliveries to the DLQ.\n\n**Auth:** Admin wallet address via `Actor-Wallet-Address` header or JWT.\n\n**Idempotency:** Naturally idempotent — setting the same state twice is a no-op beyond the updated timestamp.",
        "tags": [
          "Admin"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target",
                  "open"
                ],
                "properties": {
                  "target": {
                    "type": "string",
                    "enum": [
                      "indexer",
                      "webhook"
                    ],
                    "description": "Which subsystem breaker to toggle.",
                    "example": "webhook"
                  },
                  "open": {
                    "type": "boolean",
                    "description": "true trips the breaker (halt dispatch); false resets it (resume).",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Breaker updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CircuitBreakers"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "422": {
            "$ref": "#/components/responses/422"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    },
    "/api/debug/kms-sign": {
      "post": {
        "operationId": "debugKmsSign",
        "summary": "Sign a payload via KMS (debug only)",
        "description": "**Non-production only.** Returns a base64-encoded signature for the given payload. Returns 403 in production.",
        "security": [],
        "tags": [
          "Debug"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payload"
                ],
                "properties": {
                  "payload": {
                    "type": "string",
                    "description": "Base64-encoded data to sign.",
                    "example": "aGVsbG8="
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signature produced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "signature"
                  ],
                  "properties": {
                    "signature": {
                      "type": "string",
                      "description": "Base64-encoded signature.",
                      "example": "c2lnbmVkOmFHVnNiRzg5"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Activity",
      "description": "Activity event log"
    },
    {
      "name": "Auth",
      "description": "Wallet-based authentication flow"
    },
    {
      "name": "Streams",
      "description": "Payment stream management (v2)"
    },
    {
      "name": "Streams v1",
      "description": "Payment stream management (v1, deprecated \u2014 use Streams)"
    },
    {
      "name": "Webhooks",
      "description": "Webhook ingestion and delivery history"
    },
    {
      "name": "Admin",
      "description": "Admin-only emergency and maintenance operations"
    },
    {
      "name": "Debug",
      "description": "Non-production debugging utilities"
    }
  ]
}