flowfi.postman_collection.json

{
  "info": {
    "_postman_id": "7f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "name": "FlowFi API",
    "description": "Complete API collection for FlowFi — real-time payment streaming on Stellar.\n\n**Before you start:**\n1. Import one of the environment files from the same folder:\n   - `local.postman_environment.json` — Docker / manual local setup (port 3001)\n   - `test.postman_environment.json` — shared test deployment\n2. Select the imported environment from the top-right dropdown.\n3. Send requests. Variables like `{{baseUrl}}`, `{{senderPublicKey}}`, etc. are resolved automatically.\n\n**Sandbox mode:** Add `X-Sandbox-Mode: true` header or `?sandbox=true` to any request.\n**Swagger UI** (local): http://localhost:3001/api-docs\n**OpenAPI JSON** (local): http://localhost:3001/api-docs.json",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "http://localhost:3001",
      "type": "string",
      "description": "Overridden by the active environment file."
    }
  ],
  "item": [
    {
      "name": "Health",
      "description": "Liveness and readiness probes.",
      "item": [
        {
          "name": "Root ping",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/",
              "host": ["{{baseUrl}}"],
              "path": [""]
            },
            "description": "Simple liveness probe. Returns the plain-text string `FlowFi Backend is running` when the server is up."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "plain",
              "header": [{ "key": "Content-Type", "value": "text/plain; charset=utf-8" }],
              "body": "FlowFi Backend is running"
            }
          ]
        },
        {
          "name": "Detailed health check",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/health",
              "host": ["{{baseUrl}}"],
              "path": ["health"]
            },
            "description": "Returns status, uptime, version, supported API versions, and service health."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"status\": \"healthy\",\n  \"timestamp\": \"2024-02-21T14:30:00.000Z\",\n  \"uptime\": 3600,\n  \"version\": \"1.0.0\",\n  \"api\": {\n    \"supported\": [\"v1\"],\n    \"default\": \"v1\"\n  }\n}"
            }
          ]
        },
        {
          "name": "Swagger UI",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api-docs",
              "host": ["{{baseUrl}}"],
              "path": ["api-docs"]
            },
            "description": "Interactive Swagger UI for the FlowFi API. Open in a browser."
          },
          "response": []
        },
        {
          "name": "OpenAPI JSON spec",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api-docs.json",
              "host": ["{{baseUrl}}"],
              "path": ["api-docs.json"]
            },
            "description": "Raw OpenAPI 3.0 specification in JSON format."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Streams",
      "description": "Payment stream lifecycle management. All endpoints prefixed with `/v1/streams`.",
      "item": [
        {
          "name": "Create stream",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sender\": \"{{senderPublicKey}}\",\n  \"recipient\": \"{{recipientPublicKey}}\",\n  \"amount\": 10000,\n  \"token\": \"{{tokenAddress}}\",\n  \"startTime\": 1708531200,\n  \"endTime\": 1711209600\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/streams",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "streams"]
            },
            "description": "Creates a new payment stream.\n\n**Required:** `sender`, `recipient`, `amount` (positive), `token`.\n**Optional:** `startTime`, `endTime` (Unix timestamps).\n\nReturns **201 Created** with the stream object. Broadcasts `stream.created` SSE event."
          },
          "response": [
            {
              "name": "201 Created",
              "status": "Created",
              "code": 201,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"id\": \"uuid\",\n  \"streamId\": 1,\n  \"sender\": \"GABC...\",\n  \"recipient\": \"GDEF...\",\n  \"tokenAddress\": \"CBCD...\",\n  \"depositedAmount\": \"10000\",\n  \"isActive\": true,\n  \"startTime\": 1708531200,\n  \"createdAt\": \"2024-02-21T14:30:00.000Z\"\n}"
            },
            {
              "name": "400 Validation error",
              "status": "Bad Request",
              "code": 400,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"message\": \"Validation failed\",\n  \"errors\": [\n    { \"code\": \"too_small\", \"path\": [\"sender\"], \"message\": \"Sender address is required\" }\n  ]\n}"
            }
          ]
        },
        {
          "name": "List streams",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/streams?sender={{senderPublicKey}}&recipient={{recipientPublicKey}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "streams"],
              "query": [
                { "key": "sender", "value": "{{senderPublicKey}}", "description": "Filter by sender address (optional)." },
                { "key": "recipient", "value": "{{recipientPublicKey}}", "description": "Filter by recipient address (optional).", "disabled": true }
              ]
            },
            "description": "List all streams, optionally filtered by sender and/or recipient public key."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "[\n  {\n    \"streamId\": 1,\n    \"sender\": \"GABC...\",\n    \"recipient\": \"GDEF...\",\n    \"isActive\": true\n  }\n]"
            }
          ]
        },
        {
          "name": "Get stream by ID",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/streams/{{streamId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "streams", "{{streamId}}"]
            },
            "description": "Get details for a single stream including related events."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"streamId\": 1,\n  \"sender\": \"GABC...\",\n  \"recipient\": \"GDEF...\",\n  \"tokenAddress\": \"CBCD...\",\n  \"ratePerSecond\": \"115740\",\n  \"depositedAmount\": \"10000\",\n  \"withdrawnAmount\": \"0\",\n  \"startTime\": 1708531200,\n  \"lastUpdateTime\": 1708531200,\n  \"isActive\": true,\n  \"events\": []\n}"
            },
            {
              "name": "404 Not Found",
              "status": "Not Found",
              "code": 404,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"message\": \"Stream not found\"\n}"
            }
          ]
        },
        {
          "name": "Get stream events",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/streams/{{streamId}}/events",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "streams", "{{streamId}}", "events"]
            },
            "description": "Get all indexed on-chain events for a stream (CREATED, TOPPED_UP, WITHDRAWN, CANCELLED, COMPLETED)."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "[\n  {\n    \"id\": \"uuid\",\n    \"streamId\": 1,\n    \"eventType\": \"CREATED\",\n    \"transactionHash\": \"abc123...\",\n    \"ledgerSequence\": 12345,\n    \"timestamp\": 1708531200\n  }\n]"
            }
          ]
        },
        {
          "name": "Get claimable amount",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/streams/{{streamId}}/claimable",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "streams", "{{streamId}}", "claimable"],
              "query": [
                { "key": "at", "value": "", "description": "Optional Unix timestamp to calculate claimable at a specific time.", "disabled": true }
              ]
            },
            "description": "Calculate the actionable claimable amount for a stream. Supports caching."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"streamId\": 1,\n  \"claimableAmount\": \"5000\",\n  \"actionable\": true,\n  \"calculatedAt\": \"2024-02-21T14:30:00.000Z\",\n  \"cached\": false\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Users",
      "description": "User registration and profile endpoints. All prefixed with `/v1/users`.",
      "item": [
        {
          "name": "Register wallet",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"publicKey\": \"{{senderPublicKey}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/users",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "users"]
            },
            "description": "Register a Stellar wallet public key. Returns 201 for new users or 200 if the key already exists."
          },
          "response": [
            {
              "name": "201 Created",
              "status": "Created",
              "code": 201,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"id\": \"uuid\",\n  \"publicKey\": \"GABC...\",\n  \"createdAt\": \"2024-02-21T14:30:00.000Z\",\n  \"updatedAt\": \"2024-02-21T14:30:00.000Z\"\n}"
            }
          ]
        },
        {
          "name": "Get user by public key",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/users/{{senderPublicKey}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "users", "{{senderPublicKey}}"]
            },
            "description": "Get a user profile by Stellar public key, including their recent sent and received streams."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"id\": \"uuid\",\n  \"publicKey\": \"GABC...\",\n  \"sentStreams\": [],\n  \"receivedStreams\": []\n}"
            },
            {
              "name": "404 Not Found",
              "status": "Not Found",
              "code": 404,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"message\": \"User not found\"\n}"
            }
          ]
        },
        {
          "name": "Get current user (authenticated)",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{authToken}}", "description": "Signed Stellar transaction XDR (SEP-10)." }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/users/me",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "users", "me"]
            },
            "description": "Returns the authenticated user based on the signed Stellar transaction in the Authorization header (SEP-10 auth)."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"id\": \"uuid\",\n  \"publicKey\": \"GABC...\"\n}"
            },
            {
              "name": "401 Unauthorized",
              "status": "Unauthorized",
              "code": 401,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"message\": \"Unauthorized\"\n}"
            }
          ]
        },
        {
          "name": "Get user activity events",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/users/{{senderPublicKey}}/events",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "users", "{{senderPublicKey}}", "events"]
            },
            "description": "Get all stream events associated with a user (as sender or recipient)."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "[\n  {\n    \"id\": \"uuid\",\n    \"streamId\": 1,\n    \"eventType\": \"CREATED\",\n    \"timestamp\": 1708531200\n  }\n]"
            }
          ]
        }
      ]
    },
    {
      "name": "Events (SSE)",
      "description": "Server-Sent Events for real-time stream updates. All prefixed with `/v1/events`.",
      "item": [
        {
          "name": "Subscribe to stream events (SSE)",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "text/event-stream" },
              { "key": "Cache-Control", "value": "no-cache" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/events/subscribe?streams={{streamId}}&users={{senderPublicKey}}&all=false",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "events", "subscribe"],
              "query": [
                { "key": "streams", "value": "{{streamId}}", "description": "Stream ID to watch. Repeat for multiple." },
                { "key": "users", "value": "{{senderPublicKey}}", "description": "Public key to watch. Repeat for multiple." },
                { "key": "all", "value": "false", "description": "Set to true to receive all events." }
              ]
            },
            "description": "Establishes a persistent SSE connection. Pushes events: `stream.created`, `stream.topped_up`, `stream.withdrawn`, `stream.cancelled`, `stream.completed`.\n\nUse at least one filter: `streams`, `users`, or `all=true`.\n\n**Postman note:** SSE is buffered. Use *Send and Download*, or test with:\n```\ncurl -N --no-buffer '{{baseUrl}}/v1/events/subscribe?all=true'\n```"
          },
          "response": [
            {
              "name": "200 SSE stream",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "text",
              "header": [
                { "key": "Content-Type", "value": "text/event-stream" },
                { "key": "Cache-Control", "value": "no-cache" },
                { "key": "Connection", "value": "keep-alive" }
              ],
              "body": "data: {\"type\":\"connected\",\"clientId\":\"1708531200-abc123xyz\"}\n\nevent: stream.created\ndata: {\"streamId\":1,\"sender\":\"GABC...\",\"recipient\":\"GDEF...\",\"amount\":10000}\n\n"
            },
            {
              "name": "400 Missing filter",
              "status": "Bad Request",
              "code": 400,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"message\": \"Invalid subscription parameters\"\n}"
            }
          ]
        },
        {
          "name": "Get SSE connection stats",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/events/stats",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "events", "stats"]
            },
            "description": "Returns the count of active SSE connections and server timestamp."
          },
          "response": [
            {
              "name": "200 OK",
              "status": "OK",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [{ "key": "Content-Type", "value": "application/json; charset=utf-8" }],
              "body": "{\n  \"activeConnections\": 3,\n  \"timestamp\": \"2024-02-21T14:30:00.000Z\"\n}"
            }
          ]
        }
      ]
    }
  ]
}