openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "StellarSettle API",
    "version": "1.0.0",
    "description": "API specification for StellarSettle backend including Soroban contract interactions."
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local development server"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "EscrowStatusResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "escrowed"
          },
          "contractId": {
            "type": "string",
            "description": "The Soroban contract ID managing the escrow",
            "example": "CA3D..."
          },
          "transactionXdr": {
            "type": "string",
            "description": "The base64 encoded transaction XDR",
            "example": "AAAA..."
          }
        },
        "required": ["status", "contractId"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "BatchPublishRequest": {
        "type": "object",
        "required": ["invoiceIds"],
        "properties": {
          "invoiceIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Ids of the draft invoices to publish."
          }
        }
      },
      "BatchPublishResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "properties": {
              "published": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "description": "The invoices that were published."
              },
              "count": {
                "type": "integer",
                "example": 3
              }
            }
          }
        }
      },
      "RevokeKYCRequest": {
        "type": "object",
        "required": ["userId", "reviewerId"],
        "properties": {
          "userId": {
            "type": "string",
            "description": "User whose approval is being withdrawn."
          },
          "reviewerId": {
            "type": "string",
            "description": "Admin performing the revocation."
          },
          "revocationReason": {
            "type": "string",
            "description": "Recorded in the KYC audit log."
          }
        }
      },
      "BuyLimitResponse": {
        "type": "object",
        "properties": {
          "keyId": {
            "type": "string"
          },
          "maxBuyPerTx": {
            "type": "string",
            "description": "Maximum amount purchasable in a single buy transaction, in base units"
          },
          "maxBuyPerDay": {
            "type": "string",
            "description": "Maximum amount purchasable per wallet per day, in base units"
          },
          "currentSupply": {
            "type": "string",
            "description": "Current key supply, in base units"
          },
          "curveType": {
            "type": "string"
          },
          "configVersion": {
            "type": "integer"
          },
          "isActive": {
            "type": "boolean"
          },
          "contractAddress": {
            "type": "string"
          },
          "cachedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreatorKeyDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BuyLimitResponse"
          },
          {
            "type": "object",
            "properties": {
              "creatorId": {
                "type": "string"
              },
              "creatorWallet": {
                "type": "string"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "CurveMigration": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "migrationId": {
            "type": "string",
            "description": "On-chain proposal id"
          },
          "keyId": {
            "type": "string"
          },
          "proposalId": {
            "type": "string"
          },
          "contractAddress": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "executed", "expired"]
          },
          "proposedParams": {
            "type": "object",
            "additionalProperties": true
          },
          "appliedParams": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "timelockExpiry": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timelockExpired": {
            "type": "boolean"
          },
          "executable": {
            "type": "boolean"
          },
          "proposedAt": {
            "type": "string",
            "format": "date-time"
          },
          "executedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "proposalTxHash": {
            "type": "string",
            "nullable": true
          },
          "executionTxHash": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "CurveMigrationList": {
        "type": "object",
        "properties": {
          "pending": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CurveMigration"
            }
          },
          "executed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CurveMigration"
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CurveMigration"
            }
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "AclEntry": {
        "type": "object",
        "properties": {
          "contractAddress": {
            "type": "string"
          },
          "permittedFunctions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "enum": ["active", "removed"]
          },
          "addedAt": {
            "type": "string",
            "format": "date-time"
          },
          "removedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastLedger": {
            "type": "string",
            "nullable": true
          },
          "lastTxHash": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AclLogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "contractAddress": {
            "type": "string"
          },
          "action": {
            "type": "string",
            "enum": ["add", "remove"]
          },
          "permittedFunctions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ledgerSequence": {
            "type": "string",
            "nullable": true
          },
          "txHash": {
            "type": "string",
            "nullable": true
          },
          "actor": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AtomicSwap": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "swapId": {
            "type": "string",
            "description": "On-chain swap id"
          },
          "buyer": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string"
              },
              "invoiceId": {
                "type": "string",
                "nullable": true
              },
              "amount": {
                "type": "string"
              }
            }
          },
          "seller": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string"
              },
              "invoiceId": {
                "type": "string",
                "nullable": true
              },
              "amount": {
                "type": "string"
              }
            }
          },
          "fee": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "string"
              },
              "recipient": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "feeAmount": {
            "type": "string"
          },
          "txHash": {
            "type": "string",
            "nullable": true
          },
          "ledgerSequence": {
            "type": "string",
            "nullable": true
          },
          "executedAt": {
            "type": "string",
            "format": "date-time"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RoyaltyTransfer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "keyAddress": {
            "type": "string",
            "description": "Creator key contract that split the royalty."
          },
          "buyerWallet": {
            "type": "string",
            "nullable": true,
            "description": "Buyer that paid the transfer, when the event carried it."
          },
          "amount": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Royalty amount credited in token units."
          },
          "txHash": {
            "type": "string",
            "nullable": true,
            "description": "Transaction that paid the royalty."
          },
          "ledgerSequence": {
            "type": "string",
            "nullable": true,
            "description": "Ledger the royalty was paid in."
          },
          "paidAt": {
            "type": "string",
            "nullable": true,
            "description": "RFC 3339 payment time."
          }
        },
        "required": ["id", "keyAddress", "amount"]
      },
      "RoyaltyClaim": {
        "type": "object",
        "properties": {
          "claimId": {
            "type": "string",
            "description": "On-chain claim identifier."
          },
          "keyAddress": {
            "type": "string",
            "nullable": true,
            "description": "Creator key the royalty was accrued under."
          },
          "amount": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Royalty amount claimed."
          },
          "txHash": {
            "type": "string",
            "nullable": true,
            "description": "Transaction that claimed the royalty."
          },
          "ledgerSequence": {
            "type": "string",
            "nullable": true,
            "description": "Ledger the claim settled in."
          },
          "claimedAt": {
            "type": "string",
            "nullable": true,
            "description": "RFC 3339 claim time."
          }
        },
        "required": ["claimId", "amount"]
      },
      "RoyaltyEarnings": {
        "type": "object",
        "properties": {
          "creatorWallet": {
            "type": "string"
          },
          "totalEarned": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Lifetime royalty accruals."
          },
          "totalClaimed": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Lifetime royalties claimed."
          },
          "pending": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "totalEarned - totalClaimed, floored at zero."
          },
          "transferCount": {
            "type": "integer"
          },
          "claimCount": {
            "type": "integer"
          },
          "transfers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RoyaltyTransfer"
            }
          },
          "computedAt": {
            "type": "string",
            "description": "RFC 3339 computation time."
          }
        },
        "required": [
          "creatorWallet",
          "totalEarned",
          "totalClaimed",
          "pending",
          "transfers",
          "computedAt"
        ]
      },
      "DividendCycleClaimable": {
        "type": "object",
        "properties": {
          "cycleId": {
            "type": "string"
          },
          "cycleFrequency": {
            "type": "string",
            "nullable": true,
            "description": "Configured distribution frequency for the cycle."
          },
          "distributedAt": {
            "type": "string",
            "nullable": true,
            "description": "RFC 3339 distribution time."
          },
          "txHash": {
            "type": "string",
            "nullable": true,
            "description": "Transaction that distributed the cycle."
          },
          "earned": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Amount allocated to the wallet for the cycle."
          },
          "claimed": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Amount of the allocation already claimed."
          },
          "claimable": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "earned - claimed, floored at zero."
          }
        },
        "required": ["cycleId", "earned", "claimed", "claimable"]
      },
      "DividendClaimable": {
        "type": "object",
        "properties": {
          "wallet": {
            "type": "string"
          },
          "cycles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DividendCycleClaimable"
            }
          },
          "totalEarned": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Sum of every cycle's allocation."
          },
          "totalClaimed": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Sum of every claim by the wallet."
          },
          "totalClaimable": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "totalEarned - totalClaimed, floored at zero."
          },
          "computedAt": {
            "type": "string",
            "description": "RFC 3339 computation time."
          }
        },
        "required": [
          "wallet",
          "cycles",
          "totalEarned",
          "totalClaimed",
          "totalClaimable",
          "computedAt"
        ]
      },
      "DividendClaim": {
        "type": "object",
        "properties": {
          "claimId": {
            "type": "string",
            "description": "On-chain claim identifier."
          },
          "distributionId": {
            "type": "string",
            "nullable": true,
            "description": "Distribution cycle the claim came from."
          },
          "issuerWallet": {
            "type": "string",
            "nullable": true,
            "description": "Issuer that distributed the cycle."
          },
          "cycleFrequency": {
            "type": "string",
            "nullable": true,
            "description": "Configured distribution frequency for the cycle."
          },
          "amount": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Amount claimed."
          },
          "txHash": {
            "type": "string",
            "nullable": true,
            "description": "Transaction that claimed the dividend."
          },
          "ledgerSequence": {
            "type": "string",
            "nullable": true,
            "description": "Ledger the claim settled in."
          },
          "claimedAt": {
            "type": "string",
            "nullable": true,
            "description": "RFC 3339 claim time."
          }
        },
        "required": ["claimId", "amount"]
      },
      "DividendSummary": {
        "type": "object",
        "properties": {
          "wallet": {
            "type": "string"
          },
          "totalEarned": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Lifetime dividend allocations."
          },
          "totalClaimed": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Lifetime dividends claimed."
          },
          "totalPending": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "totalEarned - totalClaimed, floored at zero."
          },
          "cycleCount": {
            "type": "integer",
            "description": "Number of cycles the wallet was allocated in."
          },
          "computedAt": {
            "type": "string",
            "description": "RFC 3339 computation time."
          }
        },
        "required": [
          "wallet",
          "totalEarned",
          "totalClaimed",
          "totalPending",
          "cycleCount",
          "computedAt"
        ]
      },
      "SubscriptionStatus": {
        "type": "object",
        "properties": {
          "wallet": {
            "type": "string"
          },
          "keyId": {
            "type": "string",
            "description": "Contract id or key identifier the status was checked against."
          },
          "subscribed": {
            "type": "boolean",
            "description": "True when the balance meets the minimum and has not expired."
          },
          "balance": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Current on-chain key balance."
          },
          "minBalance": {
            "type": "string",
            "pattern": "^\\d+(\\.\\d{1,4})?$",
            "description": "Minimum balance required for access."
          },
          "expiryLedger": {
            "type": "integer",
            "nullable": true,
            "description": "Ledger the current subscription lapses after."
          },
          "daysRemaining": {
            "type": "integer",
            "minimum": 0,
            "description": "Whole days until expiry; 0 once expired."
          },
          "ledger": {
            "type": "integer",
            "description": "Ledger the answer was read at."
          },
          "checkedAt": {
            "type": "string",
            "description": "RFC 3339 check time."
          }
        },
        "required": [
          "wallet",
          "keyId",
          "subscribed",
          "balance",
          "minBalance",
          "daysRemaining",
          "ledger",
          "checkedAt"
        ]
      },
      "OnboardingStatus": {
        "type": "object",
        "properties": {
          "wallet": {
            "type": "string"
          },
          "tourCompleted": {
            "type": "boolean"
          },
          "completedAt": {
            "type": "string",
            "nullable": true,
            "description": "RFC 3339 completion time, preserved across repeat calls."
          },
          "updatedAt": {
            "type": "string",
            "nullable": true,
            "description": "RFC 3339 time of the last write."
          }
        },
        "required": ["wallet", "tourCompleted"]
      }
    }
  },
  "paths": {
    "/api/v1/admin": {
      "description": "Administrative routes are defined under this prefix."
    },
    "/api/v1/admin/acl": {
      "get": {
        "summary": "Get the contract integration ACL",
        "description": "Returns the whitelisted contract integrations and the functions each may call, projected from ACLUpdated contract events. Cached for five minutes and invalidated whenever a new ACLUpdated event is indexed. Admin only.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "contracts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/AclEntry"
                          }
                        },
                        "total": {
                          "type": "integer"
                        },
                        "cachedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "Admin access required": {
            "description": "Admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Authentication required": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/acl/log": {
      "get": {
        "summary": "Get the ACL add/remove history",
        "description": "Returns the append-only audit trail of ACL changes derived from ACLUpdated events, newest first. Admin only.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AclLogEntry"
                      }
                    }
                  }
                }
              }
            }
          },
          "Admin access required": {
            "description": "Admin access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Authentication required": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Bad Request": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/revoke-kyc": {
      "post": {
        "summary": "Revoke a user's KYC approval",
        "description": "Withdraws a previously granted KYC approval, returning the user to the pending state so they can be reviewed again. Only an approved user can be revoked. Requires the admin API key and an allow-listed source IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RevokeKYCRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "KYC revoked"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "User is not currently approved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dividends/claimable": {
      "get": {
        "summary": "Claimable dividends per cycle",
        "description": "Claimable dividend amounts per distribution cycle for the authenticated holder wallet, derived from synced DividendDistributed / DividendClaimed events. Cached for 30 seconds and invalidated by dividend events.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DividendClaimable"
                    }
                  },
                  "required": ["success", "data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dividends/claims": {
      "get": {
        "summary": "Dividend claim history",
        "description": "Dividends the authenticated holder wallet has claimed, newest first, with amounts and the on-chain transaction that paid them. Cursor paginated.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size (1-100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from the previous page's meta.nextCursor.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "success": {
                    "type": "boolean"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/DividendClaim"
                    }
                  },
                  "meta": {
                    "type": "object",
                    "properties": {
                      "hasMore": {
                        "type": "boolean"
                      },
                      "nextCursor": {
                        "type": "string",
                        "nullable": true,
                        "description": "Opaque cursor for the next page."
                      },
                      "limit": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dividends/summary": {
      "get": {
        "summary": "Dividend totals across every cycle",
        "description": "Lifetime earned, claimed and pending dividend totals for the authenticated holder wallet, aggregated across every distribution cycle the wallet was allocated in.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DividendSummary"
                    }
                  },
                  "required": ["success", "data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/investors": {
      "post": {
        "summary": "Acknowledge investor accreditation terms",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Acknowledge investor accreditation terms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "get": {
        "summary": "List the authenticated investor's portfolios and payouts",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List the authenticated investor's portfolios and payouts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/investors/acknowledge": {
      "post": {
        "summary": "Acknowledge investor accreditation terms",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Acknowledge investor accreditation terms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/investors/acknowledgement-status": {
      "get": {
        "summary": "Read the accreditation acknowledgement status",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Read the accreditation acknowledgement status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/investors/payouts/export/csv": {
      "get": {
        "summary": "Export the investor's payout history as CSV",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "CSV export",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/investors/payouts/history": {
      "get": {
        "summary": "List the investor's payout history",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List the investor's payout history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/investors/risk-profile": {
      "post": {
        "summary": "Create the investor's risk profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Risk profile created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "get": {
        "summary": "Read the investor's risk profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Risk profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "delete": {
        "summary": "Delete the investor's risk profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/invoices/batch-publish": {
      "post": {
        "summary": "Batch publish draft invoices",
        "description": "Publishes several of the authenticated seller's draft invoices to the marketplace in a single atomic transaction. Every invoice is validated first; if any one of them cannot be published the whole batch is rejected and no invoice changes state. The 400 response lists every rejected invoice and why.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchPublishRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "All invoices published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchPublishResponse"
                }
              }
            }
          },
          "400": {
            "description": "Batch rejected; no invoice was changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "KYC approval required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/invoices/{id}/escrow-status": {
      "get": {
        "summary": "Get Soroban Escrow Status",
        "description": "Retrieves the on-chain escrow status for a specific invoice via Soroban smart contracts.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EscrowStatusResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/{id}": {
      "get": {
        "summary": "Get creator key detail",
        "description": "Returns the creator key configuration, including the per-transaction buy limit. Public read; the limit is enforced on-chain.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Creator key id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CreatorKeyDetail"
                    }
                  }
                }
              }
            }
          },
          "Creator key not found": {
            "description": "Creator key not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Bad Request": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/{id}/buy-limit": {
      "get": {
        "summary": "Get per-transaction buy limit for a creator key",
        "description": "Pre-trade check: returns the per-transaction buy cap (max_buy_per_tx) and the current key supply so the frontend can clamp the buy input before submitting a transaction. Public read, cached for 60 seconds and invalidated when a key configuration update event is indexed.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Creator key id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/BuyLimitResponse"
                    }
                  }
                }
              }
            }
          },
          "Creator key not found": {
            "description": "Creator key not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Bad Request": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/keys/{id}/curve-migrations": {
      "get": {
        "summary": "List bonding curve migrations for a creator key",
        "description": "Returns the migration proposals indexed from CurveMigrationProposed / CurveMigrationExecuted events, each with the proposed parameters, timelock expiry and status. Executed migrations are visible to any authenticated user; migrations still behind the timelock are creator-only.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Creator key id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status; `pending` requires creator access",
            "schema": {
              "type": "string",
              "enum": ["all", "pending", "executed"],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CurveMigrationList"
                    }
                  }
                }
              }
            }
          },
          "Creator access required": {
            "description": "Creator access required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Authentication required": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Bad Request": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/kyc/submit": {
      "post": {
        "summary": "Submit KYC verification",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Verification submitted"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/kyc/webhook": {
      "post": {
        "summary": "Process a KYC provider webhook",
        "description": "Updates verification and user KYC state after validating the provider HMAC signature.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Webhook processed"
          },
          "401": {
            "description": "Invalid webhook signature"
          }
        }
      }
    },
    "/api/v1/marketplace": {
      "get": {
        "summary": "List invoices available on the secondary marketplace",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List invoices available on the secondary marketplace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/marketplace/invoices": {
      "get": {
        "summary": "List invoices available on the secondary marketplace",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List invoices available on the secondary marketplace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/onboarding/complete": {
      "post": {
        "summary": "Record onboarding tour completion",
        "description": "Records that the authenticated wallet finished the onboarding tour. Idempotent: re-completing keeps the original completedAt timestamp.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/OnboardingStatus"
                    }
                  },
                  "required": ["success", "data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/onboarding/status": {
      "get": {
        "summary": "Onboarding tour status",
        "description": "Whether the authenticated wallet has completed the onboarding tour, and when. Called on every app load, so it is a single indexed row lookup.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/OnboardingStatus"
                    }
                  },
                  "required": ["success", "data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/portfolio": {
      "get": {
        "summary": "Read the authenticated investor's portfolio",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Read the authenticated investor's portfolio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/royalties/earnings": {
      "get": {
        "summary": "Creator royalty earnings",
        "description": "Lifetime royalty accruals, claims and the outstanding balance for the authenticated creator, with a per-transfer breakdown. Creator-only (seller or both) and scoped to the token's wallet. Figures are cached for 30 seconds and invalidated by royalty events.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transfer_limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of royalty transfers to return (1-200).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RoyaltyEarnings"
                    }
                  },
                  "required": ["success", "data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The authenticated wallet is not a creator",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/royalties/history": {
      "get": {
        "summary": "Creator royalty claim history",
        "description": "Royalties the authenticated creator has claimed, newest first, with the on-chain transaction that paid them. Cursor paginated and creator-only.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size (1-100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from the previous page's meta.nextCursor.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "success": {
                    "type": "boolean"
                  },
                  "data": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/RoyaltyClaim"
                    }
                  },
                  "meta": {
                    "type": "object",
                    "properties": {
                      "hasMore": {
                        "type": "boolean"
                      },
                      "nextCursor": {
                        "type": "string",
                        "nullable": true,
                        "description": "Opaque cursor for the next page."
                      },
                      "limit": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The authenticated wallet is not a creator",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/seller": {
      "get": {
        "summary": "Read the authenticated seller's dashboard",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Read the authenticated seller's dashboard",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/seller/dashboard": {
      "get": {
        "summary": "Read the authenticated seller's dashboard",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Read the authenticated seller's dashboard",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/subscriptions/status": {
      "get": {
        "summary": "Gated-content subscription status",
        "description": "Whether a wallet holds the minimum key balance required to access gated content, with the expiry ledger and whole days remaining. Public by design: a content gate has to answer before the visitor is known to the platform, and the response only reflects public on-chain holdings. Cached for 30 seconds and evicted when a holding-change event is observed.",
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "required": false,
            "description": "Stellar account (strkey) public key to check.",
            "schema": {
              "type": "string",
              "pattern": "^G[A-Z2-7]{55}$"
            }
          },
          {
            "name": "key_id",
            "in": "query",
            "required": false,
            "description": "Soroban contract id, or the key identifier the contract uses.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SubscriptionStatus"
                    }
                  },
                  "required": ["success", "data"]
                }
              }
            }
          },
          "400": {
            "description": "'wallet' is missing or malformed, or 'key_id' is missing or malformed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/swaps/history": {
      "get": {
        "summary": "List atomic swaps for the authenticated wallet",
        "description": "Returns every atomic swap where the authenticated wallet is either the buyer or the seller, keyset-paginated on (executed_at, id).",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from the previous page's meta.nextCursor",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AtomicSwap"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        },
                        "nextCursor": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "Authentication required": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Bad Request": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/swaps/{id}": {
      "get": {
        "summary": "Get a single atomic swap",
        "description": "Public lookup of one atomic swap by its id or on-chain swap id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Swap id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AtomicSwap"
                    }
                  }
                }
              }
            }
          },
          "Swap not found": {
            "description": "Swap not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "Bad Request": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/watchlist": {
      "get": {
        "summary": "List the authenticated user's watchlist",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Watchlist",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "post": {
        "summary": "Add an invoice to the watchlist",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/v1/watchlist/{invoiceId}": {
      "post": {
        "summary": "Add an invoice to the watchlist",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "delete": {
        "summary": "Remove an invoice from the watchlist",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/ready": {
      "get": {
        "summary": "Readiness probe",
        "responses": {
          "200": {
            "description": "Service is ready",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Service is not ready",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}