specification.yaml

swagger: "2.0"
info:
  description: "This is an API for interacting with Liquid Securities.\n\nExamples of how to authenticate and call the API programmatically using Python and nodejs can be obtained by request.\n\nThe version of this specification should not be confused with the version of the API itself, which can be discovered using the /info path."
  version: "1.0.2"
  title: "Liquid Securities"
  contact:
    email: "liquid-securities-support@blockstream.com"
host: "securities.blockstream.com"
basePath: "/api"
tags:
- name: "general"
  description: "General API operations"
- name: "user"
  description: "Operations about user and user information"
- name: "investors"
  description: "Operations about investors"
- name: "assets"
  description: "Operations about assets"
schemes:
- "https"
paths:
  /info:
    get:
      tags:
      - "general"
      summary: "Gets information about the API. Token authentication is not required by this endpoint."
      description: "API version information. Not to be confused with the version of this specification. \nWhen the API version is incremented, any breaking changes to the previous API will be listed in the notes returned, as shown in the Response example below."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      responses:
        200:
          description: ""
          schema:
            required:
              - version
            properties:
              version:
                type: string
                example: "1.0.1"
              notes:
                type: string
                example: "Version 0.99 - a new mandatory field was added to the /investors/add path that breaks the previous api definition."
  /user/obtain_token:
    post:
      tags:
      - "user"
      summary: "Returns a token used to authenticate all other API calls apart from /info."
      description: "The username and password you provide should be the ones used to access Liquid Securties. The token returned can be used in subsequent API calls by setting the request header like so:\n\n { 'content-type': 'application/json', 'Authorization': 'token <returned_token>' } \n\nExamples of how to authenticate and call the API programmatically using Python and nodejs can be obtained by request."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          required:
          - username
          - password
          properties:
            username:
              type: string
              description: "The username used to access Liquid Securities."
            password:
              type: string
              description: "The password used to access Liquid Securities."
      responses:
        200:
          description: "Authentication token"
          schema:
            required:
            - token
            properties:
              token:
                type: string
                description: "The token that can be used to authenticate subsequent API calls."
        400:
          description: "Invalid credentials"
  /investors/:
    get:
      tags:
      - "investors"
      summary: "List of all Investors."
      description: ""
      responses:
        200:
          description: ""
          schema:
            type: array
            items:
              $ref: "#/definitions/InvestorResponse"
  /investors/{investorId}:
    get:
      tags:
      - "investors"
      summary: "Details of the Investor requested."
      description: ""
      parameters:
      - name: "investorId"
        in: "path"
        description: "ID of investor"
        required: true
        type: integer
      responses:
        200:
          description: ""
          schema:
            $ref: "#/definitions/InvestorResponse"
        403:
          description: "Not authorized"
        404:
          description: "Investor not found"
  /investors/add:
    post:
      tags:
      - "investors"
      summary: "Adds an Investor"
      description: ""
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          $ref: "#/definitions/InvestorAdd"
      responses:
        200:
          description: ""
          schema:
            $ref: "#/definitions/InvestorResponse"
        403:
          description: "Not authorized"
  /investors/{investorId}/edit:
    put:
      tags:
      - "investors"
      summary: "Updates an Investor"
      description: "is_company can't be modified"
      parameters:
      - name: "investorId"
        in: "path"
        description: "ID of investor"
        required: true
        type: integer
      - in: "body"
        name: "body"
        required: true
        schema:
          $ref: "#/definitions/InvestorEdit"
      responses:
        200:
          description: ""
          schema:
            $ref: "#/definitions/InvestorResponse"
        403:
          description: "Not authorized"
        404:
          description: "Investor not found"
  /investors/{investorId}/delete:
    delete:
      tags:
      - "investors"
      summary: "Deletes an Investor"
      parameters:
      - name: "investorId"
        in: "path"
        description: "ID of investor"
        required: true
        type: integer
      responses:
        204:
          description: "Successful delete"
        400:
          description: "Bad input"
        403:
          description: "Not authorized"
        404:
          description: "Investor not found"
  /investors/categories:
    get:
      tags:
      - "investors"
      summary: "Lists all Categories that can be associated with Investors."
      description: ""
      responses:
        200:
          description: "List of all investor categories"
          schema:
            type: array
            items:
              $ref: "#/definitions/InvestorCategoryResponse"
  /investors/categories/add:
    post:
      tags:
      - "investors"
      summary: "Adds a new Category"
      description: "Adds a new category that can then be assigned to one or more Investors."
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          $ref: "#/definitions/InvestorCategoryAdd"
      responses:
        200:
          description: "Investor Category"
          schema:
            $ref: "#/definitions/InvestorCategoryResponse"
        403:
          description: "Not authorized"
  /investors/categories/{categoryId}:
    get:
      tags:
      - "investors"
      summary: "Gets the details of the provided investor category"
      description: "Returns details of the category. The id can be used to associate investors with the category elsewhere."
      parameters:
      - name: "categoryId"
        in: "path"
        description: "ID of investor category"
        required: true
        type: integer
      responses:
        200:
          description: "Investor Category"
          schema:
            $ref: "#/definitions/InvestorCategoryResponse"
        403:
          description: "Not authorized"
        404:
          description: "Investor category not found"
  /investors/categories/{categoryId}/edit:
    put:
      tags:
      - "investors"
      summary: "Allows the update of the name and description of an investor category."
      parameters:
      - name: "categoryId"
        in: "path"
        description: "ID of investor category"
        required: true
        type: integer
      - in: "body"
        name: "body"
        required: true
        schema:
          $ref: '#/definitions/InvestorCategoryEdit'
      responses:
        200:
          description: "Investor Category"
          schema:
            $ref: "#/definitions/InvestorCategoryResponse"
        400:
          description: "Invalid data"
        403:
          description: "Not authorized"
        404:
          description: "Investor category not found"
  /investors/categories/{categoryId}/delete:
    delete:
      tags:
      - "investors"
      summary: "Delete a category."
      description: ""
      parameters:
      - name: "categoryId"
        in: "path"
        description: "ID of category"
        required: true
        type: integer
      responses:
        204:
          description: "Successful delete"
        404:
          description: "Category not found"
        403:
          description: "Not authorized"
  /investors/categories/{categoryId}/investors-add:
    post:
      tags:
      - "investors"
      description: "An Investor can be assigned to one or more investor categories using the categories array and providing the ids of the categories to associate with the Investor. \nThere must be Categories set up (you can use the /investors/categories/add API) before an Investor can be assigned to them.\nThe wallet id should be the Green wallet id that has been created for the Investor."
      summary: "Add an array of investors to a category."
      parameters:
      - name: "categoryId"
        in: "path"
        description: "ID of investor category"
        required: true
        type: integer
      - in: "body"
        name: "body"
        required: true
        description: "Investor ID or array of Investor IDs"
        schema:
          properties:
            investors:
              type: array
              example: [1, 2]
              items:
                type: integer
      responses:
        200:
          description: "Investor Category"
          schema:
            $ref: "#/definitions/InvestorCategoryResponse"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
  /investors/categories/{categoryId}/investors-delete:
    delete:
      tags:
      - "investors"
      summary: "Remove an array of investors from a category."
      description: ""
      parameters:
      - name: "categoryId"
        in: "path"
        description: "ID of investor category"
        required: true
        type: integer
      - in: "body"
        name: "body"
        required: true
        description: "Investor ID or array of Investor IDs"
        schema:
          properties:
            investors:
              type: array
              example: [1, 2]
              items:
                type: integer
      responses:
        200:
          description: "Investor Category"
          schema:
            $ref: "#/definitions/InvestorCategoryResponse"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
  /assets/:
    get:
      tags:
      - "assets"
      summary: "Returns a list of all assets"
      responses:
        200:
          description: "List of assets"
          schema:
            required:
            - name
            - asset_uuid
            - issuer
            - amount
            - asset_id
            type: array
            items:
              $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
  /assets/issue:
    post:
      tags:
      - "assets"
      summary: "Issues a new asset"
      description: "Issue an asset on the Liquid Network. If is_reissuable is true then reissuance_amount and reissuance_address must be provided. Name, ticker, domain and pubkey are committed to the issuance transaction, thus they cannot be changed later."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          $ref: '#/definitions/Issuance'
      responses:
        201:
          description: "Asset Issuance"
          schema:
            $ref: '#/definitions/IssuanceResponse'
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
  /assets/{assetUuid}:
    get:
      tags:
      - "assets"
      summary: "Gets details of a given asset"
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "Asset"
          schema:
            $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/edit:
    put:
      tags:
      - "assets"
      summary: "Updates an existing asset"
      description: "The only field that can be updated is the asset's authorization endpoint."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        required: true
        schema:
          properties:
            name:
              type: string
      responses:
        200:
          description: "Assets"
          schema:
            $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/delete:
    delete:
      tags:
      - "assets"
      summary: "Deletes the given asset and any associated relational data."
      description: "The deletion cannot be undone. Deletion does not affect the underlying asset on the Liquid blockchain, neither does it destroy an issued asset amount. Use with caution for assets accidentally issued."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        204:
          description: "Successful delete"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/categories-add:
    post:
      tags:
      - "assets"
      summary: "Add investor category or list of categories to an asset"
      description: "An asset can be assigned one or more investor categories\nThere must be Categories set up (you can use the /investors/categories/add API) before they can be assigned to an asset."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        required: true
        description: "Category ID or array of Category IDs"
        schema:
          properties:
            categories:
              type: array
              example: [1, 2]
              items:
                type: integer
      responses:
        200:
          description: "Asset"
          schema:
            $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/categories-delete:
    delete:
      tags:
      - "assets"
      summary: "Remove investor category or list of categories from asset"
      description: "Used to remove existing investor categories from an asset."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        required: true
        description: "Category ID or array of Category IDs"
        schema:
          properties:
            categories:
              type: array
              example: [1, 2]
              items:
                type: integer
      responses:
        200:
          description: "Asset"
          schema:
            $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/register:
    get:
      tags:
      - "assets"
      summary: "Registers the asset with the Blockstream Asset Registry"
      description: "Registers the asset if the requirements are satisifed.\n\nThe asset registry allows you to register an asset and prove ownership against a domain name.\nThe asset needs to have a ticker, domain and pubkey.\nFor more information see: https://docs.blockstream.com/liquid/developer-guide/developer-guide-index.html#proof-of-issuance-blockstream-s-liquid-asset-registry"
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "Asset"
          schema:
            $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/register-authorized:
    get:
      tags:
      - "assets"
      summary: "Register authorization with Green Address"
      description: "Authorizes the asset within Green to be handled by Green's wallet control features. Allows whitelisting etc."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "Asset"
          schema:
            $ref: "#/definitions/Asset"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/reissue-request:
    post:
      tags:
      - "assets"
      summary: "Requests the script to reissue an asset"
      description: "Request the command that can be used to reissue the given amount of the asset. The amount to be reissued should be provided and the return value will be in the form of a script that must be run locally against your Liquid node. The script will reissue the stated amount of the asset and post the resulting transaction data back to the Liquid Securities API reissue-confim endpoint to confirm and register the transaction and increase the available supply within Liquid Securities."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        required: true
        schema:
          properties:
            amount_to_reissue:
              type: integer
      responses:
        200:
          description: "Reissuance command in bash script"
          schema:
            properties:
              reissuance_bash_command:
                type: string
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/reissue-confirm:
    post:
      tags:
      - "assets"
      description: "Confirms the reissuance was made. Post the exact data returned from liquid-cli's 'gettransaction' method, including surrounding '{' and '}' marks. As such, no schema property is provided. Example post data: { 'amount': { 'bitcoin': 0, ... etc. You should not need to call this manually as the reissue-request API command provides a bash script that calls this API endpoint as part of its execution."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        required: true
        schema:
          properties:
            "":
              type: string
      responses:
        200:
          description: "Confirmation of the validity of the reissuance transaction."
          schema:
            properties:
              txid:
                type: string
              vout:
                type: integer
              destination_address:
                type: string
              reissuance_amount:
                type: integer
              confirmed_in_block:
                type: string
              created:
                type: string
                format: 'date-time'
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/activities:
    get:
      tags:
      - "assets"
      summary: "List of asset activities"
      description: "Returned activities can be of type: issuance, reissuance, distribution, transactions.
        Results are paged and sortable. See parameter notes for details of use. The start parameter is 1 (not zero) based to make paging easier for clients.
        start=1, count=50 should return activities list indexes 0 to 49.
        start=51, count=50 should return activities list indexes 50 to 99.
        a negative value can be provided to return from the end of the list."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "query"
        name: "start"
        type: "integer"
        description: "Start index for pagination"
        required: false
        default: 1
      - in: "query"
        name: "count"
        type: "integer"
        description: "Number of results per call"
        required: false
        default: 100000
      - in: "query"
        name: "sortcolumn"
        type: "string"
        description: "The sortcolumn parameter can either be an index number (starting at 1) or the string name of the column. "
        required: false
        default: 1
      - in: "query"
        name: "sortorder"
        type: "string"
        description: "The sortorder parameter can either be asc (for ascending) or desc (for descending) and defaults to asc if the parameter is not included."
        required: false
        default: "asc"
      responses:
        200:
          description: "List of Asset activities"
          schema:
            type: array
            items:
              $ref: "#/definitions/Activity"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/ownerships:
    get:
      tags:
      - "assets"
      summary: "List of asset ownership at a given point in time"
      description: "Returns ownership distribution.\n\nOwnership point in time is based upon the confirmation datetime of the associated transaction."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "query"
        name: "height"
        type: "integer"
        description: "If provided the height parameter must be a valid Liquid block height else height will be set to the last Liquid block. Example: height=100."
        required: false
      responses:
        200:
          description: "List of Asset ownerships based upon confirmed transactions."
          schema:
            type: array
            items:
              $ref: "#/definitions/Ownership"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/balance:
    get:
      tags:
      - "assets"
      summary: "Balance of asset"
      description: "Returns the balance of an asset and the list of outputs that the server lost track of. Under normal circumstances, the list of lost outputs is empty."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "Balance of an assets."
          schema:
            $ref: "#/definitions/Balance"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/reissuances:
    get:
      tags:
      - "assets"
      summary: "List of asset reissuances"
      description: "Details of each Liquid transaction where the associated asset was reissued. The reissuance itself would normally be carried out by the bash script returned from the reissue-request API endpoint."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "List of Asset reissuances"
          schema:
            type: array
            items:
              $ref: "#/definitions/Reissuance"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/assignments:
    get:
      tags:
      - "assignments and distributions"
      summary: "List of asset assignments"
      description: "List of asset assignments.\n\nAn assignment is an allocation of an asset to an investor. An assignment can be updated to adjust the amount assigned and also to prepare an assignment for distribution using /assets/{assetUuid}/assignments/{assignmentId}/edit.\nIf you want to distribute a lesser amount than the amount already assigned, you must reduce the amount assigned (what will be the remaining amount assigned) and create another assignment entry for the investor that is flagged as ready_for_distribution and set the amount to the value you want to later distribute.\n\nAssignments flagged as ready_for_distribution that do not have a distribution_uuid value will be included in the distribution transaction script returned by /assets/{assetUuid}/distributions/create/, which will also assign and return a distribution_uuid which can be used in distribution related api calls.\n\nAssignments with a distribution_uuid and a status of pending can either be cancelled using /assets/{assetUuid}/distributions/{distributionUuid}/cancel or the transaction performing the distribution can be confirmed using /assets/{assetUuid}/distributions/{distributionUuid}/confirm.\n\nAssignements with a status of 'unconfirmed' or 'confirmed' can be viewed using /{assetUuid}/distributions/{distributionUuid}/details. The status refers to the Liquid transaction status.\n\nAn investor may only have one entry of status 'assigned' and one entry with a status of either 'pending' or 'unconfirmed'. An investor may have many rows with a status of 'confirmed'."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "List of Asset Assignments"
          schema:
            type: array
            items:
              $ref: "#/definitions/Assignment"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/assignments/{assignmentId}:
    get:
      tags:
      - "assignments and distributions"
      summary: "Gets the details of asset assignment"
      description: "Details of the assignment. See /assets/{assetUuid}/assignments for description of returned fields and available actions."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - name: "assignmentId"
        in: "path"
        description: "Id of assignment"
        required: true
        type: "integer"
      responses:
        200:
          description: "Asset Assignment"
          schema:
            $ref: "#/definitions/Assignment"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/assignments/create:
    post:
      tags:
      - "assignments and distributions"
      summary: "Create an asset assignment"
      description: "The investor parameter should be the id of the investor the assigment is being made against.\n\nYou can only set the 'ready_for_distribution' value to true if the investor has no currently 'pending' or 'unconfirmed' distributions. You can only have one entry with a 'ready_for_distribution' value of true and a null 'distribution_uuid' value. \n\nSee /assets/{assetUuid}/assignments for description of returned fields and available actions."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        required: true
        schema:
          required:
          - assignments
          properties:
            assignments:
              type: array
              items:
                $ref: "#/definitions/AssignmentCreate"
      responses:
        200:
          description: "Asset Assignments"
          schema:
            type: array
            items:
              $ref: "#/definitions/Assignment"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/assignments/{assignmentId}/edit:
    put:
      tags:
      - "assignments and distributions"
      summary: "Edit asset assignment"
      description: "Allows the amount assigned and the ready_for_distribution flag to be amended. You can only have one entry with a 'ready_for_distribution' value of true and a null 'distribution_uuid' value.\n\nSee /assets/{assetUuid}/assignments for description of returned fields and available actions."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - name: "assignmentId"
        in: "path"
        description: "Id of assignment"
        required: true
        type: "integer"
      - in: "body"
        name: "body"
        required: true
        schema:
          properties:
            amount:
              type: integer
            ready_for_distribution:
              type: boolean
      responses:
        200:
          description: "Asset Assignment"
          schema:
            $ref: "#/definitions/Assignment"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/assignments/{assignmentId}/delete:
    delete:
      tags:
      - "assignments and distributions"
      summary: "Deletes the given assignment."
      description: "Sets the assignment to deleted so it will be excluded from future lists and details views etc."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - name: "assignmentId"
        in: "path"
        description: "Id of assignment"
        required: true
        type: "integer"
      responses:
        204:
          description: "Successful delete"
        403:
          description: "Not authorized"
        404:
          description: "Asset or assignment not found"
  /assets/{assetUuid}/distributions:
    get:
      tags:
        - "assignments and distributions"
      summary: "List of asset distributions"
      description: "Distributions of assigned amounts of an asset. A distribution represents the sending of an asset amount to one or more investors. One of more confirmed Liquid transactions represent the completion of a distribution. The returned data includes details of transaction data and is grouped by distribution_uuid. A distribution may span multiple transactions, depending on the number of outputs required. The distribution_status field is derived from the status of each transaction making up the distribution."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "List of Asset Distributions"
          schema:
            type: array
            items:
              $ref: "#/definitions/Distribution"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/distributions/{distributionUuid}:
    get:
      tags:
      - "assignments and distributions"
      summary: "Details of the asset distribution"
      description: "Returns details of the Assets distribution.\n\nSee /assets/{assetUuid}/distributions for an exlanation of the structure of a distribution."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - name: "distributionUuid"
        in: "path"
        description: "UUID of distribution"
        required: true
        type: string
      responses:
        200:
          description: "Asset Distribution details"
          schema:
            $ref: "#/definitions/Distribution"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/distributions/create/:
    get:
      tags:
      - "assignments and distributions"
      summary: "Creates an asset distribution."
      description: "Creates an asset distribution script that can be run locally against a Liquid node to distribute the asset to investors.\n\nAny assignments marked as 'ready_for_distribution' without an existing 'distribution_uuid' will be assigned a distribution_uuid and a script generated to perform the distribution transaction. When run, the script will also send the distribution_uuid and transaction details back to the /assets/{assetUuid}/distributions/{distributionUuid}/confirm api so Liquid Securities can monitor the transaction for confirmation."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      responses:
        200:
          description: "Asset Distribution Script"
          schema:
            $ref: "#/definitions/DistributionCreate"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
  /assets/{assetUuid}/distributions/{distributionUuid}/confirm:
    post:
      tags:
      - "assignments and distributions"
      summary: "Confirm a distribution transaction"
      description: "Confirms the distribution transaction was made. 'tx_data' is that returned from liquid-cli's 'gettransaction' method, including surrounding '{' and '}' marks; 'change_data' is that returned from liquid-cli's 'listunspent' method, including surrounding '{' and '}' marks."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - name: "distributionUuid"
        in: "path"
        description: "UUID of distribution"
        required: true
        type: "string"
      - in: "body"
        name: "body"
        required: true
        schema:
          properties:
            tx_data:
              type: object
            change_data:
              type: object
      responses:
        200:
          description: "Asset Distribution"
          schema:
            items:
              $ref: "#/definitions/Distribution"
        403:
          description: "Not authorized"
        404:
          description: "Asset or distribution not found"
  /assets/{assetUuid}/distributions/{distributionUuid}/cancel:
    delete:
      tags:
      - "assignments and distributions"
      summary: "Cancel a distribution"
      description: "Cancel an asset distribution. The status of the distribution must be 'pending'. Removes the 'distribution_uuid' from pending distributions. This essentially returns the distribution to an assignment marked as 'ready_for_distribution'."
      parameters:
      - name: "assetUuid"
        in: "path"
        description: "UUID of asset"
        required: true
        type: "string"
        format: "uuid"
      - name: "distributionUuid"
        in: "path"
        description: "UUID of distribution batch"
        required: true
        type: "integer"
      responses:
        200:
          description: "The distribution was cancelled"
        400:
          description: "Invalid input"
        403:
          description: "Not authorized"
        404:
          description: "Asset not found"
