flowfi.openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "FlowFi API",
    "version": "1.0.0",
    "description": "API documentation for FlowFi - Real-time payment streaming on Stellar\n\n## Performance & Caching\nThe API implements caching for frequently accessed endpoints, such as claimable amount calculations. \n- **Claimable Cache TTL**: 5 seconds\n- **Invalidation**: Automatically cleared when a withdrawal event occurs.\n\n## Sandbox Mode\n\nFlowFi API supports sandbox mode for testing without affecting production data.\n\n**Enable Sandbox Mode:**\n- Header: `X-Sandbox-Mode: true`\n- Query Parameter: `?sandbox=true`\n\n**Sandbox Features:**\n- Isolated database (separate from production)\n- All responses include `_sandbox` metadata\n- Response headers include `X-Sandbox-Mode: true`\n- Safe for testing and development\n\nSee [Sandbox Mode Documentation](../docs/SANDBOX_MODE.md) for details.",
    "contact": {
      "name": "FlowFi Team",
      "url": "https://github.com/LabsCrypt/flowfi"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3001/v1",
      "description": "Development server (v1)"
    },
    {
      "url": "https://api.flowfi.io/v1",
      "description": "Production server (v1)"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Health check endpoints"
    },
    {
      "name": "Users",
      "description": "User management endpoints"
    },
    {
      "name": "Streams",
      "description": "Payment stream management endpoints"
    },
    {
      "name": "Events",
      "description": "Stream event tracking endpoints"
    },
    {
      "name": "Admin",
      "description": "Administrative and monitoring endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JSON Web Token issued by /v1/auth/verify after completing the SEP-10 challenge flow."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Alias for BearerAuth — used by route-level security annotations."
      },
      "adminAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Admin JWT — the token subject must match ADMIN_PUBLIC_KEY."
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "required": [
          "id",
          "publicKey"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the user",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "publicKey": {
            "type": "string",
            "description": "Stellar public key (G...)",
            "example": "GABC123XYZ456DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "User creation timestamp"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp"
          }
        }
      },
      "Stream": {
        "type": "object",
        "required": [
          "id",
          "streamId",
          "sender",
          "recipient",
          "tokenAddress",
          "ratePerSecond"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Database UUID"
          },
          "streamId": {
            "type": "integer",
            "description": "On-chain stream ID",
            "example": 1
          },
          "sender": {
            "type": "string",
            "description": "Sender Stellar public key",
            "example": "GABC123XYZ456DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA"
          },
          "recipient": {
            "type": "string",
            "description": "Recipient Stellar public key",
            "example": "GDEF456ABC789GHI012JKL345MNO678PQR901STU234VWX567YZA123BCD"
          },
          "tokenAddress": {
            "type": "string",
            "description": "Token contract address",
            "example": "CBCD789EFG012HIJ345KLM678NOP901QRS234TUV567WXY890ZAB123CDE"
          },
          "ratePerSecond": {
            "type": "string",
            "description": "Payment rate per second (i128 as string)",
            "example": "100"
          },
          "depositedAmount": {
            "type": "string",
            "description": "Total deposited amount (i128 as string)",
            "example": "10000"
          },
          "withdrawnAmount": {
            "type": "string",
            "description": "Total withdrawn amount (i128 as string)",
            "example": "2500"
          },
          "startTime": {
            "type": "integer",
            "description": "Stream start time (Unix timestamp)",
            "example": 1708531200
          },
          "lastUpdateTime": {
            "type": "integer",
            "description": "Last update time (Unix timestamp)",
            "example": 1708534800
          },
          "isActive": {
            "type": "boolean",
            "description": "Stream active status",
            "example": true
          },
          "isPaused": {
            "type": "boolean",
            "description": "Whether the stream is currently paused",
            "example": false
          },
          "pausedAt": {
            "type": "integer",
            "nullable": true,
            "description": "Ledger timestamp when the stream was last paused (Unix), null if not paused",
            "example": null
          },
          "totalPausedDuration": {
            "type": "integer",
            "description": "Cumulative seconds the stream has spent paused",
            "example": 0
          },
          "endTime": {
            "type": "integer",
            "nullable": true,
            "description": "Ledger timestamp when the stream ended (Unix), null if still active",
            "example": null
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StreamEvent": {
        "type": "object",
        "required": [
          "id",
          "streamId",
          "eventType",
          "transactionHash",
          "ledgerSequence",
          "timestamp"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "streamId": {
            "type": "integer",
            "description": "Reference to stream ID"
          },
          "eventType": {
            "type": "string",
            "enum": [
              "CREATED",
              "TOPPED_UP",
              "WITHDRAWN",
              "CANCELLED",
              "COMPLETED",
              "PAUSED",
              "RESUMED",
              "FEE_COLLECTED"
            ],
            "description": "Type of stream event",
            "example": "TOPPED_UP"
          },
          "amount": {
            "type": "string",
            "nullable": true,
            "description": "Amount involved in event (i128 as string)",
            "example": "5000"
          },
          "transactionHash": {
            "type": "string",
            "description": "Stellar transaction hash",
            "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
          },
          "ledgerSequence": {
            "type": "integer",
            "description": "Ledger sequence number",
            "example": 12345678
          },
          "timestamp": {
            "type": "integer",
            "description": "Event timestamp (Unix)",
            "example": 1708531200
          },
          "metadata": {
            "type": "string",
            "nullable": true,
            "description": "Additional event data (JSON string)"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StreamListResponse": {
        "type": "object",
        "required": [
          "data",
          "total",
          "hasMore",
          "limit",
          "offset"
        ],
        "properties": {
          "data": {
            "type": "array",
            "description": "Streams matching the filter, sorted and paginated",
            "items": {
              "$ref": "#/components/schemas/Stream"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of streams matching the filter"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether more results are available past this page"
          },
          "limit": {
            "type": "integer",
            "description": "Page size applied (capped at MAX_STREAM_PAGE_SIZE)"
          },
          "offset": {
            "type": "integer",
            "description": "Number of results skipped"
          }
        }
      },
      "StreamEventListResponse": {
        "type": "object",
        "required": [
          "data",
          "total",
          "hasMore"
        ],
        "properties": {
          "data": {
            "type": "array",
            "description": "Events for the stream, sorted by timestamp (tie-broken by id)",
            "items": {
              "$ref": "#/components/schemas/StreamEvent"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of events matching the filter"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether more results are available past this page"
          }
        }
      },
      "EventListResponse": {
        "type": "object",
        "required": [
          "events",
          "total",
          "limit",
          "offset",
          "hasMore"
        ],
        "properties": {
          "events": {
            "type": "array",
            "description": "Reverse-chronological stream events for the wallet",
            "items": {
              "$ref": "#/components/schemas/StreamEvent"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of matching events"
          },
          "limit": {
            "type": "integer",
            "description": "Page size applied (capped at 200)"
          },
          "offset": {
            "type": "integer",
            "description": "Number of events skipped"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether more results are available past this page"
          }
        }
      },
      "UserEventListResponse": {
        "type": "object",
        "required": [
          "data",
          "total",
          "hasMore",
          "limit",
          "offset"
        ],
        "properties": {
          "data": {
            "type": "array",
            "description": "Events associated with the user, newest first",
            "items": {
              "$ref": "#/components/schemas/StreamEvent"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of matching events"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether more results are available past this page"
          },
          "limit": {
            "type": "integer",
            "description": "Page size applied (capped at 200)"
          },
          "offset": {
            "type": "integer",
            "description": "Number of events skipped"
          }
        }
      },
      "UserStreamSummary": {
        "type": "object",
        "required": [
          "address",
          "totalStreamsCreated",
          "totalStreamedOut",
          "totalStreamedIn",
          "currentClaimable",
          "activeOutgoingCount",
          "activeIncomingCount"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "Stellar public key"
          },
          "totalStreamsCreated": {
            "type": "integer",
            "description": "Number of streams this wallet sent"
          },
          "totalStreamedOut": {
            "type": "string",
            "description": "Sum of withdrawn amounts on outgoing streams (i128 as string)"
          },
          "totalStreamedIn": {
            "type": "string",
            "description": "Sum of withdrawn amounts on incoming streams (i128 as string)"
          },
          "currentClaimable": {
            "type": "string",
            "description": "Total currently claimable across active incoming streams (i128 as string)"
          },
          "activeOutgoingCount": {
            "type": "integer"
          },
          "activeIncomingCount": {
            "type": "integer"
          },
          "truncated": {
            "type": "boolean",
            "description": "True when the number of streams was capped at MAX_USER_STREAMS per direction",
            "example": false
          }
        }
      },
      "ClaimableResponse": {
        "type": "object",
        "required": [
          "claimableAmount",
          "actionable",
          "calculatedAt"
        ],
        "properties": {
          "streamId": {
            "type": "integer",
            "description": "On-chain stream ID"
          },
          "ratePerSecond": {
            "type": "string",
            "description": "Payment rate per second (i128 as string)"
          },
          "depositedAmount": {
            "type": "string",
            "description": "Total deposited amount (i128 as string)"
          },
          "withdrawnAmount": {
            "type": "string",
            "description": "Total withdrawn amount (i128 as string)"
          },
          "startTime": {
            "type": "integer",
            "description": "Stream start time (Unix timestamp)"
          },
          "lastUpdateTime": {
            "type": "integer",
            "description": "Last state update time (Unix timestamp)"
          },
          "claimableAmount": {
            "type": "string",
            "description": "Amount claimable at the requested time (i128 as string)"
          },
          "actionable": {
            "type": "boolean",
            "description": "Whether the claimable amount is positive"
          },
          "calculatedAt": {
            "type": "integer",
            "description": "Unix timestamp of the calculation"
          },
          "cached": {
            "type": "boolean",
            "description": "Whether the value came from cache or a fresh computation"
          },
          "source": {
            "type": "string",
            "enum": [
              "db",
              "chain"
            ],
            "description": "Where the value was computed from"
          }
        }
      },
      "PauseResumeResponse": {
        "type": "object",
        "required": [
          "success",
          "streamId",
          "txHash"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "streamId": {
            "type": "integer"
          },
          "txHash": {
            "type": "string",
            "description": "Stellar transaction hash of the pause/resume simulation"
          },
          "stream": {
            "$ref": "#/components/schemas/Stream"
          }
        }
      },
      "TopUpResponse": {
        "type": "object",
        "required": [
          "streamId",
          "txHash",
          "depositedAmount"
        ],
        "properties": {
          "streamId": {
            "type": "integer"
          },
          "txHash": {
            "type": "string",
            "description": "Stellar transaction hash"
          },
          "depositedAmount": {
            "type": "string",
            "description": "New total deposited amount after the top-up (i128 as string)"
          }
        }
      },
      "WithdrawResponse": {
        "type": "object",
        "required": [
          "success",
          "streamId",
          "txHash",
          "amount"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "streamId": {
            "type": "integer"
          },
          "txHash": {
            "type": "string",
            "description": "Stellar transaction hash of the withdrawal"
          },
          "amount": {
            "type": "string",
            "description": "Amount withdrawn (i128 as string)"
          },
          "stream": {
            "$ref": "#/components/schemas/Stream"
          }
        }
      },
      "CancelResponse": {
        "type": "object",
        "required": [
          "txHash",
          "status"
        ],
        "properties": {
          "txHash": {
            "type": "string",
            "description": "Stellar transaction hash of the cancel"
          },
          "status": {
            "type": "string",
            "enum": [
              "CANCELLED"
            ],
            "example": "CANCELLED"
          }
        }
      },
      "AuthChallengeResponse": {
        "type": "object",
        "required": [
          "nonce",
          "expiresAt"
        ],
        "properties": {
          "nonce": {
            "type": "string",
            "description": "Hex-encoded nonce to sign via a Stellar manage_data operation"
          },
          "expiresAt": {
            "type": "integer",
            "description": "Unix timestamp (ms) when the challenge expires (60s)"
          }
        }
      },
      "AuthVerifyResponse": {
        "type": "object",
        "required": [
          "token",
          "expiresIn"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "JWT to use in the Authorization: Bearer header"
          },
          "expiresIn": {
            "type": "integer",
            "description": "Token lifetime in seconds (3600)"
          }
        }
      },
      "SseStats": {
        "type": "object",
        "required": [
          "activeConnections",
          "activeIps",
          "perIpPeakConnections",
          "maxConnections",
          "timestamp"
        ],
        "properties": {
          "activeConnections": {
            "type": "integer",
            "example": 42
          },
          "activeIps": {
            "type": "integer",
            "example": 8
          },
          "perIpPeakConnections": {
            "type": "integer",
            "example": 5
          },
          "maxConnections": {
            "type": "integer",
            "example": 10000
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookSubscription": {
        "type": "object",
        "required": [
          "id",
          "userAddress",
          "targetUrl",
          "eventTypes",
          "active",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Webhook subscription id"
          },
          "userAddress": {
            "type": "string",
            "description": "Stellar public key the subscription belongs to"
          },
          "targetUrl": {
            "type": "string",
            "description": "HTTPS endpoint receiving the events"
          },
          "eventTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "CREATED",
                "TOPPED_UP",
                "WITHDRAWN",
                "CANCELLED",
                "COMPLETED",
                "PAUSED",
                "RESUMED",
                "FEE_COLLECTED"
              ]
            }
          },
          "active": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": [
          "status",
          "db",
          "indexerEnabled",
          "uptime",
          "checks"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded"
            ],
            "example": "ok"
          },
          "db": {
            "type": "string",
            "enum": [
              "connected",
              "disconnected"
            ],
            "example": "connected"
          },
          "indexerEnabled": {
            "type": "boolean",
            "description": "Whether the event indexer is configured"
          },
          "indexerLag": {
            "type": "integer",
            "nullable": true,
            "description": "Seconds since last indexer update, or null when no state row exists yet"
          },
          "eventsProcessed": {
            "type": "integer",
            "description": "Lifetime count of successfully processed indexer events"
          },
          "eventsFailed": {
            "type": "integer",
            "description": "Lifetime count of indexer events that threw during processing"
          },
          "lastErrorAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Most recent per-event processing failure"
          },
          "indexerDegraded": {
            "type": "boolean",
            "description": "True when recent event-processing failure rate spikes"
          },
          "uptime": {
            "type": "number",
            "description": "Server uptime in seconds"
          },
          "checks": {
            "type": "object",
            "description": "Per-subsystem status breakdown",
            "properties": {
              "database": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "ok",
                      "down"
                    ]
                  }
                }
              },
              "indexer": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "ok",
                      "degraded",
                      "disabled"
                    ]
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "lagSeconds": {
                    "type": "integer",
                    "nullable": true
                  }
                }
              },
              "redis": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "ok",
                      "unavailable",
                      "not_configured"
                    ]
                  }
                }
              },
              "sorobanRpc": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "ok",
                      "down"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message",
            "example": "Resource not found"
          },
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "NOT_FOUND"
          },
          "message": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable detail (present on many error responses)"
          },
          "details": {
            "type": "array",
            "nullable": true,
            "description": "Structured validation issues (zod) when the error is a 400",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Simple health check",
        "description": "Returns a simple message to verify the API is running",
        "responses": {
          "200": {
            "description": "API is running successfully"
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Detailed health check",
        "description": "Returns liveness and readiness information.\n**Liveness** (200 vs 503) is determined by DB reachability alone.\n**Indexer lag** is reported in the body for observability but only\nforces a 503 when the indexer is actually enabled\n(`STREAM_CONTRACT_ID` env var set) and its state row is stale\n(lag > 60 s). A cold-started instance with no state row yet, or a\ndeployment with the indexer intentionally disabled, always returns 200\nas long as the DB is reachable.\n**Event-processing failures** are also reported. When the indexer is\nenabled and recent per-event failures spike (≥50% of attempts in the\nlast 5 minutes, with ≥3 samples), the endpoint returns 503 even if\nlag looks healthy (the IndexerState upsert bumps updatedAt every poll).\n",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service is degraded or unhealthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks": {
      "post": {
        "summary": "Register a new webhook subscription",
        "description": "Creates a webhook subscription. The returned `secretKey` is only shown once.",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userAddress",
                  "targetUrl",
                  "eventTypes"
                ],
                "properties": {
                  "userAddress": {
                    "type": "string",
                    "description": "Stellar public key"
                  },
                  "targetUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "eventTypes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "CREATED",
                        "TOPPED_UP",
                        "WITHDRAWN",
                        "CANCELLED",
                        "COMPLETED",
                        "PAUSED",
                        "RESUMED",
                        "FEE_COLLECTED"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscription": {
                      "$ref": "#/components/schemas/WebhookSubscription"
                    },
                    "secretKey": {
                      "type": "string",
                      "description": "Webhook signing secret (returned only once)"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List all webhooks for authenticated user",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "userAddress",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of webhook subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscriptions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookSubscription"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing userAddress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "summary": "Delete a webhook subscription",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "userAddress",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Webhook deleted successfully"
          },
          "400": {
            "description": "Invalid id or missing userAddress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "summary": "Send a test ping to a webhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userAddress"
                ],
                "properties": {
                  "userAddress": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Test webhook sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Test webhook sent"
                    },
                    "result": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing id or userAddress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Register a wallet public key",
        "description": "Registers a new Stellar wallet public key or returns the existing user if already registered.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "publicKey"
                ],
                "properties": {
                  "publicKey": {
                    "type": "string",
                    "description": "Stellar public key (G...)",
                    "example": "GABC123XYZ456DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "201": {
            "description": "User registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{publicKey}": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Fetch a user by public key",
        "description": "Returns user details along with recent sent and received streams.",
        "parameters": [
          {
            "in": "path",
            "name": "publicKey",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stellar public key"
          }
        ],
        "responses": {
          "200": {
            "description": "User found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/me": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get current authenticated user",
        "description": "Returns the currently authenticated user's details (protected endpoint)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current user details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{address}/summary": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get aggregate stream summary for a user",
        "description": "Returns dashboard/profile summary data for a wallet address:\ntotal created streams, total streamed out/in, current claimable across\nactive incoming streams, and active stream counts.\n\nResponse is cached for 30 seconds to reduce DB load.\n",
        "parameters": [
          {
            "in": "path",
            "name": "address",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stellar public key address"
          }
        ],
        "responses": {
          "200": {
            "description": "User stream summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserStreamSummary"
                }
              }
            }
          },
          "400": {
            "description": "Address is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{publicKey}/events": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Fetch user activity history",
        "description": "Returns a paginated chronological history of all stream events associated with the user.",
        "parameters": [
          {
            "in": "path",
            "name": "publicKey",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stellar public key"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            },
            "description": "Maximum number of events to return"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Number of events to skip for pagination"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of user events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserEventListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid pagination parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{address}/export": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Export transaction history for tax and accounting",
        "description": "Generates CSV or JSON export of stream transactions for QuickBooks, Xero, CoinTracker, etc.",
        "parameters": [
          {
            "in": "path",
            "name": "address",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stellar public key"
          },
          {
            "in": "query",
            "name": "format",
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "json"
              ],
              "default": "csv"
            },
            "description": "Export format"
          },
          {
            "in": "query",
            "name": "direction",
            "schema": {
              "type": "string",
              "enum": [
                "incoming",
                "outgoing",
                "all"
              ],
              "default": "all"
            },
            "description": "Filter by transaction direction"
          },
          {
            "in": "query",
            "name": "startDate",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start date (ISO 8601 or Unix timestamp)"
          },
          {
            "in": "query",
            "name": "endDate",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End date (ISO 8601 or Unix timestamp)"
          },
          {
            "in": "query",
            "name": "tokenAddress",
            "schema": {
              "type": "string"
            },
            "description": "Filter by specific token contract"
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction export file",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams": {
      "post": {
        "tags": [
          "Streams"
        ],
        "summary": "Create a new payment stream",
        "description": "Creates or reactivates a payment stream record for the authenticated wallet. The authenticated wallet must be the stream sender.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "streamId",
                  "sender",
                  "recipient",
                  "tokenAddress",
                  "ratePerSecond",
                  "depositedAmount",
                  "startTime"
                ],
                "properties": {
                  "streamId": {
                    "type": "integer",
                    "description": "On-chain stream ID",
                    "example": 1
                  },
                  "sender": {
                    "type": "string",
                    "description": "Sender Stellar public key — must match the authenticated wallet",
                    "example": "GABC123XYZ456DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA"
                  },
                  "recipient": {
                    "type": "string",
                    "description": "Recipient Stellar public key",
                    "example": "GDEF456ABC789GHI012JKL345MNO678PQR901STU234VWX567YZA123BCD"
                  },
                  "tokenAddress": {
                    "type": "string",
                    "description": "Token contract address",
                    "example": "CBCD789EFG012HIJ345KLM678NOP901QRS234TUV567WXY890ZAB123CDE"
                  },
                  "ratePerSecond": {
                    "type": "string",
                    "description": "Payment rate per second (i128 as string)",
                    "example": "100"
                  },
                  "depositedAmount": {
                    "type": "string",
                    "description": "Total deposited amount (i128 as string)",
                    "example": "10000"
                  },
                  "startTime": {
                    "type": "integer",
                    "description": "Stream start time (Unix timestamp)",
                    "example": 1708531200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stream created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stream"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - sender does not match the authenticated wallet, or stream is owned by another wallet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - rate limit exceeded (10 requests per minute)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Streams"
        ],
        "summary": "List payment streams",
        "description": "Retrieve a list of payment streams with optional filtering, sorting, and pagination.",
        "parameters": [
          {
            "in": "query",
            "name": "sender",
            "schema": {
              "type": "string"
            },
            "description": "Filter by sender public key"
          },
          {
            "in": "query",
            "name": "recipient",
            "schema": {
              "type": "string"
            },
            "description": "Filter by recipient public key"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "cancelled",
                "completed",
                "paused"
              ]
            },
            "description": "Filter by stream status"
          },
          {
            "in": "query",
            "name": "token",
            "schema": {
              "type": "string"
            },
            "description": "Filter by token contract address"
          },
          {
            "in": "query",
            "name": "sort",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "startTime",
                "lastUpdateTime",
                "depositedAmount",
                "endTime"
              ],
              "default": "createdAt"
            },
            "description": "Sort field"
          },
          {
            "in": "query",
            "name": "order",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            },
            "description": "Sort order"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Max results per page (capped at 100)"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Number of results to skip"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of streams",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid status or pagination parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/summary/{address}": {
      "get": {
        "tags": [
          "Streams"
        ],
        "summary": "Get user stream summary",
        "description": "Aggregate dashboard/profile summary for a wallet address. Cached for 30 seconds.",
        "parameters": [
          {
            "in": "path",
            "name": "address",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stellar public key"
          }
        ],
        "responses": {
          "200": {
            "description": "User stream summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserStreamSummary"
                }
              }
            }
          },
          "400": {
            "description": "Address is required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}": {
      "get": {
        "tags": [
          "Streams"
        ],
        "summary": "Get stream details",
        "description": "Returns a single stream. Falls back to live on-chain data when the DB record is missing or stale.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Stream details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stream"
                }
              }
            }
          },
          "400": {
            "description": "Invalid streamId parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/events": {
      "get": {
        "tags": [
          "Streams"
        ],
        "summary": "Get stream events",
        "description": "Retrieve events for a specific stream with pagination, filtering, and sorting.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Number of events to return per page (default: 50, max: 200)"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Number of events to skip (default: 0)"
          },
          {
            "in": "query",
            "name": "eventType",
            "schema": {
              "type": "string",
              "enum": [
                "CREATED",
                "TOPPED_UP",
                "WITHDRAWN",
                "CANCELLED",
                "COMPLETED",
                "PAUSED",
                "RESUMED",
                "FEE_COLLECTED",
                "FEE_CONFIG_UPDATED",
                "ADMIN_TRANSFERRED"
              ]
            },
            "description": "Filter events by type"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            },
            "description": "1-based page index (offset based). Ignored when `cursor` is set."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            },
            "description": "Event id cursor for stable pagination (hasMore-aware). Ignored when `offset` is set."
          },
          {
            "in": "query",
            "name": "order",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            },
            "description": "Sort order by timestamp (default: desc)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated stream events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamEventListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/claimable": {
      "get": {
        "tags": [
          "Streams"
        ],
        "summary": "Get actionable claimable amount for a stream",
        "description": "Returns the amount claimable right now (or at an optional timestamp). Uses a 5s-cached computation, with an on-chain fallback when the record is missing or stale.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          },
          {
            "in": "query",
            "name": "at",
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Optional Unix timestamp (seconds) to compute the claimable amount at"
          }
        ],
        "responses": {
          "200": {
            "description": "Claimable amount",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimableResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid streamId or `at` parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/pause": {
      "post": {
        "tags": [
          "Streams"
        ],
        "summary": "Pause a payment stream",
        "description": "Pause an active stream. Only the sender can pause their own stream.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream paused successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PauseResumeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid streamId, or on-chain pause simulation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - caller is not the stream sender",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - stream already paused or inactive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/resume": {
      "post": {
        "tags": [
          "Streams"
        ],
        "summary": "Resume a paused payment stream",
        "description": "Resume a paused stream. Only the sender can resume their own stream.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Stream resumed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PauseResumeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid streamId, or on-chain resume simulation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - caller is not the stream sender",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - stream not paused or inactive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/withdraw": {
      "post": {
        "tags": [
          "Streams"
        ],
        "summary": "Withdraw claimable balance from a payment stream",
        "description": "Withdraws the currently claimable amount. Only the recipient can withdraw.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawal submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid streamId or contract revert",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - caller is not the stream recipient",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - no claimable balance available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/top-up": {
      "post": {
        "tags": [
          "Streams"
        ],
        "summary": "Top up a payment stream",
        "description": "Adds additional funds to an existing active stream. Only the original sender can top up.",
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "string",
                    "description": "Amount to add to the stream deposit (i128 as string)",
                    "example": "5000"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stream topped up successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopUpResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — amount missing or not a positive integer string",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - caller is not the stream sender",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - stream inactive or paused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/streams/{streamId}/cancel": {
      "post": {
        "tags": [
          "Streams"
        ],
        "summary": "Cancel an active payment stream",
        "description": "Cancels an active payment stream on the Stellar network.\nOnly the original sender can cancel the stream.\nAccrued tokens are sent to the recipient, and the remainder is refunded to the sender.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "streamId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "On-chain stream ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Stream cancelled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse",
                  "type": "object",
                  "properties": {
                    "txHash": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "example": "CANCELLED"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid streamId or transaction simulation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - only sender can cancel",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Stream not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stream already cancelled or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "List stream events for a wallet (paginated, filterable)",
        "description": "Returns a reverse-chronological list of stream events where the wallet\nwas either the sender or recipient. Supports event-type filtering and\nlimit/offset pagination — used by the frontend activity timeline.\n",
        "parameters": [
          {
            "in": "query",
            "name": "address",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Stellar public key (G...)"
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of event types to include. Allowed values:\nCREATED, TOPPED_UP, WITHDRAWN, CANCELLED, COMPLETED, PAUSED,\nRESUMED, FEE_COLLECTED, FEE_CONFIG_UPDATED, ADMIN_TRANSFERRED.\n"
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Optional 1-based page index. Ignored when offset is set."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated event list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing/invalid `address` or invalid `type` filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - `address` must match the authenticated wallet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/subscribe": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Subscribe to real-time stream events",
        "description": "Establishes a Server-Sent Events (SSE) connection for real-time updates.\n\n**Reconnection Strategy:**\n- Browser automatically reconnects with exponential backoff\n- Initial retry: 1s, max: 30s\n- Client should implement custom reconnection logic for production\n\n**Event Types:**\n- `stream.created` - New stream created\n- `stream.topped_up` - Stream received additional funds\n- `stream.withdrawn` - Funds withdrawn from stream\n- `stream.cancelled` - Stream cancelled\n- `stream.completed` - Stream completed\n\n**Sandbox Mode:**\n- Add header `X-Sandbox-Mode: true` or query parameter `?sandbox=true`\n- Sandbox events are clearly marked with `_sandbox` metadata\n- Sandbox events are isolated from production events\n",
        "parameters": [
          {
            "in": "header",
            "name": "X-Sandbox-Mode",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Enable sandbox mode for testing",
            "required": false
          },
          {
            "in": "query",
            "name": "sandbox",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Enable sandbox mode via query parameter",
            "required": false
          },
          {
            "in": "query",
            "name": "streams",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Array of stream IDs to subscribe to",
            "example": [
              "1",
              "2"
            ]
          },
          {
            "in": "query",
            "name": "users",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Array of user public keys to subscribe to",
            "example": [
              "GABC...",
              "GDEF..."
            ]
          },
          {
            "in": "query",
            "name": "all",
            "schema": {
              "type": "boolean"
            },
            "description": "Subscribe to all events",
            "example": false
          }
        ],
        "responses": {
          "200": {
            "description": "SSE connection established. Events are emitted as `data:` frames of type stream.created, stream.topped_up, stream.withdrawn, stream.cancelled, stream.completed, stream.paused, stream.resumed, fee.collected.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events stream; each event carries a JSON payload matching the StreamEvent schema"
                }
              }
            }
          },
          "400": {
            "description": "Invalid subscription parameters"
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token"
          }
        }
      }
    },
    "/v1/events/stats": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Get SSE connection statistics",
        "description": "Returns current SSE connection metrics for monitoring (admin only)",
        "security": [
          {
            "adminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Connection statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SseStats"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/challenge": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Request a sign challenge for wallet authentication",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "publicKey"
                ],
                "properties": {
                  "publicKey": {
                    "type": "string",
                    "example": "GABC..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Challenge nonce issued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthChallengeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid publicKey",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/verify": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Verify signed challenge and receive JWT",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "publicKey",
                  "signedTransaction"
                ],
                "properties": {
                  "publicKey": {
                    "type": "string"
                  },
                  "signedTransaction": {
                    "type": "string",
                    "description": "Base64-encoded XDR signed transaction containing the nonce"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthVerifyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing publicKey or signedTransaction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid signature or expired challenge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/metrics": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Protocol health metrics",
        "security": [
          {
            "adminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Protocol health metrics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_streams": {
                      "type": "integer"
                    },
                    "active_streams": {
                      "type": "integer"
                    },
                    "paused_streams": {
                      "type": "integer"
                    },
                    "completed_streams": {
                      "type": "integer"
                    },
                    "cancelled_streams": {
                      "type": "integer"
                    },
                    "total_volume_streamed": {
                      "type": "string",
                      "description": "Sum of withdrawn amounts (i128 as string)"
                    },
                    "streams": {
                      "type": "object",
                      "properties": {
                        "active": {
                          "type": "integer"
                        },
                        "paused": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "byStatus": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "events": {
                      "type": "object",
                      "properties": {
                        "last24h": {
                          "type": "integer"
                        }
                      }
                    },
                    "fees": {
                      "type": "object",
                      "properties": {
                        "totalFeesCollectedByToken": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "feesLast24h": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "sse": {
                      "type": "object",
                      "properties": {
                        "activeConnections": {
                          "type": "integer"
                        }
                      }
                    },
                    "indexer": {
                      "type": "object",
                      "properties": {
                        "lastLedger": {
                          "type": "integer"
                        },
                        "lagSeconds": {
                          "type": "integer",
                          "nullable": true
                        },
                        "lastUpdated": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "eventsProcessed": {
                          "type": "integer"
                        },
                        "eventsFailed": {
                          "type": "integer"
                        },
                        "lastErrorAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "degraded": {
                          "type": "boolean"
                        }
                      }
                    },
                    "cache": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "pgPool": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "uptime": {
                      "type": "number"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "calculatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/indexer/status": {
      "get": {
        "tags": [
          "Admin"
        ],
        "summary": "Get indexer status",
        "security": [
          {
            "adminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Indexer status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/indexer/reset": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Reset indexer lastProcessedLedger (supports dry-run preview)",
        "security": [
          {
            "adminAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "dryRun",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "If true, return the projected reset scope without mutating state."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ledger"
                ],
                "properties": {
                  "ledger": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reset successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "lastLedger": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid ledger value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/indexer/replay": {
      "post": {
        "tags": [
          "Admin"
        ],
        "summary": "Replay events from a given ledger (supports dry-run preview)",
        "security": [
          {
            "adminAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "from_ledger",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "dryRun",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "If true, return the projected replay scope without mutating state."
          }
        ],
        "responses": {
          "200": {
            "description": "Dry-run preview of the replay scope"
          },
          "202": {
            "description": "Replay started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "replayingFrom": {
                      "type": "integer"
                    },
                    "requestId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid from_ledger value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}