UNITS APIs for GFF

units_apis.yaml

openapi: 3.0.0
info:
  title: "Finternet UNITS API [Draft]"
  version: "1.0.0"
  description: "API for interacting with the UNITS platform for tokenization and workflow management, incorporating a standard telemetry wrapper for all requests and responses."
servers:
  - url: "https://api.finternet.units"
    description: "Main server"

security:
  - BearerAuth: []

paths:
  /api/draft/identity/create:
    post:   # properly indented under the path
      summary: "Create a new identity with associated account"
      description: "Creates a new digital identity and automatically creates an associated account. The account is linked to the identity and both are created in a single transaction. Requires JWT and signature."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdentityRequest'
      responses:
        '200':
          description: "Identity created successfully."
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseWrapper'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          identityId: { type: string }
                          accountId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/draft/token/search/{type}:
    get:
      summary: "Search tokens by type"
      description: "Retrieves a list of tokens filtered by their type. Requires JWT and signature."
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [LoanPool, Project, LoanAsset, Mortgage]
          description: "The type of tokens to search for"
      responses:
        '200':
          description: "List of tokens retrieved successfully"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseWrapper'
                  - type: object
                    properties:
                      result:
                        type: array
                        items:
                          type: object
                          properties:
                            tokenId: { type: string }
                            ownerAccountId: { type: string }
                            displayName: { type: string }
                            symbol: { type: string }
                            totalSupply: { type: number }
                            data:
                              type: object
                              properties:
                                poolName: { type: string }
                                assetIds:
                                  type: array
                                  items:
                                    type: string
                                decimals: { type: integer }
                                metadata: { type: string }
                        example:
                          - tokenId: "token_123"
                            ownerAccountId: "acc_originator_123"
                            displayName: "Q3 2024 Retail Asset Pool"
                            symbol: "QRAP24"
                            totalSupply: 1
                            data:
                              poolName: "Q3 Retail Asset Pool"
                              assetIds: ["loan_abc", "loan_def"]
                              decimals: 20
                              metadata: "Personal Loans"
                          - tokenId: "token_456"
                            ownerAccountId: "acc_originator_123"
                            displayName: "Q4 2024 Retail Asset Pool"
                            symbol: "QRAP24Q4"
                            totalSupply: 1
                            data:
                              poolName: "Q4 Retail Asset Pool"
                              assetIds: ["loan_xyz", "loan_uvw"]
                              decimals: 20
                              metadata: "Personal Loans"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/draft/token/types:
    get:
      summary: "List all available token types"
      description: "Retrieves a list of all token types that can be created or searched for. Requires JWT and signature."
      responses:
        '200':
          description: "A list of token types."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTokenTypesResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/draft/token/types/{type}:
    get:
      summary: "Get token type metadata"
      description: "Retrieves the detailed schema and metadata for a specific token type. Requires JWT and signature."
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [LoanPool, Project, LoanAsset, Mortgage]
      responses:
        '200':
          description: "Successful response with the requested token type schema."
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LoanPoolSchema'
                  - $ref: '#/components/schemas/ProjectSchema'
                  - $ref: '#/components/schemas/LoanAssetSchema'
                  - $ref: '#/components/schemas/MortgageSchema'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/draft/token/create:
    post:
      summary: "Create a new token (Asynchronous)"
      description: "Submits a request to create a new token. Requires JWT and signature."
      parameters:
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
          description: "Signature of the request payload, signed by the user's private key."
        - name: X-Identity-Id
          in: header
          required: true
          schema:
            type: string
          description: "The unique identifier of the requesting identity"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenRequest'
      responses:
        '202':
          description: "Request accepted for processing."
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseWrapper'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          token_id: { type: string }
                          transaction_id: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/draft/token/transact:
    post:
      summary: "Perform a state-changing operation on a token (Asynchronous)"
      description: "Submits a transaction to attest, lock, unlock, or transfer a token. Requires JWT and signature."
      parameters:
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
          description: "Signature of the request payload, signed by the user's private key."
        - name: X-Identity-Id
          in: header
          required: true
          schema:
            type: string
          description: "The unique identifier of the requesting identity"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RequestWrapper'
                - type: object
                  properties:
                    request:
                      type: object
                      required: [tokenId, operation]
                      properties:
                        tokenId: { type: string }
                        operation: { type: string, enum: [attest, lock, unlock, transfer] }
                        data: { type: object }
      responses:
        '202':
          description: "Request accepted for processing."
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseWrapper'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          transaction_id: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/draft/token/{token_id}:
    get:
      summary: "Get token details"
      description: "Retrieves detailed information about a specific token. Requires JWT and signature."
      parameters:
        - name: token_id
          in: path
          required: true
          schema:
            type: string
          description: "The unique identifier of the token"
      responses:
        '200':
          description: "Token details retrieved successfully"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseWrapper'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          tokenType: { type: string }
                          ownerAccountId: { type: string }
                          displayName: { type: string }
                          symbol: { type: string }
                          totalSupply: { type: number }
                          data:
                            type: object
                            properties:
                              poolName: { type: string }
                              assetIds:
                                type: array
                                items:
                                  type: string
                              decimals: { type: integer }
                              metadata: { type: string }
                        example:
                          tokenType: "LOAN_POOL"
                          ownerAccountId: "acc_originator_123"
                          displayName: "Q3 2024 Retail Asset Pool"
                          symbol: "QRAP24"
                          totalSupply: 1
                          data:
                            poolName: "Q3 Retail Asset Pool"
                            assetIds: ["loan_abc", "loan_def"]
                            decimals: 20
                            metadata: "Personal Loans"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/draft/transaction/status/{transaction_id}:
    get:
      summary: "Get the status of an asynchronous operation"
      description: "Polls this endpoint to check the completion status of a job. Requires JWT and signature."
      parameters:
        - name: transaction_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Status of the job."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/draft/transaction/verify/{proof_transaction_id}:
    get:
      summary: "Get the status of a ZK proof"
      description: "Polls this endpoint to check the status of proof generation. Requires JWT and signature."
      parameters:
        - name: proof_transaction_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Status of the proof generation job."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    # Telemetry Wrappers
    RequestWrapper:
      type: object
      properties:
        id: { type: string }
        ver: { type: string, example: "v1" }
        ts: { type: string, format: "date-time" }
        params:
          type: object
          properties:
            msgid: { type: string, format: "uuid" }
    ResponseWrapper:
      type: object
      properties:
        id: { type: string }
        ver: { type: string, example: "v1" }
        ts: { type: string, format: "date-time" }
        params:
          type: object
          properties:
            status: { type: string, enum: [SUCCESS, FAILED] }
            msgid: { type: string, format: "uuid" }
            resmsgid: { type: string, format: "uuid" }
        responseCode: { type: string, enum: [OK, ERROR] }

    # Request & Response Payloads
    CreateIdentityRequest:
      allOf:
        - $ref: '#/components/schemas/RequestWrapper'
        - type: object
          properties:
            request:
              type: object
              required: [universalIdentifier, legalName, publicKey, contactInfo, account, name, accountType]
              properties:
                universalIdentifier: { type: string }
                legalName: { type: string }
                nationality: { type: string }
                publicKey: { type: string }
                contactInfo:
                  type: object
                  properties:
                    email: { type: string, format: "email" }
                    phoneNumber: { type: string }
                account:
                  $ref: '#/components/schemas/AccountInput'
              example:
                universalIdentifier: "uns:originator-hdfc.x"
                legalName: "HDFC Bank"
                nationality: "IN"
                publicKey: "0x04..."
                contactInfo:
                  email: "contact@hdfc.com"
                  phoneNumber: "+912261606161"
                account:
                  name: "HDFC Securitization Account"
                  accountType: "Business"
    AsyncResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              type: object
              properties:
                transaction_id: { type: string }
    IdentityStatusResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              type: object
              properties:
                status: { type: string, enum: [pending, completed, failed] }
                identityId: { type: string }
                accountId: { type: string }
                account: { $ref: '#/components/schemas/Account' }
    CreateAccountRequest:
      allOf:
        - $ref: '#/components/schemas/RequestWrapper'
        - type: object
          properties:
            request:
              $ref: '#/components/schemas/AccountInput'
    CreateAccountResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/Account'
    ListTokenTypesResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              type: object
              properties:
                tokenTypes:
                  type: array
                  items:
                    type: string
                  example: ["LOAN_POOL", "PROJECT", "MORTGAGE", "LOAN_ASSET"]
    CreateTokenRequest:
      allOf:
        - $ref: '#/components/schemas/RequestWrapper'
        - type: object
          properties:
            request:
              $ref: '#/components/schemas/TokenInput'
    TransactTokenRequest:
      allOf:
        - $ref: '#/components/schemas/RequestWrapper'
        - type: object
          properties:
            request:
              $ref: '#/components/schemas/TransactionInput'
    UpdateTokenRequest:
      allOf:
        - $ref: '#/components/schemas/RequestWrapper'
        - type: object
          properties:
            request:
              type: object
              properties:
                tokenId: { type: string }
                operation: { type: string, enum: [attest, approve, repay] }
                data: { type: object }
    UpdateTokenResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/Token'
    TransactionStatusResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/Transaction'
    GenerateProofRequest:
      allOf:
        - $ref: '#/components/schemas/RequestWrapper'
        - type: object
          properties:
            request:
              type: object
              properties:
                source_transaction_id: { type: string }
    ProofStatusResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseWrapper'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/ProofStatus'

    # Core Schemas
    UserInput:
      type: object
      properties:
        universalIdentifier: { type: string }
        legalName: { type: string }
        nationality: { type: string }
        publicKey: { type: string }
        contactInfo:
          type: object
          properties:
            email: { type: string, format: "email" }
            phoneNumber: { type: string }
      required: [universalIdentifier, legalName, publicKey]
      example:
        universalIdentifier: "uns:originator-hdfc.x"
        legalName: "HDFC Bank"
        nationality: "IN"
        publicKey: "0x04..."
        contactInfo:
          email: "contact@hdfc.com"
          phoneNumber: "+912261606161"

    AccountInput:
      type: object
      properties:
        ownerId: { type: string }
        name: { type: string }
        accountType: { type: string, enum: [Personal, Business, Escrow, Custodial, SmartContract] }
      required: [ownerId, name, accountType]
      example:
        ownerId: "uns:originator-hdfc.x"
        name: "HDFC Securitization Account"
        accountType: "Business"

    Account:
      type: object
      properties:
        accountId: { type: string }
        ownerId: { type: string }
        name: { type: string }
        accountType: { type: string }
        creationDate: { type: string, format: "date-time" }

    TokenInput:
      type: object
      properties:
        tokenType: { type: string }
        ownerAccountId: { type: string }
        displayName: { type: string }
        symbol: { type: string }
        totalSupply: { type: number }
        data: { type: object }
      required: [tokenType, ownerAccountId, displayName, symbol]
      example:
        tokenType: "LOAN_POOL"
        ownerAccountId: "acc_originator_123"
        displayName: "Q3 2024 Retail Asset Pool"
        symbol: "QRAP24"
        totalSupply: 1
        data:
          poolName: "Q3 Retail Asset Pool"
          assetIds: ["loan_abc", "loan_def"]
          totalValue: 2500000
          assetType: "Personal Loans"

    TransactionInput:
      type: object
      properties:
        tokenId: { type: string }
        operation: { type: string, enum: [lock, unlock, transfer] }
        params: { type: object }
      required: [tokenId, operation]
      example:
        tokenId: "token_pool_123"
        operation: "transfer"
        params: { "destinationAccountId": "acc_investor_456", "quantity": 1 }

    Token:
      type: object
      properties:
        tokenId: { type: string }
        tokenType: { type: string }
        issuingTokenManagerId: { type: string }
        ownerAccountId: { type: string }
        totalSupply: { type: number }
        decimals: { type: integer }
        displayName: { type: string }
        symbol: { type: string }
        underlyingAssetReference: { type: string }
        data: { type: object }
        flagsAndConstraints:
          type: object
          properties:
            isTransferable: { type: boolean }
            isLockingAllowed: { type: boolean }
            isBurnable: { type: boolean }
            isFractionable: { type: boolean }
            isKYCMandatory: { type: boolean }
            requiresAttestation: { type: boolean }
            requiresApproval: { type: boolean }
        attestations:
          type: array
          items:
            type: object
            properties:
              providerId: { type: string }
              attestationType: { type: string }
              attestationHash: { type: string }
              timestamp: { type: string, format: "date-time" }

    Transaction:
      type: object
      properties:
        transactionId: { type: string }
        timestamp: { type: string, format: "date-time" }
        initiatorId: { type: string }
        actionType: { type: string }
        affectedTokens:
          type: array
          items:
            type: object
            properties:
              tokenId: { type: string }
              quantity: { type: number }
        sourceAccountId: { type: string }
        destinationAccountId: { type: string }
        proofReference: { type: string }
        status: { type: string, enum: [Pending, Confirmed, Failed, Reverted] }
        details: { type: object }
      required: [transactionId, timestamp, initiatorId, actionType, status]

    ProofStatus:
      type: object
      properties:
        status: { type: string, enum: [pending, generating, publishing, completed, failed] }
        proofData: { type: object }
        onChainTxHash: { type: string }
        error: { type: string }

    # Token Type Schemas
    LoanPoolSchema:
      type: object
      properties:
        schemaType: { type: string, example: "LoanPool" }
        description: { type: string, example: "Represents a securitized pool of individual loan assets." }
        requiredFields: { type: array, items: { type: string }, example: ["poolName", "assetIds", "totalValue"] }

    ProjectSchema:
      type: object
      properties:
        schemaType: { type: string, example: "Project" }
        description: { type: string, example: "Represents a real estate project seeking approved financing." }
        requiredFields: { type: array, items: { type: string }, example: ["projectName", "location", "RERA_ID"] }

    LoanAssetSchema:
      type: object
      properties:
        schemaType: { type: string, example: "LoanAsset" }
        description: { type: string, example: "Represents a single, tokenized loan agreement." }
        requiredFields: { type: array, items: { type: string }, example: ["loanId", "principal", "interestRate"] }

    MortgageSchema:
      type: object
      properties:
        schemaType: { type: string, example: "Mortgage" }
        description: { type: string, example: "Represents a mortgage lien against a property token." }
        requiredFields: { type: array, items: { type: string }, example: ["propertyTokenId", "lenderId", "lienAmount"] }

    Error:
      type: object
      properties:
        code: { type: string }
        message: { type: string }

  responses:
    BadRequest:
      description: "Bad Request"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: "Unauthorized"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: "Not Found"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: "Internal Server Error"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'