definitions:
  InvestorAdd:
    required:
      - name
    type: "object"
    properties:
      GAID:
        type: string
        example: "GAEnrGHeqCd5UQ2jTW2Mo32o6a2GG"
        description: "TODO"
      is_company:
        type: boolean
      name:
        type: string
        minLength: 1
        maxLength: 255
  InvestorResponse:
    type: "object"
    properties:
      id:
        type: integer
      GAID:
        type: string
      is_company:
        type: boolean
      name:
        type: string
      categories:
        type: array
        example: [1, 2]
        items:
          type: integer
  InvestorEdit:
    type: "object"
    properties:
      GAID:
        type: string
      name:
        type: string
  InvestorCategoryAdd:
    type: "object"
    required:
      - name
    properties:
      name:
        type: string
        minLength: 1
        maxLength: 255
      description:
        type: string
        maxLength: 1023
  InvestorCategoryResponse:
    type: "object"
    properties:
      id:
        type: integer
      name:
        type: string
      description:
        type: string
      investors:
        type: array
        example: [1, 2]
        items:
          type: integer
  InvestorCategoryEdit:
    type: "object"
    properties:
      name:
        type: string
      description:
        type: string
  Asset:
    type: "object"
    properties:
      name:
        type: string
      asset_uuid:
        type: string
      issuer:
        type: integer
      asset_id:
        type: string
      requirements:
        type: array
        example: [1, 2]
        items:
          type: integer
      ticker:
        type: string
      domain:
        type: string
      pubkey:
        type: string
      is_registered:
        type: boolean
      is_authorized:
        type: boolean
      authorizer_endpoint:
        type: string
  Assignment:
    type: "object"
    properties:
      id:
        type: integer
      investor:
        type: integer
      amount:
        type: integer
      receiving_address:
        type: string
      distribution_uuid:
        type: string
      ready_for_distribution:
        type: boolean
      distribution_status:
        type: string
        enum: [ASSIGNED, PENDING, UNCONFIRMED, CONFIRMED]
  AssignmentCreate:
    type: "object"
    properties:
      investor:
        type: integer
      amount:
        type: integer
        minimum: 1
        maximum: 2100000000000000
      ready_for_distribution:
        type: boolean
        default: false
    required:
      - investor
      - amount
  Distribution:
    type: object
    properties:
      distribution_uuid:
        type: string
      distribution_status:
        type: string
        enum: [UNCONFIRMED, CONFIRMED]
      transactions:
        type: array
        items:
          $ref: "#/definitions/Transaction"
  Transaction:
    type: object
    properties:
      txid:
        type: string
      transaction_status:
        type: string
        enum: [UNCONFIRMED, CONFIRMED]
      included_blockheight:
        type: integer
      confirmed_datetime:
        type: string
        format: "date-time"
      assignments:
        type: array
        items:
          $ref: "#/definitions/DistributionAssignment"
  DistributionAssignment:
    type: "object"
    properties:
      investor:
        type: integer
      amount:
        type: integer
      vout:
        type: integer
  DistributionCreate:
    type: object
    properties:
      distribution_uuid:
        type: string
      distribution_script:
        type: string
  Activity:
    type: "object"
    properties:
      type:
        type: string
      datetime:
        type: string
        format: 'date-time'
      description:
        type: string
      txid:
        type: string
      source_address:
        type: string
      destination_address:
        type: string
      amount:
        type: integer
  Ownership:
    type: "object"
    properties:
      owner:
        type: integer
        description: "Id of the owner, if the owner is the issuer, this field is the string 'ISSUER'"
      amount:
        type: integer
  Outpoint:
    type: "object"
    properties:
      txid:
        type: string
      vout:
        type: integer
  Balance:
    type: "object"
    properties:
      confirmed_balance:
        type: array
        items:
          $ref: "#/definitions/Ownership"
      lost_outputs:
        description: "List of output which the server has lost track of."
        type: array
        items:
          $ref: "#/definitions/Outpoint"
  Issuance:
    type: "object"
    properties:
      name:
        type: string
        minLength: 5
        maxLength: 255
        description: "Must be ASCII"
      amount:
        type: integer
        minimum: 1
        maximum: 2100000000000000
      destination_address:
        type: string
        description: "Must be a valid Liquid address"
      domain:
        type: string
        minLength: 4
        maxLength: 255
        description: "Domain for asset registry"
      ticker:
        type: string
        minLength: 3
        maxLength: 5
        description: "Ticker for asset registry"
      pubkey:
        type: string
        maxLength: 66
        minLength: 66
        description: "Pubkey for asset registry, must be a compressed pubkey in hex"
      is_confidential:
        type: boolean
        default: false
      is_reissuable:
        type: boolean
        default: false
      reissuance_amount:
        type: integer
        default: 0
        minimum: 0
        maximum: 2100000000000000
      reissuance_address:
        type: string
        default: "\"\""
        description: "Must be a valid Liquid address or the empty string"
      authorizer_endpoint:
         type: string
         description: "TODO"
         minLength: 5
         maxLength: 255
    required:
      - name
      - amount
      - destination_address
      - domain
      - ticker
      - pubkey
  IssuanceResponse:
    type: "object"
    properties:
      name:
        type: string
      amount:
        type: integer
      destination_address:
        type: string
      domain:
        type: string
      ticker:
        type: string
      pubkey:
        type: string
      is_confidential:
        type: boolean
      is_reissuable:
        type: boolean
      reissuance_amount:
        type: integer
      reissuance_address:
        type: string
      asset_id:
        type: string
        minLength: 64
        maxLength: 64
        description: "Asset id of the newly generated asset in hex"
      reissuance_token_id:
        type: string
        minLength: 64
        maxLength: 64
        description: "Reissuance token id of the newly generated asset in hex, may be null"
      asset_uuid:
        type: string
        minLength: 36
        maxLength: 36
        description: "Asset UUID used by the server"
      txid:
        minLength: 64
        maxLength: 64
        type: string
        description: "Issuance transaction id"
      vin:
        type: integer
        description: "Issuance transaction input"
      asset_vout:
        type: integer
        description: "Issuance transaction output for newly created assets"
      reissuance_vout:
        type: integer
        description: "Issuance transaction output for newly created reissuance tokens, may be null"
      authorizer_endpoint:
         type: string
         description: "TODO"
  Reissuance:
    type: "object"
    properties:
      txid:
        type: string
      vout:
        type: integer
      destination_address:
        type: string
      reissuance_amount:
        type: integer
      confirmed_in_block:
        type: string
      created:
        type: string
        format: 'date-time'