openapi.json

{
  "components": {
    "parameters": {},
    "schemas": {
      "AdminCacheStatsResponse": {
        "properties": {
          "hitRate": {
            "description": "Cache hit ratio",
            "type": "number"
          },
          "hits": {
            "description": "Cache hit count",
            "type": "integer"
          },
          "keys": {
            "description": "Cached key prefixes or names",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "misses": {
            "description": "Cache miss count",
            "type": "integer"
          },
          "size": {
            "description": "Number of active cached entries",
            "type": "integer"
          },
          "ttlMs": {
            "description": "Configured cache TTL in milliseconds",
            "type": "integer"
          }
        },
        "required": [
          "size",
          "keys",
          "ttlMs"
        ],
        "type": "object"
      },
      "AdminIsTokenAllowedResponse": {
        "properties": {
          "isAllowed": {
            "description": "Whether token is allowlisted",
            "type": "boolean"
          },
          "token": {
            "description": "Token contract address checked",
            "type": "string"
          }
        },
        "required": [
          "token",
          "isAllowed"
        ],
        "type": "object"
      },
      "AdminStatus": {
        "properties": {
          "admin": {
            "nullable": true,
            "type": "string"
          },
          "isPaused": {
            "type": "boolean"
          }
        },
        "required": [
          "admin",
          "isPaused"
        ],
        "type": "object"
      },
      "AdminStatusResponse": {
        "properties": {
          "admin": {
            "description": "Current contract admin Stellar address or null",
            "nullable": true,
            "type": "string"
          },
          "isPaused": {
            "description": "Whether contract distributions are globally paused",
            "type": "boolean"
          }
        },
        "required": [
          "admin",
          "isPaused"
        ],
        "type": "object"
      },
      "AdminTokenCountResponse": {
        "properties": {
          "count": {
            "description": "Number of allowlisted tokens",
            "type": "integer"
          }
        },
        "required": [
          "count"
        ],
        "type": "object"
      },
      "AdminUnallocatedResponse": {
        "properties": {
          "token": {
            "description": "Token contract address",
            "type": "string"
          },
          "unallocated": {
            "description": "Recoverable unallocated stroops as string",
            "type": "string"
          }
        },
        "required": [
          "token",
          "unallocated"
        ],
        "type": "object"
      },
      "AdminUnsignedXdrResponse": {
        "properties": {
          "metadata": {
            "properties": {
              "auditContext": {
                "additionalProperties": {
                  "nullable": true
                },
                "description": "Audit logging context metadata",
                "type": "object"
              },
              "contractId": {
                "description": "Deployed contract ID",
                "type": "string"
              },
              "fee": {
                "description": "Transaction fee in stroops",
                "type": "string"
              },
              "networkPassphrase": {
                "description": "Stellar network passphrase",
                "type": "string"
              },
              "operation": {
                "description": "Invoked contract method name",
                "type": "string"
              },
              "sequenceNumber": {
                "description": "Account sequence number",
                "type": "string"
              },
              "sourceAccount": {
                "description": "Admin source account address",
                "type": "string"
              }
            },
            "required": [
              "contractId",
              "networkPassphrase",
              "sourceAccount",
              "operation"
            ],
            "type": "object"
          },
          "xdr": {
            "description": "Base64 encoded unsigned transaction envelope",
            "type": "string"
          }
        },
        "required": [
          "xdr",
          "metadata"
        ],
        "type": "object"
      },
      "ApiError": {
        "example": {
          "details": {
            "path": [
              "collaborators"
            ]
          },
          "error": "VALIDATION_ERROR",
          "message": "collaborators basisPoints must sum to exactly 10000",
          "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
        },
        "properties": {
          "details": {
            "additionalProperties": {
              "nullable": true
            },
            "description": "Additional error context",
            "type": "object"
          },
          "error": {
            "description": "Machine-readable error code",
            "type": "string"
          },
          "message": {
            "description": "Human-readable error message",
            "type": "string"
          },
          "requestId": {
            "description": "Request correlation ID",
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ClaimableResponse": {
        "properties": {
          "claimable": {
            "description": "Amount available to claim, in stroops",
            "type": "string"
          },
          "claimed": {
            "description": "Amount already claimed, in stroops",
            "type": "string"
          },
          "collaborator": {
            "description": "Stellar address of the collaborator",
            "type": "string"
          },
          "projectId": {
            "description": "The project ID",
            "type": "string"
          },
          "total": {
            "description": "Total allocated (claimed + claimable), in stroops",
            "type": "string"
          }
        },
        "required": [
          "projectId",
          "collaborator",
          "claimable",
          "claimed",
          "total"
        ],
        "type": "object"
      },
      "ComponentHealth": {
        "properties": {
          "latencyMs": {
            "description": "Round-trip latency of the underlying check, in milliseconds",
            "type": "number"
          },
          "message": {
            "description": "Redacted, human-readable detail. Never contains secrets or raw connection strings.",
            "type": "string"
          },
          "status": {
            "enum": [
              "up",
              "degraded",
              "down"
            ],
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "type": "object"
      },
      "EnvComponentHealth": {
        "properties": {
          "ok": {
            "description": "Whether required environment variables are present and valid",
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      },
      "EventListenerComponentHealth": {
        "properties": {
          "consecutiveErrors": {
            "description": "Number of consecutive failing polls",
            "type": "integer"
          },
          "lastSuccessfulPoll": {
            "description": "ISO 8601 timestamp of the last successful poll, or null",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "enum": [
              "stopped",
              "healthy",
              "degraded"
            ],
            "type": "string"
          }
        },
        "required": [
          "status",
          "lastSuccessfulPoll",
          "consecutiveErrors"
        ],
        "type": "object"
      },
      "HealthResponse": {
        "properties": {
          "status": {
            "enum": [
              "ok",
              "degraded",
              "not_ready"
            ],
            "type": "string"
          },
          "timestamp": {
            "description": "ISO 8601 timestamp",
            "type": "string"
          },
          "uptime": {
            "description": "Server uptime in seconds",
            "type": "number"
          }
        },
        "required": [
          "status"
        ],
        "type": "object"
      },
      "MainnetReadinessResponse": {
        "properties": {
          "components": {
            "properties": {
              "cache": {
                "properties": {
                  "details": {
                    "additionalProperties": {
                      "nullable": true
                    },
                    "type": "object"
                  },
                  "message": {
                    "type": "string"
                  },
                  "ok": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "ok"
                ],
                "type": "object"
              },
              "db": {
                "properties": {
                  "details": {
                    "additionalProperties": {
                      "nullable": true
                    },
                    "type": "object"
                  },
                  "message": {
                    "type": "string"
                  },
                  "ok": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "ok"
                ],
                "type": "object"
              },
              "deploy": {
                "properties": {
                  "contractIdMatch": {
                    "type": "boolean"
                  },
                  "databasePoolMax": {
                    "type": "number"
                  },
                  "message": {
                    "type": "string"
                  },
                  "ok": {
                    "type": "boolean"
                  },
                  "productionSecrets": {
                    "properties": {
                      "mainnetContractId": {
                        "type": "boolean"
                      },
                      "renderBackendDeployHookUrl": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "mainnetContractId",
                      "renderBackendDeployHookUrl"
                    ],
                    "type": "object"
                  },
                  "readCacheMaxEntries": {
                    "type": "number"
                  },
                  "readCacheTtlMs": {
                    "type": "number"
                  }
                },
                "required": [
                  "ok"
                ],
                "type": "object"
              },
              "env": {
                "properties": {
                  "details": {
                    "additionalProperties": {
                      "nullable": true
                    },
                    "type": "object"
                  },
                  "message": {
                    "type": "string"
                  },
                  "ok": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "ok"
                ],
                "type": "object"
              }
            },
            "required": [
              "env",
              "db",
              "cache",
              "deploy"
            ],
            "type": "object"
          },
          "details": {
            "additionalProperties": {
              "nullable": true
            },
            "type": "object"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "status": {
            "enum": [
              "ready",
              "not_ready"
            ],
            "type": "string"
          }
        },
        "required": [
          "status",
          "components"
        ],
        "type": "object"
      },
      "OpsBackfillResponse": {
        "properties": {
          "error": {
            "description": "Error details if backfill failed",
            "type": "string"
          },
          "message": {
            "description": "Human-readable status message",
            "type": "string"
          },
          "success": {
            "description": "Whether backfill operation completed",
            "type": "boolean"
          }
        },
        "required": [
          "success"
        ],
        "type": "object"
      },
      "OpsStatusResponse": {
        "properties": {
          "database": {
            "properties": {
              "connected": {
                "description": "Whether database data-source is initialized",
                "type": "boolean"
              }
            },
            "required": [
              "connected"
            ],
            "type": "object"
          },
          "eventListener": {
            "properties": {
              "consecutiveErrors": {
                "description": "Count of consecutive poll failures",
                "type": "integer"
              },
              "lastSuccessfulPoll": {
                "description": "ISO timestamp of last successful poll",
                "nullable": true,
                "type": "string"
              },
              "ledgerLag": {
                "description": "Lag behind latest ledger",
                "type": "number"
              },
              "status": {
                "description": "EventListener lifecycle status",
                "type": "string"
              }
            },
            "required": [
              "status"
            ],
            "type": "object"
          },
          "idempotency": {
            "description": "Idempotency conflict and replay counters",
            "properties": {
              "conflictsTotal": {
                "description": "Total idempotency 409 conflicts",
                "minimum": 0,
                "type": "integer"
              },
              "replaysTotal": {
                "description": "Total idempotency replays",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "conflictsTotal",
              "replaysTotal"
            ],
            "type": "object"
          }
        },
        "required": [
          "eventListener",
          "database"
        ],
        "type": "object"
      },
      "Project": {
        "properties": {
          "balance": {
            "type": "string"
          },
          "collaborators": {
            "items": {
              "properties": {
                "address": {
                  "type": "string"
                },
                "alias": {
                  "type": "string"
                },
                "basisPoints": {
                  "type": "number"
                }
              },
              "required": [
                "address",
                "alias",
                "basisPoints"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "locked": {
            "type": "boolean"
          },
          "owner": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "projectType": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "token": {
            "type": "string"
          },
          "totalDistributed": {
            "type": "string"
          }
        },
        "required": [
          "projectId",
          "title",
          "projectType",
          "owner",
          "token",
          "balance",
          "totalDistributed",
          "locked",
          "collaborators"
        ],
        "type": "object"
      },
      "ReadinessComponents": {
        "properties": {
          "contract": {
            "$ref": "#/components/schemas/ComponentHealth"
          },
          "db": {
            "$ref": "#/components/schemas/ComponentHealth"
          },
          "env": {
            "$ref": "#/components/schemas/EnvComponentHealth"
          },
          "eventListener": {
            "$ref": "#/components/schemas/EventListenerComponentHealth"
          },
          "rpc": {
            "$ref": "#/components/schemas/ComponentHealth"
          }
        },
        "required": [
          "env",
          "db",
          "rpc",
          "contract"
        ],
        "type": "object"
      },
      "ReadinessResponse": {
        "properties": {
          "components": {
            "$ref": "#/components/schemas/ReadinessComponents"
          },
          "error": {
            "description": "Error code if not ready",
            "type": "string"
          },
          "issues": {
            "description": "List of configuration issues",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "message": {
            "description": "Error message if not ready",
            "type": "string"
          },
          "requestId": {
            "description": "Request ID for tracing",
            "type": "string"
          },
          "status": {
            "description": "Issue #935 status/status-code policy: \"ready\" -> 200 (all dependencies up); \"degraded\" -> 200 (service still usable, but at least one dependency is slow or in a non-fatal failure state - investigate, don't page); \"not_ready\" -> 503 (env invalid or a dependency is fully down, unchanged from the legacy binary contract).",
            "enum": [
              "ready",
              "degraded",
              "not_ready"
            ],
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "type": "object"
      },
      "XdrResponse": {
        "properties": {
          "metadata": {
            "properties": {
              "contractId": {
                "type": "string"
              },
              "networkPassphrase": {
                "type": "string"
              },
              "operation": {
                "type": "string"
              },
              "sourceAccount": {
                "type": "string"
              }
            },
            "required": [
              "contractId",
              "networkPassphrase",
              "sourceAccount",
              "operation"
            ],
            "type": "object"
          },
          "xdr": {
            "type": "string"
          }
        },
        "required": [
          "xdr",
          "metadata"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "adminApiKey": {
        "description": "Payments admin API key for /splits/admin mutation endpoints",
        "in": "header",
        "name": "x-admin-api-key",
        "type": "apiKey"
      },
      "bearerAuth": {
        "bearerFormat": "JWT",
        "description": "JWT obtained from POST /users/login",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Premium royalty management API on Stellar network.",
    "title": "SplitNaira API",
    "version": "0.1.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "status",
                    "version"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "API metadata"
          }
        },
        "summary": "Get API information",
        "tags": [
          "System"
        ]
      }
    },
    "/events": {
      "get": {
        "description": "Opens a Server-Sent Events stream and emits a `transaction_update` event each time the backend observes an update for the given `txHash`. Limited to 5 concurrent subscribers per `txHash` (configurable via `SSE_MAX_LISTENERS_PER_TXHASH`); exceeding it returns 429.\n\nExample frame:\n```\nevent: transaction_update\ndata: {\"txHash\":\"3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc\",\"status\":\"pending\"}\n\n```",
        "parameters": [
          {
            "description": "Transaction hash to observe",
            "in": "query",
            "name": "txHash",
            "required": true,
            "schema": {
              "description": "Transaction hash to observe",
              "example": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc",
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "example": "event: transaction_update\ndata: {\"txHash\":\"3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc\",\"status\":\"pending\"}\n\n",
                  "type": "string"
                }
              }
            },
            "description": "text/event-stream of `transaction_update` frames (connection stays open)"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "429": {
            "content": {
              "application/json": {
                "example": {
                  "code": "RESOURCE_LIMIT_EXCEEDED",
                  "details": {
                    "limit": 5,
                    "txHash": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc"
                  },
                  "error": "too_many_event_listeners",
                  "message": "Too many event stream subscribers for this transaction.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Too many concurrent subscribers for this txHash"
          }
        },
        "summary": "Observe transaction status updates for a submitted XDR (SSE)",
        "tags": [
          "Events"
        ]
      }
    },
    "/events/transactions/{txHash}": {
      "get": {
        "description": "Opens a Server-Sent Events stream and emits one `transaction:confirmed` event with the full transaction record once `EventListenerService` observes it on-chain. Sends a `: heartbeat` comment every 15s to keep intermediary proxies from closing the connection.\n\nExample frame:\n```\nevent: transaction:confirmed\ndata: {\"txHash\":\"3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc\",\"roundId\":\"afrobeats_001\",\"recipient\":\"GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV\",\"amount\":\"1000\",\"token\":\"native\",\"timestamp\":1732012800,\"status\":\"completed\"}\n\n```",
        "parameters": [
          {
            "in": "path",
            "name": "txHash",
            "required": true,
            "schema": {
              "example": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc",
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "example": "event: transaction:confirmed\ndata: {\"txHash\":\"3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc\",\"roundId\":\"afrobeats_001\",\"recipient\":\"GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV\",\"amount\":\"1000\",\"token\":\"native\",\"timestamp\":1732012800,\"status\":\"completed\"}\n\n",
                  "type": "string"
                }
              }
            },
            "description": "text/event-stream of a single `transaction:confirmed` frame (connection stays open until then)"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          }
        },
        "summary": "Observe a single transaction until it's confirmed (SSE)",
        "tags": [
          "Events"
        ]
      }
    },
    "/health": {
      "get": {
        "description": "Alias for /health/ready. Returns 200 for both \"ready\" and \"degraded\" (service still usable); 503 only for \"not_ready\" (Issue #935).",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessResponse"
                }
              }
            },
            "description": "Server is ready to accept traffic, or degraded but still usable"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessResponse"
                }
              }
            },
            "description": "Server is not ready"
          }
        },
        "summary": "Get readiness status (alias for /health/ready)",
        "tags": [
          "Health"
        ]
      }
    },
    "/health/live": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "status": {
                      "enum": [
                        "ok"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Server is alive"
          }
        },
        "summary": "Liveness check (Kubernetes compatible)",
        "tags": [
          "Health"
        ]
      }
    },
    "/health/ready": {
      "get": {
        "description": "Issue #935: returns 200 with status \"ready\" (all dependencies up) or \"degraded\" (usable, but db/rpc/contract/eventListener is slow or non-fatally impaired); returns 503 with status \"not_ready\" only when env is invalid or a dependency is fully down. See docs/runbooks/observability.md for the on-call interpretation of each state.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessResponse"
                }
              }
            },
            "description": "Server is ready to accept traffic, or degraded but still usable"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadinessResponse"
                }
              }
            },
            "description": "Server is not ready (missing configuration or a dependency is down)"
          }
        },
        "summary": "Readiness check (Kubernetes compatible)",
        "tags": [
          "Health"
        ]
      }
    },
    "/ops/backfill": {
      "post": {
        "description": "Backfills missed ledger events starting from a given ledger sequence.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "fromLedger": {
                    "description": "Starting ledger sequence number",
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpsBackfillResponse"
                }
              }
            },
            "description": "Backfill outcome"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Trigger event history backfill",
        "tags": [
          "Operations"
        ]
      }
    },
    "/ops/mainnet-readiness": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MainnetReadinessResponse"
                }
              }
            },
            "description": "Mainnet readiness validation passed"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MainnetReadinessResponse"
                }
              }
            },
            "description": "Mainnet readiness validation failed"
          }
        },
        "summary": "Mainnet readiness validation for deployment and ops workflows",
        "tags": [
          "Operations"
        ]
      }
    },
    "/ops/status": {
      "get": {
        "description": "Returns status of the event listener service, ledger lag, and database connection.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpsStatusResponse"
                }
              }
            },
            "description": "Operations status"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Get operational service health and lag",
        "tags": [
          "Operations"
        ]
      }
    },
    "/splits": {
      "get": {
        "description": "Returns a paginated list of on-chain split projects with optional search and type filters.",
        "parameters": [
          {
            "in": "query",
            "name": "start",
            "required": false,
            "schema": {
              "default": 0,
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 10,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "search",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Project"
                  },
                  "type": "array"
                }
              }
            },
            "description": "List of projects"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "429": {
            "content": {
              "application/json": {
                "example": {
                  "error": "RATE_LIMIT_EXCEEDED",
                  "message": "Too many requests. Please retry after the rate limit window.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Too many requests"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "List all split projects",
        "tags": [
          "Splits"
        ]
      },
      "post": {
        "description": "Builds an unsigned Soroban transaction XDR to create a new revenue-split project on-chain. The caller must sign the returned XDR with the `owner` wallet and submit it themselves; this endpoint never holds a private key. Supports an optional `Idempotency-Key` header (Issue #888) so retried requests don't produce duplicate project-creation attempts.",
        "parameters": [
          {
            "description": "Client-generated unique token identifying this create-split request (Issue #888). Replaying the same key with an identical payload returns the original response instead of resubmitting; replaying it with a different payload returns 409 IDEMPOTENCY_KEY_CONFLICT. Keys expire after IDEMPOTENCY_KEY_TTL_MS (default 24h), after which the request is treated as new.",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "description": "Client-generated unique token identifying this create-split request (Issue #888). Replaying the same key with an identical payload returns the original response instead of resubmitting; replaying it with a different payload returns 409 IDEMPOTENCY_KEY_CONFLICT. Keys expire after IDEMPOTENCY_KEY_TTL_MS (default 24h), after which the request is treated as new.",
              "example": "550e8400-e29b-41d4-a716-446655440000",
              "maxLength": 255,
              "minLength": 1,
              "pattern": "^[A-Za-z0-9_.:-]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "collaborators": [
                  {
                    "address": "GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV",
                    "alias": "Producer",
                    "basisPoints": 6000
                  },
                  {
                    "address": "GBG234UA6RBPDD5K6FHMQXHUXB5ALOENQGH24Y3W4ERX2YJNQ4MK4V25",
                    "alias": "Vocalist",
                    "basisPoints": 4000
                  }
                ],
                "owner": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT",
                "projectId": "afrobeats_001",
                "projectType": "music",
                "title": "Afrobeats Collective Vol. 1",
                "token": "CDOVDY3MZDG7PHCGVP7EP2EKQ2ENV26DZW6FKLBRN42LOGIZGXZV3WX5"
              },
              "schema": {
                "properties": {
                  "collaborators": {
                    "items": {
                      "properties": {
                        "address": {
                          "minLength": 1,
                          "type": "string"
                        },
                        "alias": {
                          "maxLength": 100,
                          "minLength": 1,
                          "type": "string"
                        },
                        "basisPoints": {
                          "exclusiveMinimum": true,
                          "maximum": 10000,
                          "minimum": 0,
                          "type": "integer"
                        }
                      },
                      "required": [
                        "address",
                        "alias",
                        "basisPoints"
                      ],
                      "type": "object"
                    },
                    "minItems": 2,
                    "type": "array"
                  },
                  "owner": {
                    "description": "owner",
                    "minLength": 1,
                    "type": "string"
                  },
                  "projectId": {
                    "maxLength": 32,
                    "minLength": 1,
                    "pattern": "^[a-zA-Z0-9_]+$",
                    "type": "string"
                  },
                  "projectType": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "token": {
                    "description": "token",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "owner",
                  "projectId",
                  "title",
                  "projectType",
                  "token",
                  "collaborators"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "metadata": {
                    "contractId": "CAGR5U5IBEPFVJDZPZUXXNCPXAHNZ6TWVIUTI5RLRH3SZSU4O2VXDOPF",
                    "networkPassphrase": "Test SDF Network ; September 2015",
                    "operation": "create_project",
                    "sourceAccount": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
                  },
                  "xdr": "AAAAAgAAAAC5tRUXpDqRcTvpvKF...(truncated unsigned transaction envelope)"
                },
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR ready for the owner to sign and submit"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "details": {
                    "path": [
                      "collaborators"
                    ]
                  },
                  "error": "VALIDATION_ERROR",
                  "message": "collaborators basisPoints must sum to exactly 10000",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "409": {
            "content": {
              "application/json": {
                "example": {
                  "code": "IDEMPOTENCY_KEY_CONFLICT",
                  "error": "IDEMPOTENCY_KEY_CONFLICT",
                  "message": "Idempotency-Key was already used with a different request payload.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Conflict with existing resource"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Create a new split project",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/admin/allow-token": {
      "post": {
        "description": "Builds an unsigned transaction XDR to add a token to the allowlist. Requires admin authorization.",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "admin": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT",
                "token": "CDOVDY3MZDG7PHCGVP7EP2EKQ2ENV26DZW6FKLBRN42LOGIZGXZV3WX5"
              },
              "schema": {
                "properties": {
                  "admin": {
                    "description": "admin",
                    "minLength": 1,
                    "type": "string"
                  },
                  "token": {
                    "description": "token",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "admin",
                  "token"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnsignedXdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "error": "SERVICE_UNAVAILABLE",
                  "message": "The service is temporarily unavailable. Please try again shortly.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Service temporarily unavailable"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Allow a token on the contract",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/allowlist": {
      "get": {
        "description": "Returns the contract admin address, total allowed token count, and a paginated token allowlist.",
        "parameters": [
          {
            "in": "query",
            "name": "start",
            "required": false,
            "schema": {
              "default": 0,
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "admin": {
                      "nullable": true,
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "tokens": {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "admin",
                    "count",
                    "tokens"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Token allowlist page"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "FORBIDDEN",
                  "message": "You do not have permission to perform this action.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Access denied"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "List allowed payment tokens",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/cache-stats": {
      "get": {
        "description": "Returns in-memory read cache statistics and TTL configuration.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminCacheStatsResponse"
                }
              }
            },
            "description": "Cache statistics"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Get read-cache diagnostic stats",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/disallow-token": {
      "post": {
        "description": "Builds an unsigned transaction XDR to remove a token from the allowlist. Requires admin authorization.",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "admin": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT",
                "token": "CDOVDY3MZDG7PHCGVP7EP2EKQ2ENV26DZW6FKLBRN42LOGIZGXZV3WX5"
              },
              "schema": {
                "properties": {
                  "admin": {
                    "description": "admin",
                    "minLength": 1,
                    "type": "string"
                  },
                  "token": {
                    "description": "token",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "admin",
                  "token"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnsignedXdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "error": "SERVICE_UNAVAILABLE",
                  "message": "The service is temporarily unavailable. Please try again shortly.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Service temporarily unavailable"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Disallow a token on the contract",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/is-token-allowed": {
      "get": {
        "description": "Queries whether a given token address is allowed on the contract. Protected by payments admin authorization.",
        "parameters": [
          {
            "description": "token contract address to check",
            "in": "query",
            "name": "token",
            "required": true,
            "schema": {
              "description": "token contract address to check",
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminIsTokenAllowedResponse"
                }
              }
            },
            "description": "Token allowlist status"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Check if a token is allowlisted",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/pause-distributions": {
      "post": {
        "description": "Builds an unsigned transaction XDR to pause contract-wide distributions. Requires admin authorization.",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "admin": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
              },
              "schema": {
                "properties": {
                  "admin": {
                    "description": "admin",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "admin"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnsignedXdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "error": "SERVICE_UNAVAILABLE",
                  "message": "The service is temporarily unavailable. Please try again shortly.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Service temporarily unavailable"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Pause all contract distributions",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/status": {
      "get": {
        "description": "Returns the current contract admin address and pause state. Protected by payments admin authorization.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminStatusResponse"
                }
              }
            },
            "description": "Admin and distribution pause status"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Get contract admin and pause status",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/token-count": {
      "get": {
        "description": "Returns the total number of allowlisted tokens. Protected by payments admin authorization.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminTokenCountResponse"
                }
              }
            },
            "description": "Allowed token count"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Get allowed token count",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/unallocated": {
      "get": {
        "description": "Returns the recoverable unallocated token balance on the contract. Protected by payments admin authorization.",
        "parameters": [
          {
            "description": "token contract address",
            "in": "query",
            "name": "token",
            "required": true,
            "schema": {
              "description": "token contract address",
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnallocatedResponse"
                }
              }
            },
            "description": "Unallocated token balance in stroops"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Get unallocated token balance",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/unpause-distributions": {
      "post": {
        "description": "Builds an unsigned transaction XDR to unpause contract-wide distributions. Requires admin authorization.",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "admin": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
              },
              "schema": {
                "properties": {
                  "admin": {
                    "description": "admin",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "admin"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnsignedXdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "error": "SERVICE_UNAVAILABLE",
                  "message": "The service is temporarily unavailable. Please try again shortly.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Service temporarily unavailable"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Unpause contract distributions",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/admin/withdraw-unallocated": {
      "post": {
        "description": "Builds an unsigned transaction XDR to recover unallocated funds. Includes audit context.",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "admin": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT",
                "amount": 500000,
                "to": "GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV",
                "token": "CDOVDY3MZDG7PHCGVP7EP2EKQ2ENV26DZW6FKLBRN42LOGIZGXZV3WX5"
              },
              "schema": {
                "properties": {
                  "admin": {
                    "description": "admin",
                    "minLength": 1,
                    "type": "string"
                  },
                  "amount": {
                    "description": "amount in stroops to recover",
                    "exclusiveMinimum": true,
                    "minimum": 0,
                    "type": "number"
                  },
                  "to": {
                    "description": "destination address",
                    "minLength": 1,
                    "type": "string"
                  },
                  "token": {
                    "description": "token contract address",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "admin",
                  "token",
                  "to",
                  "amount"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminUnsignedXdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR with audit context"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "error": "SERVICE_UNAVAILABLE",
                  "message": "The service is temporarily unavailable. Please try again shortly.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Service temporarily unavailable"
          }
        },
        "security": [
          {
            "adminApiKey": []
          }
        ],
        "summary": "Withdraw unallocated contract funds",
        "tags": [
          "Admin"
        ]
      }
    },
    "/splits/{projectId}": {
      "get": {
        "description": "Fetches the current on-chain state for a single split project including collaborators and balances.",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Project"
                }
              }
            },
            "description": "Project details"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Get project details by ID",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/claim": {
      "post": {
        "description": "Builds an unsigned XDR allowing a collaborator to claim their allocated share from a project.",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "claimer": {
                    "description": "collaborator address performing the claim",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "claimer"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Claim collaborator payout",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/claimable/{collaborator}": {
      "get": {
        "description": "Returns the claimable, claimed, and total allocated amounts for a collaborator on a project.",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          },
          {
            "description": "Stellar address of the collaborator",
            "in": "path",
            "name": "collaborator",
            "required": true,
            "schema": {
              "description": "Stellar address of the collaborator",
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimableResponse"
                }
              }
            },
            "description": "Claimable payout information"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Get claimable payout information for a collaborator",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/collaborators": {
      "put": {
        "description": "Builds an unsigned XDR to replace the collaborator list and revenue share allocations. Fails validation if any address repeats or shares don't sum to 10,000 basis points; the frontend CreateSplitWizard performs the same duplicate/casing checks client-side, but this endpoint is the source of truth. Rejected with 401 UNAUTHORIZED when `owner` is not the on-chain project owner.",
        "parameters": [
          {
            "description": "Project ID",
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "description": "Project ID",
              "example": "afrobeats_001",
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "collaborators": [
                  {
                    "address": "GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV",
                    "alias": "Producer",
                    "basisPoints": 5000
                  },
                  {
                    "address": "GBG234UA6RBPDD5K6FHMQXHUXB5ALOENQGH24Y3W4ERX2YJNQ4MK4V25",
                    "alias": "Vocalist",
                    "basisPoints": 5000
                  }
                ],
                "owner": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
              },
              "schema": {
                "properties": {
                  "collaborators": {
                    "items": {
                      "properties": {
                        "address": {
                          "minLength": 1,
                          "type": "string"
                        },
                        "alias": {
                          "maxLength": 100,
                          "minLength": 1,
                          "type": "string"
                        },
                        "basisPoints": {
                          "exclusiveMinimum": true,
                          "maximum": 10000,
                          "minimum": 0,
                          "type": "integer"
                        }
                      },
                      "required": [
                        "address",
                        "alias",
                        "basisPoints"
                      ],
                      "type": "object"
                    },
                    "minItems": 2,
                    "type": "array"
                  },
                  "owner": {
                    "description": "owner",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "owner",
                  "collaborators"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "metadata": {
                    "contractId": "CAGR5U5IBEPFVJDZPZUXXNCPXAHNZ6TWVIUTI5RLRH3SZSU4O2VXDOPF",
                    "networkPassphrase": "Test SDF Network ; September 2015",
                    "operation": "update_collaborators",
                    "sourceAccount": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
                  },
                  "xdr": "AAAAAgAAAAC5tRUXpDqRcTvpvKF...(truncated unsigned transaction envelope)"
                },
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "details": {
                    "path": [
                      "collaborators"
                    ]
                  },
                  "error": "VALIDATION_ERROR",
                  "message": "duplicate collaborator address found",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "code": "UNAUTHORIZED",
                  "details": {
                    "remediation": {
                      "action": "Switch Wallet",
                      "message": "Only the project owner can perform this action."
                    }
                  },
                  "error": "unauthorized",
                  "message": "Caller is not the project owner",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Update project collaborators",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/deposit": {
      "post": {
        "description": "Builds an unsigned XDR to deposit tokens into a split project's escrow balance.",
        "parameters": [
          {
            "description": "Project ID",
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "description": "Project ID",
              "example": "afrobeats_001",
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "amount": 50000000,
                "from": "GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV"
              },
              "schema": {
                "properties": {
                  "amount": {
                    "description": "deposit amount in stroops",
                    "exclusiveMinimum": true,
                    "minimum": 0,
                    "type": "number"
                  },
                  "from": {
                    "description": "from",
                    "minLength": 1,
                    "type": "string"
                  },
                  "token": {
                    "description": "token",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "from",
                  "amount",
                  "token"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "metadata": {
                    "contractId": "CAGR5U5IBEPFVJDZPZUXXNCPXAHNZ6TWVIUTI5RLRH3SZSU4O2VXDOPF",
                    "networkPassphrase": "Test SDF Network ; September 2015",
                    "operation": "deposit",
                    "sourceAccount": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
                  },
                  "xdr": "AAAAAgAAAAC5tRUXpDqRcTvpvKF...(truncated unsigned transaction envelope)"
                },
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "details": {
                    "path": [
                      "amount"
                    ]
                  },
                  "error": "VALIDATION_ERROR",
                  "message": "amount must be greater than 0",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Deposit funds into a project",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/distribute": {
      "post": {
        "description": "Builds an unsigned XDR to distribute accumulated project funds according to collaborator shares.",
        "parameters": [
          {
            "description": "Project ID",
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "description": "Project ID",
              "example": "afrobeats_001",
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "sourceAddress": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
              },
              "schema": {
                "properties": {
                  "sourceAddress": {
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "metadata": {
                    "contractId": "CAGR5U5IBEPFVJDZPZUXXNCPXAHNZ6TWVIUTI5RLRH3SZSU4O2VXDOPF",
                    "networkPassphrase": "Test SDF Network ; September 2015",
                    "operation": "distribute",
                    "sourceAccount": "GBJRKIYXAAFD3NZCWJXGUTNKYUQFZC2ANS6LRMBPJCE4IZSMJJMZPQBT"
                  },
                  "xdr": "AAAAAgAAAAC5tRUXpDqRcTvpvKF...(truncated unsigned transaction envelope)"
                },
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "details": {
                    "path": [
                      "projectId"
                    ]
                  },
                  "error": "VALIDATION_ERROR",
                  "message": "Invalid projectId format.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Distribute project funds to collaborators",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/history": {
      "get": {
        "description": "Returns paginated on-chain distribution (`round`) and payout (`payment`) events for a project, newest first. Pass the previous response's `nextCursor` back as the `cursor` query parameter to page forward.",
        "parameters": [
          {
            "description": "Project ID",
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "description": "Project ID",
              "example": "afrobeats_001",
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "amount": "3000000",
                      "id": "0000012345678901234-0000000001",
                      "ledgerCloseTime": "1732012800",
                      "recipient": "GCZTK3PNYXCVF7Z3ELVELEJZ7BVGPGPVJ3NVZNI7O6DVCHPA4JU6LXRV",
                      "txHash": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc",
                      "type": "payment"
                    },
                    {
                      "amount": "5000000",
                      "id": "0000012345678901233-0000000001",
                      "ledgerCloseTime": "1732012700",
                      "round": 3,
                      "txHash": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8fc",
                      "type": "round"
                    }
                  ],
                  "nextCursor": "0000012345678901233-0000000001"
                },
                "schema": {
                  "properties": {
                    "items": {
                      "items": {
                        "nullable": true
                      },
                      "type": "array"
                    },
                    "nextCursor": {
                      "nullable": true,
                      "type": "string"
                    }
                  },
                  "required": [
                    "items",
                    "nextCursor"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "History items"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "details": {
                    "message": "Check cursor and limit parameters."
                  },
                  "error": "VALIDATION_ERROR",
                  "message": "Invalid query parameters.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Get project transaction history",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/lock": {
      "post": {
        "description": "Builds an unsigned XDR to permanently lock a project, preventing further metadata or collaborator changes. Rejected with 401 UNAUTHORIZED when `owner` is not the on-chain project owner.",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "owner": {
                    "description": "owner",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "owner"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "code": "UNAUTHORIZED",
                  "details": {
                    "remediation": {
                      "action": "Switch Wallet",
                      "message": "Only the project owner can perform this action."
                    }
                  },
                  "error": "unauthorized",
                  "message": "Caller is not the project owner",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Lock a project permanently",
        "tags": [
          "Splits"
        ]
      }
    },
    "/splits/{projectId}/metadata": {
      "patch": {
        "description": "Builds an unsigned XDR to update a project's title and project type. Text fields are server-side sanitized. Rejected with 401 UNAUTHORIZED when `owner` is not the on-chain project owner.",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "maxLength": 32,
              "minLength": 1,
              "pattern": "^[a-zA-Z0-9_]+$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "owner": {
                    "description": "owner",
                    "minLength": 1,
                    "type": "string"
                  },
                  "projectType": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "owner",
                  "title",
                  "projectType"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XdrResponse"
                }
              }
            },
            "description": "Unsigned transaction XDR"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "code": "UNAUTHORIZED",
                  "details": {
                    "remediation": {
                      "action": "Switch Wallet",
                      "message": "Only the project owner can perform this action."
                    }
                  },
                  "error": "unauthorized",
                  "message": "Caller is not the project owner",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          },
          "502": {
            "content": {
              "application/json": {
                "example": {
                  "error": "BAD_GATEWAY",
                  "message": "The Stellar network RPC call failed. Please retry.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Upstream RPC or contract error"
          }
        },
        "summary": "Update project metadata (title/category)",
        "tags": [
          "Splits"
        ]
      }
    },
    "/transactions/history": {
      "get": {
        "description": "Returns paginated payout records with optional wallet, date, and status filters.",
        "parameters": [
          {
            "in": "query",
            "name": "walletAddress",
            "required": false,
            "schema": {
              "pattern": "^G[A-Z2-7]{55}$",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "startDate",
            "required": false,
            "schema": {
              "exclusiveMinimum": true,
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "endDate",
            "required": false,
            "schema": {
              "exclusiveMinimum": true,
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "pending",
                "completed",
                "failed"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "total": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "transactions": {
                      "items": {
                        "properties": {
                          "amount": {
                            "type": "string"
                          },
                          "id": {
                            "type": "string"
                          },
                          "recipient": {
                            "type": "string"
                          },
                          "roundId": {
                            "type": "string"
                          },
                          "status": {
                            "enum": [
                              "pending",
                              "completed",
                              "failed"
                            ],
                            "type": "string"
                          },
                          "timestamp": {
                            "type": "integer"
                          },
                          "token": {
                            "type": "string"
                          },
                          "txHash": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "roundId",
                          "recipient",
                          "amount",
                          "token",
                          "timestamp",
                          "txHash",
                          "status"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "transactions",
                    "total",
                    "limit",
                    "offset"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Paginated transaction history"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Query payout transaction history",
        "tags": [
          "Transactions"
        ]
      }
    },
    "/transactions/receipt/{txHash}": {
      "get": {
        "description": "Returns receipt fields from the indexed payout and configured Stellar network.",
        "parameters": [
          {
            "in": "path",
            "name": "txHash",
            "required": true,
            "schema": {
              "pattern": "^[a-fA-F0-9]{64}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "amount": {
                      "type": "string"
                    },
                    "date": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "network": {
                      "type": "string"
                    },
                    "projectId": {
                      "type": "string"
                    },
                    "recipient": {
                      "type": "string"
                    },
                    "reference": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "completed",
                        "failed"
                      ],
                      "type": "string"
                    },
                    "token": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "reference",
                    "amount",
                    "token",
                    "date",
                    "network",
                    "status",
                    "recipient",
                    "projectId"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Transaction receipt"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Generate a transaction receipt",
        "tags": [
          "Transactions"
        ]
      }
    },
    "/transactions/recipient/{walletAddress}": {
      "get": {
        "description": "Returns all payout records sent to the given Stellar wallet address.",
        "parameters": [
          {
            "in": "path",
            "name": "walletAddress",
            "required": true,
            "schema": {
              "pattern": "^G[A-Z2-7]{55}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "transactions": {
                      "items": {
                        "properties": {
                          "amount": {
                            "type": "string"
                          },
                          "id": {
                            "type": "string"
                          },
                          "recipient": {
                            "type": "string"
                          },
                          "roundId": {
                            "type": "string"
                          },
                          "status": {
                            "enum": [
                              "pending",
                              "completed",
                              "failed"
                            ],
                            "type": "string"
                          },
                          "timestamp": {
                            "type": "integer"
                          },
                          "token": {
                            "type": "string"
                          },
                          "txHash": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "roundId",
                          "recipient",
                          "amount",
                          "token",
                          "timestamp",
                          "txHash",
                          "status"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "walletAddress": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "transactions",
                    "total",
                    "walletAddress"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Recipient transaction list"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "List transactions for a recipient",
        "tags": [
          "Transactions"
        ]
      }
    },
    "/transactions/{txHash}": {
      "get": {
        "description": "Returns a single payout record matching the Stellar transaction hash.",
        "parameters": [
          {
            "in": "path",
            "name": "txHash",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "amount": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "recipient": {
                      "type": "string"
                    },
                    "roundId": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "completed",
                        "failed"
                      ],
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "integer"
                    },
                    "token": {
                      "type": "string"
                    },
                    "txHash": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "roundId",
                    "recipient",
                    "amount",
                    "token",
                    "timestamp",
                    "txHash",
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Transaction record"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Get transaction by hash",
        "tags": [
          "Transactions"
        ]
      }
    },
    "/users/login": {
      "post": {
        "description": "Authenticates a registered user and returns a JWT bearer token.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "walletAddress": {
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "walletAddress"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "alias": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "id": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "role": {
                      "enum": [
                        "company",
                        "customer",
                        "driver"
                      ],
                      "type": "string"
                    },
                    "token": {
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    },
                    "walletAddress": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "walletAddress",
                    "role",
                    "isActive",
                    "createdAt",
                    "updatedAt",
                    "token"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Authenticated user with JWT"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Log in by wallet address",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/me": {
      "get": {
        "description": "Returns the profile of the user identified by the JWT bearer token.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "alias": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "id": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "role": {
                      "enum": [
                        "company",
                        "customer",
                        "driver"
                      ],
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    },
                    "walletAddress": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "walletAddress",
                    "role",
                    "isActive",
                    "createdAt",
                    "updatedAt"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Authenticated user profile"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get authenticated user profile",
        "tags": [
          "Users"
        ]
      },
      "patch": {
        "description": "Updates email or alias for the authenticated user.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "alias": {
                    "maxLength": 64,
                    "minLength": 1,
                    "type": "string"
                  },
                  "email": {
                    "format": "email",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "alias": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "id": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "role": {
                      "enum": [
                        "company",
                        "customer",
                        "driver"
                      ],
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    },
                    "walletAddress": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "walletAddress",
                    "role",
                    "isActive",
                    "createdAt",
                    "updatedAt"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Updated user profile"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "UNAUTHORIZED",
                  "message": "Missing or invalid bearer token / admin API key.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Authentication required"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update authenticated user profile",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/register": {
      "post": {
        "description": "Creates a user profile linked to a Stellar wallet address.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "alias": {
                    "maxLength": 64,
                    "minLength": 1,
                    "type": "string"
                  },
                  "email": {
                    "format": "email",
                    "type": "string"
                  },
                  "role": {
                    "default": "customer",
                    "enum": [
                      "company",
                      "customer",
                      "driver"
                    ],
                    "type": "string"
                  },
                  "walletAddress": {
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "walletAddress"
                ],
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "alias": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "id": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "role": {
                      "enum": [
                        "company",
                        "customer",
                        "driver"
                      ],
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    },
                    "walletAddress": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "walletAddress",
                    "role",
                    "isActive",
                    "createdAt",
                    "updatedAt"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Registered user profile"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "409": {
            "content": {
              "application/json": {
                "example": {
                  "error": "CONFLICT",
                  "message": "A project with ID \"afrobeats_001\" already exists.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Conflict with existing resource"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Register a new user",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{walletAddress}": {
      "get": {
        "description": "Looks up a public user profile by Stellar wallet address.",
        "parameters": [
          {
            "in": "path",
            "name": "walletAddress",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "alias": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "id": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "role": {
                      "enum": [
                        "company",
                        "customer",
                        "driver"
                      ],
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string"
                    },
                    "walletAddress": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "walletAddress",
                    "role",
                    "isActive",
                    "createdAt",
                    "updatedAt"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "User profile"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Validation error"
          },
          "404": {
            "content": {
              "application/json": {
                "example": {
                  "error": "NOT_FOUND",
                  "message": "Project afrobeats_001 does not exist.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Resource not found"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "INTERNAL_ERROR",
                  "message": "An unexpected error occurred. Please try again later.",
                  "requestId": "b6f1a2d4-8c3e-4a1b-9f2e-6d5c7a8b9c0d"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "summary": "Get user by wallet address",
        "tags": [
          "Users"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "http://localhost:3001"
    }
  ]
}