treetracker-wallet-api.yaml

openapi: 3.0.0
info:
  title: Treetracker Wallet API
  version: '1.31.2'
  description: 'The Wallet API of Greenstand for managing impact wallets and tokens.'
  contact:
    name: Greenstand Support
    email: admin@greenstand.com
  license:
    name: AGPL 3.0
    url: 'https://www.gnu.org/licenses/agpl-3.0.en.html'
servers:
  - url: https://{environment}-k8s.treetracker.org/wallet/v2
    variables:
      environment:
        default: dev
        enum:
          - dev     # Development server
          - test    # Test server
          - prod    # Production server
paths:
  '/auth':
    post:
      tags:
        - Authentication
      operationId: post-auth
      summary: Authenticate account
      description: 'Authenticate the client using wallet name or id and password, and respond with a bearer token'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
      requestBody:
        description: 'Authentication request body'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/authRequest'
        required: true
      responses:
        '200':
          description: 'Successful authentication response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bearerToken'
        '401':
          description: 'Incorrect password for wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 401
                message: 'Invalid Credentials'
        '404':
          description: 'No wallet found with provided wallet name or id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Could not find entity by wallet name: bad_wallet'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          description: 'Missing request parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"wallet" is not allowed to be empty'
      deprecated: false
  '/tokens':
    get:
      tags:
        - Token details
      operationId: get-tokens
      summary: Get a list of tokens in the current wallet or managed wallets.
      description: 'Get a list of for tokens in the current wallet or managed wallets, matching certain parameters'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: limit
          in: query
          description: Number of items to return
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            example: 100
            default: 2000
        - name: offset
          in: query
          description: 'Where does the list offset, 0 means start from the beginning of the list'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 0
            example: 1
            default: 0
        - name: wallet
          description: 'Wallet name can be specified if the authenticated wallet manages other wallets. The default is to return tokens matching the authenticated wallet.'
          in: query
          schema:
            type: string
            example: wallet2
      responses:
        '200':
          description: 'Returns list of tokens matching the input parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokens'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersLimit'
      deprecated: false
  '/tokens/{token_uuid}':
    get:
      tags:
        - Token details
      operationId: get-tokens-tokenId
      summary: Get details for one token
      description: 'Get details for one token in the current wallet or managed wallets, matching certain parameters'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: token_uuid
          description: 'ID of specific token to retrieve'
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b
      responses:
        '200':
          description: 'Returns token matching the input parameter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'No token found matching token_uuid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Can not find token by id: a5fee1ec-31dd-4150-aae1-dfe423ee9fc7'
        '422':
          description: 'Missing or invalid query or request parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"value" must be a valid GUID'
      deprecated: false
  '/tokens/{token_uuid}/transactions':
    get:
      tags:
        - Token details
      operationId: get-tokens-tokenId-transactions
      summary: Get transaction history for a particular token
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: token_uuid
          in: path
          description: 'ID of specific token to retrieve'
          required: true
          explode: true
          schema:
            type: string
            example: e3cd6587-ff01-419b-b2c9-44ceed4dc749
        - name: limit
          in: query
          description: Number of items to return
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            default: 1000
            example: 100
        - name: offset
          in: query
          description: 'Where does the list offset, 0 means offset from the beginning of the list'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 0
            example: 0
            default: 0
      responses:
        '200':
          description: 'Return list of transactions associated with the token'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/historyResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'No token found matching token_uuid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Can not find token by id:d15f40b4-ed8b-457a-8c85-97beb8862682'
        '422':
          description: 'Missing or invalid query or request parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"value" must be a valid GUID'
      deprecated: false
  '/wallets':
    get:
      tags:
        - Managed wallets
      operationId: get-wallets
      summary: 'Get all wallets managed by the logged in account. This endpoint is also used to get the total number of tokens in a given wallet.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: limit
          in: query
          description: 'Number of items to return'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            example: 100
            default: 1000
        - name: offset
          in: query
          description: 'Where does the list offset, 0 means offset from the beginning of the list'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 0
            example: 1
            default: 0
        - name: name
          in: query
          description: 'Filter wallets by name'
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: walletA
        - name: sort_by
          in: query
          description: 'Sort result by field'
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: created_at
            default: created_at
        - name: order
          in: query
          description: 'Order result in ascending or descending order'
          required: false
          style: form
          explode: true
          schema:
            type: string
            enum:
              - asc
              - desc
            example: desc
            default: desc
        - name: created_at_start_date
          in: query
          description: 'Wallets created after this date'
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date
            example: 2023-09-12
        - name: created_at_end_date
          in: query
          description: 'Wallets created before this date'
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date
            example: 2023-09-20
        - name: account_id
          in: query
          description: 'Filter wallets by account id'
          required: false
          style: form
          explode: true
          schema:
            type: string
            example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b
      responses:
        '200':
          description: 'Returns list of managed wallets'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersLimit'
      deprecated: false
    post:
      tags:
        - Managed wallets
      operationId: post-wallets
      summary: 'Create a new managed wallet'
      description: 'Create a new managed wallet. Requires the manage_account role.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
      requestBody:
        description: 'Wallet creation request'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/accountRequest'
        required: true
      responses:
        '201':
          description: 'A new wallet was created'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 784311ee-156e-41c7-a85f-b51572cbcf91
                  wallet:
                    type: string
                    example: new_wallet
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: 'The wallet to be created already exists'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 409
                message: 'The wallet "walletX" already exists'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          description: 'Missing or invalid parameters in request body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"wallet" is required'
      deprecated: false
  '/wallets/{wallet_uuid}':
    get:
      tags:
        - Managed wallets
      operationId: get-wallets-walletId
      summary: Get details for one wallet, including number of tokens
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: wallet_uuid
          description: 'ID of wallet'
          in: path
          required: true
          schema:
            type: string
            example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b
      responses:
        '200':
          description: 'Return wallet matching wallet_uuid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/walletNotFound'
        '422':
          description: 'Missing or invalid query parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"wallet_id" must be a valid GUID'
      deprecated: false
  '/wallets/{wallet_uuid}/trust_relationships':
    get:
      tags:
        - Managed wallets
      operationId: get-wallets-walletId-trustRelationships
      summary: Get list of trust relationships for the specified wallet
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: wallet_uuid
          description: 'ID of wallet'
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b
        - name: state
          in: query
          description: 'Trust state'
          required: false
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/trustStateType'
        - name: type
          in: query
          description: 'Trust type'
          required: false
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/trustType'
        - name: request_type
          in: query
          description: 'Trust request type'
          required: false
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/trustRequestType'
      responses:
        '200':
          description: 'Return list of trust relationships for the wallet matching wallet_uuid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/walletNotFound'
        '422':
          description: 'Invalid query parameter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"wallet_id" must be a valid GUID'
      deprecated: false
  /wallets/batch-create-wallet:
    post:
      tags:
        - Managed wallets
      operationId: post-wallets-batchCreate
      deprecated: false
      summary: 'Batch Create Wallets'
      description: 'Create multiple wallets using a CSV file.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeMultipartHeader'
      requestBody:
        description: 'Wallet batch create request'
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/batchCreateRequest'
            encoding:
              csv:
                contentType: text/csv
        required: true
      responses:
        '200':
          description: 'Batch create response'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchCreateResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '415':
          $ref: '#/components/responses/MultipartMediaTypeError'
        '422':
          description: 'Missing or invalid parameters in request body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"sender_wallet" is not allowed to be empty'
  /wallets/batch-transfer:
    post:
      tags:
        - Managed wallets
      operationId: post-wallets-batchTransfer
      summary: 'Batch transfer'
      deprecated: false
      description: 'Create multiple transfers using a CSV file.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeMultipartHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/batchTransferRequest'
            encoding:
              csv:
                contentType: text/csv
      responses:
        '200':
          description: 'Successful batch transfer response'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Batch transfer successful'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '415':
          $ref: '#/components/responses/MultipartMediaTypeError'
        '422':
          description: 'Missing or invalid parameters in request body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"sender_wallet" is required'
  '/transfers':
    post:
      tags:
        - Transfers
      operationId: post-transfers
      summary: 'Move, request, and send tokens between wallets'
      description: 'Move, request, and send tokens between wallets (by name or id) as allowed by trust relationships. Transfer can be created/requested either using an explicit list of token ids or by specifying a bundle of tokens using tags and a count of tokens to attempt to transfer. The originator of the request (currently logged in wallet) is used by the server code to compute who the originating wallet is for this request, whether the request is a credit, debit, or managed transfer, and if appropriate trust relationships exist to automatically execute or if it must be stored as a request until approval. A claim boolean is entered to specify if the tokens are transferable. Claimed tokens cannot participate in further transfers after they are received.'
      security:
        - normalUserAccessTokenAuth
        - walletOperatorMicroserviceAccessTokenAuth
          description: 'For the wallet operator microservice to do transfers, the transfer is executed immediately without the need for the wallet to accept the transfer.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
      requestBody:
        description: 'Request body for creating a transfer'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/transferRequest'
        required: true
      responses:
        '201':
          description: 'The transfer was completely processed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transferItem'
        '202':
          $ref: '#/components/responses/transferPendingResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: 'Lacking permission to transfer the tokens'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 403
                message: 'The token 89b071ee-c49d-420c-b43d-0d3dfe323962 does not belong to the sender wallet'
        '404':
          description: 'No wallet or token found matching the corresponding parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Could not find entity by wallet name: testwalletxyz'
        '409':
          description: 'The transfer cannot be processed due to some conflict'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 409
                message: 'The token 89b071ee-c49d-420c-b43d-0d3dfe32396 is claimed, cannot be transfered'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          description: 'Missing or invalid request parameters in body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"bundle" is required'
    get:
      tags:
        - Transfers
      operationId: get-transfers
      summary: 'Get requested, pending, completed, cancelled, and failed transfers'
      description: 'Get requested, pending, completed, cancelled and failed transfers for wallets (by name or id). The authenticated wallet is either the source, destination, or originating wallet entity.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - in: query
          name: state
          schema:
            $ref: '#/components/schemas/transferState'
          required: false
          description: 'requested, pending, completed, cancelled, failed'
        - in: query
          name: wallet
          schema:
            $ref: '#/components/schemas/walletNameOrId'
          required: false
          description: 'filter transfers matches the source, destination, or originating wallet (by name or id) of a transfer'
        - name: before
          in: query
          description: 'Get transfers that fall before this date'
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date-time
            example: 2023-08-10
        - name: after
          in: query
          description: 'Get transfers that fall after this date'
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date-time
            example: 2023-08-02
        - name: limit
          in: query
          description: Number of items to return
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            example: 100
            default: 1000
        - name: offset
          in: query
          description: 'Where does the list offset, 0 means offset from the beginning of the list'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 0
            example: 1
            default: 0
      responses:
        '200':
          description: Return array of matching transfers
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfers:
                    type: array
                    items:
                      $ref: '#/components/schemas/transferItem'
                  query:
                    type: object
                    properties:
                      limit:
                        type: integer
                        example: 200
                      offset:
                        type: integer
                        example: 0
                  total:
                    type: integer
                    example: 1
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersLimit'
  '/transfers/{transfer_id}':
    get:
      tags:
        - Transfers
      operationId: get-transfers-transferId
      summary: 'Get information of a single transfer'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: transfer_id
          in: path
          description: 'The unique ID for the transfer'
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: 'Return the transfer matching the transfer_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transferItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Transfer does not exist or it is not related to this wallet'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTransferId'
    delete:
      tags:
        - Transfers
      operationId: delete-transfers
      summary: 'Cancel a pending or requested transfer that has not closed'
      description: 'Cancel a pending (untrusted) or requested transfer. The executor can delete the pending/requested transfer before it is executed.  Transfer is marked canceled by this command.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: transfer_id
          in: path
          description: 'The unique ID for the transfer'
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          $ref: '#/components/responses/transferCancelledResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Can not find transfer by id: 03537683-5356-42f4-97b2-95ba287a453b'
        '409':
          description: 'Transfer could not be cancelled due to some conflict'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 409
                message: 'The transfer state is neither pending nor requested'
  '/transfers/{transfer_id}/tokens':
    get:
      tags:
        - Transfers
      operationId: get-transfers-transferId-tokens
      summary: 'Get all tokens linked to a single transfer'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: transfer_id
          in: path
          description: 'The unique ID for the transfer'
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
        - name: limit
          in: query
          description: 'Number of items to return'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            default: 2000
            example: 100
        - name: offset
          in: query
          description: 'Where does the list offset, 0 means offset from the beginning of the list'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 0
            example: 0
            default: 0
      responses:
        '200':
          description: 'Returns list of tokens associated with the transfer'
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokens:
                    type: array
                    items:
                      $ref: '#/components/schemas/transferTokenItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Transfer does not exist or it is not related to this wallet'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTransferId'
  '/transfers/{transfer_id}/accept':
    post:
      tags:
        - Transfers
      operationId: post-transfers-transferId-accept
      summary: 'Accept a pending (untrusted) transfer'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
        - name: transfer_id
          in: path
          description: 'The unique ID for the transfer'
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          $ref: '#/components/responses/transferAcceptedResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: 'Lacking permission to accept the transfer'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 403
                message: 'Current account has no permission to accept this transfer'
        '404':
          description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Can not find transfer by id: df80b648-4fef-4ca6-b704-9e7e1c77d1ef'
        '409':
          description: 'Transfer could not be processed due to some conflict'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 409
                message: 'Do not have enough tokens'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTransferId'
  '/transfers/{transfer_id}/decline':
    post:
      tags:
        - Transfers
      operationId: post-transfers-transferId-decline
      summary: 'Decline a pending (untrusted) transfer'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
        - name: transfer_id
          in: path
          description: 'The unique ID for the transfer'
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          $ref: '#/components/responses/transferCancelledResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: 'Lacking permission to decline the transfer'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 403
                message: 'Current account has no permission to decline this transfer'
        '404':
          description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Can not find transfer by id: df80b648-4fef-4ca6-b704-9e7e1c77d1ef'
        '409':
          description: 'Transfer could not be processed due to some conflict'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 409
                message: 'The transfer state is neither pending nor requested'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTransferId'
  '/transfers/{transfer_id}/fulfill':
    post:
      tags:
        - Transfers
      operationId: post-transfers-transferId-fulfill
      summary: 'Fulfill a requested transfer'
      description: 'Post a list of tokens to fulfill the parameters of a transfer request that specifies tokens using a bundle. This allows the debited wallet to decide which tokens matching the bundle parameters to attach to the transfer. Application logic must check that each token matches the parameters of the request.'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
        - name: transfer_id
          in: path
          description: the id of the transfer record on the server
          required: true
          style: simple
          schema:
            $ref: '#/components/schemas/uuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestBundleFulfillBody'
      responses:
        '200':
          $ref: '#/components/responses/transferAcceptedResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: 'Lacking permission to fulfill the transfer'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 403
                message: 'Current account has no permission to decline this transfer'
        '404':
          description: 'No transfer found matching the transfer_id or the transfer is not associated with the logged in wallet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 404
                message: 'Can not find transfer by id: df80b648-4fef-4ca6-b704-9e7e1c77d1ef'
        '409':
          description: 'Transfer could not be processed due to some conflict'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 409
                message: 'Operation forbidden, the transfer state is wron'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          description: 'Invalid or missing parameters in query or request body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"implicit" is required'
  '/trust_relationships':
    get:
      tags:
        - Trust relationships
      operationId: get-trustRelationships
      summary: 'Get a list of existing, requested, and pending trust relationships'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: limit
          in: query
          description: 'Number of items to return'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            default: 500
            example: 100
        - name: offset
          in: query
          description: 'Where does the list offset, 0 means start from the beginning of the list'
          required: false
          style: form
          explode: true
          schema:
            type: integer
            format: int32
            minimum: 0
            example: 0
            default: 0
        - name: state
          in: query
          description: 'Filter by state of the trust relationship'
          required: false
          style: form
          schema:
            $ref: '#/components/schemas/trustStateType'
        - name: type
          in: query
          description: 'Type of the trust relationship'
          required: false
          style: form
          schema:
            $ref: '#/components/schemas/trustType'
        - name: request_type
          in: query
          description: 'Type of the trust relationship request'
          required: false
          style: form
          schema:
            $ref: '#/components/schemas/trustRequestType'
      responses:
        '200':
          description: 'Returns list of trust relationships'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersLimit'
    post:
      tags:
        - Trust relationships
      operationId: post-trustRelationships
      summary: 'Request a new trust relationship from another wallet'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/trustRequest'
      responses:
        '201':
          description: 'Accepted but waiting for approval'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: 'Lacking permission to create the trust relationship'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 403
                message: 'Have no permission to deal with this actor'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          description: 'Invalid or missing parameters in request body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 422
                message: '"trust_request_type" is required'
  '/trust_relationships/{trust_relationship_id}':
    get:
      tags:
        - Trust relationships
      operationId: get-trustRelationships-trustRelationshipId
      summary: 'Get details for a single trust relationship'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: trust_relationship_id
          description: 'ID of the trust relationship'
          in: path
          required: true
          schema:
            type: string
            example: 496ffa8e-2fa2-488c-98e1-acf9b57c230b
      responses:
        '200':
          description: 'Return the trust relationship matching trust_relationship_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipItem'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/trustRelationshipNotFound'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTrustRelationshipId'
      deprecated: false
    delete:
      tags:
        - Trust relationships
      operationId: delete-trustRelationships-trustRelationshipId
      summary: 'Remove a trust relationship linked to the authenticated wallet'
      description: 'Remove a trust relationship linked to the authenticated wallet. This could be either the actor wallet or the target wallet'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - name: trust_relationship_id
          in: path
          description: the id of the entity trust record on the server
          required: true
          style: simple
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: 'Trust relationship state is changed to `cancelled_by_originator`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipItem'
              example:
                id: c04e3b02-971c-4268-a701-b6c01468ca62
                actor_wallet_id: 644f4d3b-a53c-457c-8677-42b5b812c23d
                target_wallet_id: 8428ea73-51df-4266-a038-4577b9aef06f
                type: send
                originator_wallet_id: 644f4d3b-a53c-457c-8677-42b5b812c23d
                request_type: send
                state: cancelled_by_originator
                created_at: '2023-08-19T03:40:38.200Z'
                updated_at: '2023-08-19T03:40:38.200Z'
                active: true
                originating_wallet: testuser
                actor_wallet: testuser
                target_wallet: testWallet11
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: 'Lacking permission to cancel the trust relationship'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                code: 403
                message: 'Have no permission to cancel this relationship'
        '404':
          $ref: '#/components/responses/trustRelationshipNotFound'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTrustRelationshipId'
  '/trust_relationships/{trust_relationship_id}/accept':
    post:
      tags:
        - Trust relationships
      operationId: post-trustRelationships-trustRelationshipId-accept
      summary: 'Accept a trust relationship'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
        - name: trust_relationship_id
          in: path
          description: 'The unique ID of the entity trust record on the server'
          required: true
          style: simple
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: 'Trust relationship state is changed to `trusted`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipItem'
              example:
                id: c04e3b02-971c-4268-a701-b6c01468ca62
                actor_wallet_id: 644f4d3b-a53c-457c-8677-42b5b812c23d
                target_wallet_id: 8428ea73-51df-4266-a038-4577b9aef06f
                type: send
                originator_wallet_id: 644f4d3b-a53c-457c-8677-42b5b812c23d
                request_type: send
                state: trusted
                created_at: '2023-08-19T03:40:38.200Z'
                updated_at: '2023-08-19T03:40:38.200Z'
                active: true
                originating_wallet: testuser
                actor_wallet: testuser
                target_wallet: testWallet11
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/trustRelationshipNotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTrustRelationshipId'
  '/trust_relationships/{trust_relationship_id}/decline':
    post:
      tags:
        - Trust relationships
      operationId: post-trustRelationships-trustRelationshipId-decline
      summary: 'Decline a trust relationship'
      parameters:
        - $ref: '#/components/parameters/treetrackerApiKeyParam'
        - $ref: '#/components/parameters/contentTypeJsonHeader'
        - name: trust_relationship_id
          in: path
          description: 'The unique ID of the entity trust record on the server'
          required: true
          style: simple
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: 'Trust relationship state is changed to `cancelled_by_target`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trustRelationshipItem'
              example:
                id: c04e3b02-971c-4268-a701-b6c01468ca62
                actor_wallet_id: 644f4d3b-a53c-457c-8677-42b5b812c23d
                target_wallet_id: 8428ea73-51df-4266-a038-4577b9aef06f
                type: send
                originator_wallet_id: 644f4d3b-a53c-457c-8677-42b5b812c23d
                request_type: send
                state: cancelled_by_target
                created_at: '2023-08-19T03:40:38.200Z'
                updated_at: '2023-08-19T03:40:38.200Z'
                active: true
                originating_wallet: testuser
                actor_wallet: testuser
                target_wallet: testWallet11
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/trustRelationshipNotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          $ref: '#/components/responses/InvalidQueryParametersTrustRelationshipId'
components:
  parameters:
    treetrackerApiKeyParam:
      name: TREETRACKER-API-KEY
      in: header
      description: 'API key for authenticating requests to the Treetracker Wallet API'
      required: true
      style: simple
      schema:
        type: string
        example: '{{apiKey}}'
    contentTypeJsonHeader:
      name: Content-Type
      in: header
      description: 'Specifies the media type of the request payload'
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    contentTypeMultipartHeader:
      name: Content-Type
      in: header
      description: 'Specifies the media type of the request payload'
      required: true
      style: simple
      schema:
        type: string
        example: multipart/form-data
  schemas:
    authRequest:
      title: Authentication Request
      required:
        - wallet
        - password
      type: object
      properties:
        wallet:
          $ref: '#/components/schemas/walletName'
        password:
          type: string
          example: walnut
    accountRequest:
      title: 'Account Request'
      required:
        - wallet
      type: object
      properties:
        wallet:
          $ref: '#/components/schemas/walletName'
    batchCreateRequest:
      title: 'Batch Create Request'
      required:
        - csv
      type: object
      properties:
        sender_wallet:
          type: string
          example: wallet1
        token_transfer_amount_default:
          type: integer
          example: 5
        csv:
          type: string
          format: binary
          description: 'Must be a `.csv` file'
    batchCreateResponse:
      title: 'Batch Create Response'
      type: object
      properties:
        wallets_created:
          type: integer
        wallets_already_exists:
          type: array
          items:
            type: string
        wallet_other_failure_count:
          type: integer
        extra_wallet_information_saved:
          type: integer
        extraWalletInformationNotSaved:
          type: array
          items:
            type: string
      example:
        wallets_created: 3
        wallets_already_exists: [ ]
        wallet_other_failure_count: 0
        extra_wallet_information_saved: 0
        extraWalletInformationNotSaved: [ ]
    batchTransferRequest:
      title: 'Batch Transfer Request'
      required:
        - csv
        - sender_wallet
      type: object
      properties:
        sender_wallet:
          type: string
          example: wallet1
        token_transfer_amount_default:
          type: integer
          example: 5
        csv:
          type: string
          format: binary
          description: 'Must be a `.csv` file'
    errorResponse:
      title: 'Error Response'
      description: 'Error response'
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    historyItem:
      title: History Item
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 'efaab5eb-1e6e-4f78-b3e8-4bc7f6989b12'
        token_id:
          type: string
          format: uuid
          example: 'd15f40b4-ed8b-457a-8c85-97beb8862685'
        transfer_id:
          type: string
          format: uuid
          example: '57e70823-be2a-4b7d-9874-9a44e95baa1d'
        source_wallet_id:
          type: string
          format: uuid
          example: '482bf306-30c7-4cea-833a-1cdda3d96573'
        destination_wallet_id:
          type: string
          format: uuid
          example: '644f4d3b-a53c-457c-8677-42b5b812c23d'
        processed_at:
          type: string
          format: date-time
          example: '2023-08-02T09:36:46.402Z'
        claim:
          type: boolean
          example: false
        sender_wallet:
          type: string
          example: 'testuser'
        receiver_wallet:
          type: string
          example: 'otherwallet'
    historyResponse:
      title: History Response
      type: object
      properties:
        history:
          type: array
          items:
            $ref: '#/components/schemas/historyItem'
    bearerToken:
      title: Successful Authentication Response
      type: object
      properties:
        bearer:
          type: string
          example:
            bearer: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    requestBundleFulfillBody:
      title: 'Transfer Request Fulfillment'
      type: object
      oneOf:
        - properties:
            tokens:
              type: array
              items:
                type: string
                format: uuid
              description: 'Array of explicit tokens'
              example: [ 'ed155d71-67f0-4d21-a73d-f5445b8c43c8' ]
        - properties:
            implicit:
              type: boolean
              description: 'Automatically fill the request with tokens matching the specified parameters if set'
              example: false
    tokens:
      title: Token Query Response
      type: object
      properties:
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/tokenItem'
    tokenItem:
      title: Token Item
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 'ca1a99c3-9797-465d-8ee3-8dbd26a08faa'
        capture_id:
          type: string
          format: uuid
          example: '8df635f6-2df8-496f-93da-3060fc1e3180'
        wallet_id:
          type: string
          format: uuid
          example: 'c63da6b3-d7a3-444a-9ff0-10644036eccd'
        transfer_pending:
          type: boolean
          example: false
        transfer_pending_id:
          type: string
          format: uuid
          example: null
        created_at:
          type: string
          format: date-time
          example: '2021-07-02T18:31:07.208Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-07-02T18:31:07.208Z'
        claim:
          type: boolean
          example: false
        links:
          type: object
          properties:
            capture:
              type: string
              example: '/webmap/tree?uuid=8df635f6-2df8-496f-93da-3060fc1e3180'
    transferItem:
      title: Transfer Details
      properties:
        id:
          type: string
          format: uuid
          description: 'The unique ID for this transfer'
          example: cf0ce129-8c12-45cf-b914-a8f1cb6b7dc5
        type:
          $ref: '#/components/schemas/transferType'
        parameters:
          type: object
          oneOf:
            - properties:
                bundle:
                  type: object
                  properties:
                    bundleSize:
                      type: integer
                      description: Number of tokens associated with the transfer
                      example: 2
                  required:
                    - bundleSize
            - properties:
                tokens:
                  type: array
                  items:
                    type: string
                  description: Array of explicit tokens
        state:
          $ref: '#/components/schemas/transferState'
        created_at:
          type: string
          format: date-time
          example: 2023-08-02T21:46:35.134Z
        closed_at:
          type: string
          format: date-time
          example: 2023-08-02T21:46:35.134Z
        active:
          type: boolean
          example: true
        claim:
          type: boolean
          example: false
        originating_wallet:
          type: string
          example: testuser
        source_wallet:
          type: string
          example: testuser
        destination_wallet:
          type: string
          example: wallet22
        token_count:
          type: integer
          example: 1
    transferRequest:
      title: Transfer Request
      oneOf:
        - properties:
            tokens:
              type: array
              items:
                type: string
                format: uuid
              description: 'Explicitly transfer tokens'
            sender_wallet:
              oneOf:
                - type: string
                - type: string
                  format: uuid
            receiver_wallet:
              oneOf:
                - type: string
                - type: string
                  format: uuid
            claim:
              type: boolean
          required:
            - tokens
            - sender_wallet
            - receiver_wallet
          example:
            tokens:
              - e1b278e8-f025-44b7-9dd8-36ffb2d58f7e
              - e533653e-2dbf-48cd-940a-a87e5a393158
            sender_wallet: wallet1
            receiver_wallet: wallet2
            claim: false
        - properties:
            bundle:
              type: object
              description: 'Transfer some amount of token'
              properties:
                bundle_size:
                  type: integer
                  format: int32
                  minimum: 1
                  maximum: 10000
                  description: required number of trees to transfer
            sender_wallet:
              oneOf:
                - type: string
                - type: string
                  format: uuid
            receiver_wallet:
              oneOf:
                - type: string
                - type: string
                  format: uuid
            claim:
              type: boolean
          required:
            - bundle
            - sender_wallet
            - receiver_wallet
          example:
            bundle:
              bundle_size: 100
            sender_wallet: wallet1
            receiver_wallet: wallet2
            claim: false
    transferState:
      title: 'Transfer State'
      type: string
      enum:
        - requested
        - pending
        - completed
        - cancelled
        - failed
      example: pending
    transferTokenItem:
      title: Token Item (Transfer)
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 'ca1a99c3-9797-465d-8ee3-8dbd26a08faa'
        capture_id:
          type: string
          format: uuid
          example: '8df635f6-2df8-496f-93da-3060fc1e3180'
        wallet_id:
          type: string
          format: uuid
          example: 'c63da6b3-d7a3-444a-9ff0-10644036eccd'
        transfer_pending:
          type: boolean
          example: false
        transfer_pending_id:
          type: string
          format: uuid
          example: null
        created_at:
          type: string
          format: date-time
          example: '2021-07-02T18:31:07.208Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-07-02T18:31:07.208Z'
        claim:
          type: boolean
          example: false
        token_id:
          type: string
          format: uuid
          example: cf6dde25-2eb1-4b44-a70c-724c36591b9a
        transfer_id:
          type: string
          format: uuid
          example: fea4faa4-0f37-4330-a970-4f0160d9d591
        source_wallet_id:
          type: string
          format: uuid
          example: 644f4d3b-a53c-457c-8677-42b5b812c23
        destination_wallet_id:
          type: string
          format: uuid
          example: ef6a37ce-c459-4a2c-83c3-85e829e4a75e
        processed_at:
          type: string
          format: date-time
          example: '2021-07-02T18:31:07.208Z'
    transferType:
      title: 'Transfer Type'
      type: string
      enum:
        - send
        - deduct
        - managed
      example: send
      description: 'The type of transfer. The value is computed by the server based on the submitted request'
    trustRelationshipsResponse:
      title: Trust Relationship Response
      type: object
      properties:
        trust_relationships:
          type: array
          items:
            $ref: '#/components/schemas/trustRelationshipItem'
    trustRelationshipItem:
      title: 'Trust Relationship Item'
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 0b335cd4-db82-4784-89f5-c8800844c291
        actor_wallet_id:
          type: string
          format: uuid
          example: 644f4d3b-a53c-457c-8677-42b5b812c23d
        target_wallet_id:
          type: string
          format: uuid
          example: ef6a37ce-c459-4a2c-83c3-85e829e4a75e
        type:
          $ref: '#/components/schemas/trustType'
        originator_wallet_id:
          type: string
          format: uuid
          example: 644f4d3b-a53c-457c-8677-42b5b812c23d
        request_type:
          $ref: '#/components/schemas/trustRequestType'
        state:
          $ref: '#/components/schemas/trustStateType'
        created_at:
          type: string
          format: date-time
          example: 2023-08-15T23:29:12.261Z
        updated_at:
          type: string
          format: date-time
          example: 2023-08-15T23:29:12.261Z
        active:
          type: boolean
          example: true
        originating_wallet:
          type: string
          example: testuser
        actor_wallet:
          type: string
          example: testuser
        target_wallet:
          type: string
          example: otherwallet
    trustRequest:
      title: Trust Request
      type: object
      properties:
        trust_request_type:
          $ref: '#/components/schemas/trustRequestType'
        requester_wallet:
          type: string
          description: 'Optional. If not present, then the default requester_wallet will be the current logged in wallet'
          example: wallet1
        requestee_wallet:
          type: string
          description: 'The wallet to which this request is targeted.'
          example: testwallet
      required:
        - trust_request_type
        - requestee_wallet
    trustRequestType:
      title: 'Trust Request Type'
      type: string
      enum:
        - send
        - receive
        - manage
        - yield
        - deduct
        - release
      example: manage
      description: >
        Trust Request type:
          * `send` - Request to allow actor to send to target.
          * `receive` - Request a send privilege to a wallet controlled by the originator on behalf of another sending wallet (opposite direction of send trust request).
          * `manage` - Request to allow actor to move funds from target wallet to any other wallet they control.
          * `yield` - Request to give manage privilege on a wallet controlled by the originator to another wallet (opposite direction of manage trust request).
          * `deduct` - Request to allow actor to deduct from wallet.
          * `release` - Request a deduct privilege from a wallet controlled by the originator on behalf of another deducting wallet (opposite direction of deduct trust request).

    trustStateType:
      title: 'Trust State Type'
      type: string
      enum:
        - requested
        - cancelled_by_originator
        - cancelled_by_actor
        - cancelled_by_target
        - trusted
      example: trusted
      description: >
        Trust state type:
         * `requested` - The trust relationship is pending approval.
         * `cancelled_by_originator` - The trust relationship was cancelled by the originator.
         * `cancelled_by_actor` - The trust relationship was cancelled by the actor.
         * `cancelled_by_target` - The trust relationship was cancelled by the target.
         * `trusted` - The trust relationship is active.
    trustType:
      title: 'Trust Type'
      type: string
      enum:
        - send
        - deduct
        - manage
      example: send
      description: >
        Trust Type:
         * `send` - Allow actor to send to target.
         * `deduct` - Allow actor to deduct from wallet.
         * `manage` - Allow actor to move funds from target wallet to any other wallet they control.

    uuid:
      title: 'UUID'
      description: 'Unique identifier for an entity'
      type: string
      format: uuid
      example: bc7d4c0d-1ea5-4ead-9fef-b726a34c2d74
    walletItem:
      title: 'Wallet Details'
      properties:
        id:
          type: string
          format: uuid
          example: 482bf306-30c7-4cea-833a-1cdda3d96573
        name:
          type: string
          example: test11
        about:
          type: string
          example: 'feugiat pretium nibh ipsum consequat nisl vel pretium lectus quam id leo in vitae turpis massa sed elementum tempus egestas'
        logo_url:
          type: string
          format: url
          example: https://www.placehold.co/192x192
        created_at:
          type: string
          format: date-time
          example: 2023-08-08T06:28:39.766Z
        tokens_in_wallet:
          type: integer
          example: 12
    walletNameOrId:
      title: 'Wallet Name or ID'
      oneOf:
        - type: string
          example: wallet1
        - type: string
          format: uuid
          example: bc7d4c0d-1ea5-4ead-9fef-b726a34c2d74
    walletName:
      title: 'Wallet Name'
      type: string
      minLength: 3
      maxLength: 254
      example: sprinter_van_2004
    walletsResponse:
      title: Wallets Response
      type: object
      properties:
        total:
          type: integer
          description: 'Total count of wallets satisfying the query condition'
          example: 1
        query:
          type: object
          properties:
            offset:
              type: integer
              format: int32
              example: 0
            limit:
              type: integer
              format: int32
              example: 5
            sort_by:
              type: string
              example: created_at
            order:
              type: string
              example: desc
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/walletItem'
  responses:
    InvalidQueryParametersLimit:
      description: 'Invalid query parameters'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 422
            message: '"limit" must be a number'
    InvalidQueryParametersTransferId:
      description: 'Invalid query parameters'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 422
            message: '"transfer_id" must be a valid GUID'
    InvalidQueryParametersTrustRelationshipId:
      description: 'Invalid query parameters'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 422
            message: '"trustRelationshipId" must be a valid GUID'
    MultipartMediaTypeError:
      description: Invalid content type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 415
            message: 'Invalid content type. API only supports multipart/form-data'
    transferAcceptedResponse:
      description: 'Transfer is marked as completed'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/transferItem'
          example:
            id: df80b648-4fef-4ca6-b704-9e7e1c77d1ed
            type: send
            parameters:
              bundle:
                bundleSize: '1'
            state: completed
            created_at: '2023-08-01T22:09:35.642Z'
            closed_at: '2023-08-01T22:09:35.642Z'
            active: true
            claim: false
            originating_wallet: testuser
            source_wallet: testuser
            destination_wallet: wallet2
    transferCancelledResponse:
      description: 'Transfer is marked as cancelled'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/transferItem'
          example:
            id: df80b648-4fef-4ca6-b704-9e7e1c77d1ed
            type: send
            parameters:
              bundle:
                bundleSize: '1'
            state: cancelled
            created_at: '2023-08-01T22:09:35.642Z'
            closed_at: '2023-08-01T22:09:35.642Z'
            active: true
            claim: false
            originating_wallet: testuser
            source_wallet: testuser
            destination_wallet: wallet2
    transferPendingResponse:
      description: 'The transfer could not be completely processed because a trust relationship does not exist allowing for automated processing.  If a the source wallet is controlled by the authenticated user, a transfer in the pending state has been created. If the source wallet is not controlled but the authenticated user, but the destination wallet is, then a transfer in the requested state has been created'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/transferItem'
          example:
            id: 251debc2-9077-4876-b710-f5543c9a7719
            type: send
            parameters:
              bundle:
                bundleSize: 1
            state: pending
            created_at: '2023-08-31T05:02:52.623Z'
            closed_at: '2023-08-31T05:02:52.623Z'
            active: true
            claim: false
            originating_wallet: testuser
            source_wallet: wallet1
            destination_wallet: wallet2
            token_count: 1
    trustRelationshipNotFound:
      description: 'No trust relationship found matching trust_relationship_id or it is not associated with the logged in wallet'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 404
            message: 'No such trust relationship exists or it is not associated with the current wallet.'
    UnauthorizedError:
      description: 'API key and/or Bearer token is missing or invalid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Invalid API Key:
              value:
                code: 401
                message: 'Invalid access - no API key'
            Invalid Bearer Token:
              value:
                code: 401
                message: 'ERROR: Authentication, no token supplied for protected path'
    UnsupportedMediaTypeError:
      description: Invalid content type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 415
            message: 'Invalid content type. API only supports application/json'
    walletNotFound:
      description: 'No wallet found matching wallet_uuid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 404
            message: 'Could not find wallet by id: ef6a37ce-c459-4a2c-83c3-85e829e4a753'
  securitySchemes:
    normalUserAccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This is for the normal user to authenticate with the wallet service, using the bearered JWT token which is issued by Keycloak, that is, the access token, to verify the authenticity of the request'
    walletOperatorMicroserviceAccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This is for other microservices to authenticate with the wallet service, using the bearered JWT token which is issued by Keycloak, that is, the access token, to verify the authenticity of the request, the access token must have the `wallet_operator` role, see more at: https://github.com/Greenstand/treetracker-wallet-app/blob/89737430276a0ed0856734d1d51aa901a1f4c0e8/apps/user/README.md#how-to-access-wallet-api-draft'
security:
  - normalUserAccessTokenAuth: [ ]