Upvest Investment Operations

naftiko: "1.0.0-alpha1"

info:
  label: "Upvest Investment Operations"
  description: "Unified workflow capability for building and managing investment experiences on the Upvest platform. Covers user onboarding, account management, order placement, portfolio management, savings plans, and position tracking. Designed for fintech developers and integration engineers building embedded investment features."
  tags:
    - Upvest
    - Investments
    - Fintech
    - Banking Infrastructure
    - Trading
    - Portfolios
    - Savings Plans
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      UPVEST_CLIENT_ID: UPVEST_CLIENT_ID
      UPVEST_CLIENT_SECRET: UPVEST_CLIENT_SECRET
      UPVEST_ACCESS_TOKEN: UPVEST_ACCESS_TOKEN

capability:
  consumes:
    - import: upvest-investment
      location: ./shared/investment-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: upvest-investment-ops-api
      description: "Unified REST API for Upvest investment operations."
      resources:
        - path: /v1/users
          name: users
          description: "User onboarding and management"
          operations:
            - method: GET
              name: list-users
              description: "List all onboarded users"
              call: "upvest-investment.list-users"
              with:
                offset: "rest.offset"
                limit: "rest.limit"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-user
              description: "Onboard a new user"
              call: "upvest-investment.create-user"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/users/{user_id}
          name: user
          description: "Individual user operations"
          operations:
            - method: GET
              name: retrieve-user
              description: "Retrieve a specific user"
              call: "upvest-investment.retrieve-user"
              with:
                user_id: "rest.user_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/accounts
          name: accounts
          description: "Investment account management"
          operations:
            - method: GET
              name: list-accounts
              description: "List all accounts"
              call: "upvest-investment.list-accounts"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-account
              description: "Create a new investment account"
              call: "upvest-investment.create-account"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/accounts/{account_id}
          name: account
          description: "Individual account operations"
          operations:
            - method: GET
              name: retrieve-account
              description: "Retrieve a specific account"
              call: "upvest-investment.retrieve-account"
              with:
                account_id: "rest.account_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders
          name: orders
          description: "Order placement and management"
          operations:
            - method: GET
              name: list-orders
              description: "List all orders"
              call: "upvest-investment.list-orders"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: place-order
              description: "Place a buy or sell order"
              call: "upvest-investment.place-order"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/orders/{order_id}
          name: order
          description: "Individual order operations"
          operations:
            - method: GET
              name: retrieve-order
              description: "Retrieve order details"
              call: "upvest-investment.retrieve-order"
              with:
                order_id: "rest.order_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: cancel-order
              description: "Cancel a pending order"
              call: "upvest-investment.cancel-order"
              with:
                order_id: "rest.order_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/instruments
          name: instruments
          description: "Financial instruments and prices"
          operations:
            - method: GET
              name: list-instruments
              description: "List available instruments"
              call: "upvest-investment.list-instruments"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/portfolios
          name: portfolios
          description: "Portfolio management"
          operations:
            - method: GET
              name: list-portfolios
              description: "List portfolios"
              call: "upvest-investment.list-portfolios"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-portfolio
              description: "Create a portfolio"
              call: "upvest-investment.create-portfolio"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/savings-plans
          name: savings-plans
          description: "Automated savings plan management"
          operations:
            - method: GET
              name: list-savings-plans
              description: "List savings plans"
              call: "upvest-investment.list-savings-plans"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-savings-plan
              description: "Create a savings plan"
              call: "upvest-investment.create-savings-plan"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/positions
          name: positions
          description: "Account positions and valuations"
          operations:
            - method: GET
              name: list-positions
              description: "List account positions"
              call: "upvest-investment.list-positions"
              with:
                account_id: "rest.account_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/direct-debits
          name: direct-debits
          description: "Direct debit payments"
          operations:
            - method: POST
              name: create-direct-debit
              description: "Create a direct debit"
              call: "upvest-investment.create-direct-debit"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-direct-debits
              description: "List direct debits"
              call: "upvest-investment.list-direct-debits"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/payments/withdrawals
          name: withdrawals
          description: "Cash withdrawal operations"
          operations:
            - method: POST
              name: create-withdrawal
              description: "Process a withdrawal"
              call: "upvest-investment.create-withdrawal"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-withdrawals
              description: "List withdrawals"
              call: "upvest-investment.list-withdrawals"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/webhooks
          name: webhooks
          description: "Webhook subscription management"
          operations:
            - method: GET
              name: list-webhooks
              description: "List webhook subscriptions"
              call: "upvest-investment.list-webhook-subscriptions"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-webhook
              description: "Register a webhook"
              call: "upvest-investment.create-webhook-subscription"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/reports
          name: reports
          description: "Reports and transaction data"
          operations:
            - method: GET
              name: list-reports
              description: "List investment reports"
              call: "upvest-investment.list-reports"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-transactions
              description: "List transaction history"
              call: "upvest-investment.list-transactions"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: upvest-investment-ops-mcp
      transport: http
      description: "MCP server for AI-assisted investment operations on the Upvest platform."
      tools:
        - name: list-users
          description: "List all onboarded users on the investment platform"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-users"
          with:
            offset: "tools.offset"
            limit: "tools.limit"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-user
          description: "Onboard a new user to the investment platform"
          hints:
            readOnly: false
          call: "upvest-investment.create-user"
          outputParameters:
            - type: object
              mapping: "$."
        - name: retrieve-user
          description: "Retrieve details for a specific user by ID"
          hints:
            readOnly: true
          call: "upvest-investment.retrieve-user"
          with:
            user_id: "tools.user_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-accounts
          description: "List all investment accounts"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-accounts"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-account
          description: "Create a new investment account for a user"
          hints:
            readOnly: false
          call: "upvest-investment.create-account"
          outputParameters:
            - type: object
              mapping: "$."
        - name: retrieve-account
          description: "Retrieve details for a specific investment account"
          hints:
            readOnly: true
          call: "upvest-investment.retrieve-account"
          with:
            account_id: "tools.account_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-instruments
          description: "List available financial instruments (stocks, ETFs, mutual funds)"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-instruments"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-instrument-prices
          description: "Get price data for a specific financial instrument"
          hints:
            readOnly: true
          call: "upvest-investment.list-instrument-prices"
          with:
            instrument_id: "tools.instrument_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-orders
          description: "List all orders across accounts"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-orders"
          outputParameters:
            - type: object
              mapping: "$."
        - name: place-order
          description: "Place a buy or sell order for a financial instrument"
          hints:
            readOnly: false
          call: "upvest-investment.place-order"
          outputParameters:
            - type: object
              mapping: "$."
        - name: retrieve-order
          description: "Retrieve details and status for a specific order"
          hints:
            readOnly: true
          call: "upvest-investment.retrieve-order"
          with:
            order_id: "tools.order_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: cancel-order
          description: "Cancel a pending order before execution"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "upvest-investment.cancel-order"
          with:
            order_id: "tools.order_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-portfolios
          description: "List all investment portfolios"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-portfolios"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-portfolio
          description: "Create a new investment portfolio with custom allocations"
          hints:
            readOnly: false
          call: "upvest-investment.create-portfolio"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-savings-plans
          description: "List all automated savings plans"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-savings-plans"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-savings-plan
          description: "Create an automated recurring investment savings plan"
          hints:
            readOnly: false
          call: "upvest-investment.create-savings-plan"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-positions
          description: "List current investment positions and holdings for an account"
          hints:
            readOnly: true
          call: "upvest-investment.list-positions"
          with:
            account_id: "tools.account_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-valuations
          description: "Get current and historical account valuations"
          hints:
            readOnly: true
          call: "upvest-investment.list-valuations"
          with:
            account_id: "tools.account_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-direct-debit
          description: "Set up a direct debit payment for account funding"
          hints:
            readOnly: false
          call: "upvest-investment.create-direct-debit"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-withdrawal
          description: "Process a cash withdrawal from an investment account"
          hints:
            readOnly: false
          call: "upvest-investment.create-withdrawal"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-reports
          description: "List investment reports and statements"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-reports"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-transactions
          description: "List transaction history for accounts"
          hints:
            readOnly: true
            openWorld: true
          call: "upvest-investment.list-transactions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-webhook-subscriptions
          description: "List all registered webhook subscriptions"
          hints:
            readOnly: true
          call: "upvest-investment.list-webhook-subscriptions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-webhook-subscription
          description: "Register a new webhook endpoint for event notifications"
          hints:
            readOnly: false
          call: "upvest-investment.create-webhook-subscription"
          outputParameters:
            - type: object
              mapping: "$."