Spiko Withdrawal orders API

openapi: 3.1.0
info:
  title: Spiko Distributor Account transactions Withdrawal orders API
  version: v0
  description: The Distributor API allows third parties like SaaS providers, fintechs or Web3 companies to distribute the Spiko Funds to their customers. With this API, you can programmatically manage investors, send subscription and redemption orders, and access real-time portfolio information.
servers:
- url: https://distributor-api.spiko.io
  description: Production Server
- url: https://distributor-api.preprod.spiko.io
  description: Pre-production Server
security: []
tags:
- name: Withdrawal orders
paths:
  /v0/withdrawal-orders/:
    post:
      tags:
      - Withdrawal orders
      operationId: withdrawalOrders.createWithdrawalOrder
      parameters: []
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - investorId
                - accountId
                - shareClassId
                - destination
                - quantity
                - status
                - createdAt
                - executedAt
                - canceledAt
                - settlement
                properties:
                  id:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  investorId:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  accountId:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  shareClassId:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  destination:
                    anyOf:
                    - type: object
                      required:
                      - type
                      - bankAccountId
                      properties:
                        type:
                          type: string
                          enum:
                          - bank-transfer
                        bankAccountId:
                          type: string
                          description: a Universally Unique Identifier
                          format: uuid
                      additionalProperties: false
                    - type: object
                      required:
                      - type
                      - bankAccountId
                      properties:
                        type:
                          type: string
                          enum:
                          - instant-bank-transfer
                        bankAccountId:
                          type: string
                          description: a Universally Unique Identifier
                          format: uuid
                      additionalProperties: false
                    - type: object
                      required:
                      - type
                      - walletId
                      properties:
                        type:
                          type: string
                          enum:
                          - stablecoin-transfer
                        walletId:
                          type: string
                          description: a Universally Unique Identifier
                          format: uuid
                      additionalProperties: false
                  quantity:
                    anyOf:
                    - type: object
                      required:
                      - mode
                      - amount
                      properties:
                        mode:
                          type: string
                          enum:
                          - amount
                        amount:
                          $ref: '#/components/schemas/NonNegativeAmount'
                      additionalProperties: false
                    - type: object
                      required:
                      - mode
                      - shares
                      properties:
                        mode:
                          type: string
                          enum:
                          - shares
                        shares:
                          $ref: '#/components/schemas/BigDecimal'
                      additionalProperties: false
                    - type: object
                      required:
                      - mode
                      properties:
                        mode:
                          type: string
                          enum:
                          - total
                      additionalProperties: false
                  status:
                    type: string
                    enum:
                    - pending
                    - executed
                    - canceled
                  createdAt:
                    $ref: '#/components/schemas/Date'
                  executedAt:
                    anyOf:
                    - $ref: '#/components/schemas/Date'
                    - type: 'null'
                  canceledAt:
                    anyOf:
                    - $ref: '#/components/schemas/Date'
                    - type: 'null'
                  settlement:
                    anyOf:
                    - type: object
                      required:
                      - amount
                      - shares
                      - appliedNAV
                      properties:
                        amount:
                          $ref: '#/components/schemas/NonNegativeAmount'
                        shares:
                          $ref: '#/components/schemas/BigDecimal'
                        appliedNAV:
                          type: object
                          required:
                          - day
                          - amount
                          properties:
                            day:
                              type: string
                              title: Day
                              description: a day in ISO format "YYYY-MM-DD"
                            amount:
                              $ref: '#/components/schemas/NonNegativeAmount'
                          additionalProperties: false
                      additionalProperties: false
                    - type: 'null'
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/HttpApiDecodeError'
                - $ref: '#/components/schemas/ApplicationError'
                - $ref: '#/components/schemas/InsufficientBalanceError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/Unauthorized'
                - $ref: '#/components/schemas/DistributorAuthenticationError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: NotFound
        '409':
          description: Investor token has already been used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DuplicateInvestorTokenError'
        '422':
          description: Investor is not ready for order creation yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestorNotReadyError'
      description: "\n**Create a new withdrawal order for an investor with the specified parameters.**\n\n- The `quantity` field supports three modes:\n  - `{\"mode\":\"amount\",\"amount\":{\"value\":\"1000\",\"currency\":\"USD\"}}` - withdraw a specific fiat amount\n  - `{\"mode\":\"shares\",\"shares\":\"10.5\"}` - withdraw a specific number of shares\n  - `{\"mode\":\"total\"}` - withdraw all shares (full withdrawal)\n- If the order is expressed in shares or if it is total, the currency used will be the bank account currency.\n- Returns complete order details, including its UUID identifier.\n\n> **Distribute-with-Spiko's-license distributors** cannot place this order from their backend. The investor must place it directly from the browser with a short-lived [Investor JWT](/developers/distributor_api/technical_guides/investor_jwt), targeting the investor-scoped path **`POST /v0/investor/withdrawal-orders/`** (identical payload and response, but authenticated with the investor JWT as bearer token instead of your API credentials).\n"
      summary: Create withdrawal order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - investorId
              - shareClassId
              - bankAccountId
              - quantity
              properties:
                investorId:
                  type: string
                  description: a Universally Unique Identifier
                  format: uuid
                accountId:
                  anyOf:
                  - type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  - type: 'null'
                shareClassId:
                  type: string
                  description: a Universally Unique Identifier
                  format: uuid
                bankAccountId:
                  type: string
                  description: a Universally Unique Identifier
                  format: uuid
                quantity:
                  anyOf:
                  - type: object
                    required:
                    - mode
                    - amount
                    properties:
                      mode:
                        type: string
                        enum:
                        - amount
                      amount:
                        $ref: '#/components/schemas/NonNegativeAmount'
                    additionalProperties: false
                  - type: object
                    required:
                    - mode
                    - shares
                    properties:
                      mode:
                        type: string
                        enum:
                        - shares
                      shares:
                        $ref: '#/components/schemas/BigDecimal'
                    additionalProperties: false
                  - type: object
                    required:
                    - mode
                    properties:
                      mode:
                        type: string
                        enum:
                        - total
                    additionalProperties: false
              additionalProperties: false
        required: true
    get:
      tags:
      - Withdrawal orders
      operationId: withdrawalOrders.getWithdrawalOrders
      parameters:
      - name: investorId
        in: query
        schema:
          type: string
          description: a Universally Unique Identifier
          format: uuid
        required: true
        description: a Universally Unique Identifier
      - name: shareClassId
        in: query
        schema:
          type: string
          description: a Universally Unique Identifier
          format: uuid
        required: false
        description: a Universally Unique Identifier
      - name: page
        in: query
        schema:
          type: string
          title: Page number
          description: 'defaults to "1" if not provided '
        required: false
        description: 'defaults to "1" if not provided '
      - name: limit
        in: query
        schema:
          type: string
          title: Number of items per page
          description: defaults to "50" if not provided
        required: false
        description: defaults to "50" if not provided
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - investorId
                  - accountId
                  - shareClassId
                  - destination
                  - quantity
                  - status
                  - createdAt
                  - executedAt
                  - canceledAt
                  - settlement
                  properties:
                    id:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    investorId:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    accountId:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    shareClassId:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    destination:
                      anyOf:
                      - type: object
                        required:
                        - type
                        - bankAccountId
                        properties:
                          type:
                            type: string
                            enum:
                            - bank-transfer
                          bankAccountId:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                        additionalProperties: false
                      - type: object
                        required:
                        - type
                        - bankAccountId
                        properties:
                          type:
                            type: string
                            enum:
                            - instant-bank-transfer
                          bankAccountId:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                        additionalProperties: false
                      - type: object
                        required:
                        - type
                        - walletId
                        properties:
                          type:
                            type: string
                            enum:
                            - stablecoin-transfer
                          walletId:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                        additionalProperties: false
                    quantity:
                      anyOf:
                      - type: object
                        required:
                        - mode
                        - amount
                        properties:
                          mode:
                            type: string
                            enum:
                            - amount
                          amount:
                            $ref: '#/components/schemas/NonNegativeAmount'
                        additionalProperties: false
                      - type: object
                        required:
                        - mode
                        - shares
                        properties:
                          mode:
                            type: string
                            enum:
                            - shares
                          shares:
                            $ref: '#/components/schemas/BigDecimal'
                        additionalProperties: false
                      - type: object
                        required:
                        - mode
                        properties:
                          mode:
                            type: string
                            enum:
                            - total
                        additionalProperties: false
                    status:
                      type: string
                      enum:
                      - pending
                      - executed
                      - canceled
                    createdAt:
                      $ref: '#/components/schemas/Date'
                    executedAt:
                      anyOf:
                      - $ref: '#/components/schemas/Date'
                      - type: 'null'
                    canceledAt:
                      anyOf:
                      - $ref: '#/components/schemas/Date'
                      - type: 'null'
                    settlement:
                      anyOf:
                      - type: object
                        required:
                        - amount
                        - shares
                        - appliedNAV
                        properties:
                          amount:
                            $ref: '#/components/schemas/NonNegativeAmount'
                          shares:
                            $ref: '#/components/schemas/BigDecimal'
                          appliedNAV:
                            type: object
                            required:
                            - day
                            - amount
                            properties:
                              day:
                                type: string
                                title: Day
                                description: a day in ISO format "YYYY-MM-DD"
                              amount:
                                $ref: '#/components/schemas/NonNegativeAmount'
                            additionalProperties: false
                        additionalProperties: false
                      - type: 'null'
                  additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpApiDecodeError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/Unauthorized'
                - $ref: '#/components/schemas/DistributorAuthenticationError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: NotFound
      description: "\n**Retrieve a paginated list of the withdrawal orders made by an investor.**\n\n> ⚠️ **For displaying an account's activity, prefer the [account transaction history endpoint](#tag/Account-transactions/operation/accountTransactions.getAccountTransactions).** It returns deposits, withdrawals, transfers and yield accruals as a single time-ordered stream, with cursor pagination, so you don't need to call multiple per-order-type endpoints and reconcile their results.\n\n- Orders are sorted by creation date (newest first).\n- When `shareClassId` is specified, only withdrawal orders for that share class are returned.\n- Pagination parameters (`page` & `limit`) are optional and default to `page = 1` and `limit = 50`.\n          "
      summary: Get withdrawal orders
  /v0/withdrawal-orders/{id}:
    get:
      tags:
      - Withdrawal orders
      operationId: withdrawalOrders.getWithdrawalOrder
      parameters:
      - name: id
        in: path
        schema:
          type: string
          description: a Universally Unique Identifier
          format: uuid
        required: true
        description: a Universally Unique Identifier
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - investorId
                - accountId
                - shareClassId
                - destination
                - quantity
                - status
                - createdAt
                - executedAt
                - canceledAt
                - settlement
                properties:
                  id:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  investorId:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  accountId:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  shareClassId:
                    type: string
                    description: a Universally Unique Identifier
                    format: uuid
                  destination:
                    anyOf:
                    - type: object
                      required:
                      - type
                      - bankAccountId
                      properties:
                        type:
                          type: string
                          enum:
                          - bank-transfer
                        bankAccountId:
                          type: string
                          description: a Universally Unique Identifier
                          format: uuid
                      additionalProperties: false
                    - type: object
                      required:
                      - type
                      - bankAccountId
                      properties:
                        type:
                          type: string
                          enum:
                          - instant-bank-transfer
                        bankAccountId:
                          type: string
                          description: a Universally Unique Identifier
                          format: uuid
                      additionalProperties: false
                    - type: object
                      required:
                      - type
                      - walletId
                      properties:
                        type:
                          type: string
                          enum:
                          - stablecoin-transfer
                        walletId:
                          type: string
                          description: a Universally Unique Identifier
                          format: uuid
                      additionalProperties: false
                  quantity:
                    anyOf:
                    - type: object
                      required:
                      - mode
                      - amount
                      properties:
                        mode:
                          type: string
                          enum:
                          - amount
                        amount:
                          $ref: '#/components/schemas/NonNegativeAmount'
                      additionalProperties: false
                    - type: object
                      required:
                      - mode
                      - shares
                      properties:
                        mode:
                          type: string
                          enum:
                          - shares
                        shares:
                          $ref: '#/components/schemas/BigDecimal'
                      additionalProperties: false
                    - type: object
                      required:
                      - mode
                      properties:
                        mode:
                          type: string
                          enum:
                          - total
                      additionalProperties: false
                  status:
                    type: string
                    enum:
                    - pending
                    - executed
                    - canceled
                  createdAt:
                    $ref: '#/components/schemas/Date'
                  executedAt:
                    anyOf:
                    - $ref: '#/components/schemas/Date'
                    - type: 'null'
                  canceledAt:
                    anyOf:
                    - $ref: '#/components/schemas/Date'
                    - type: 'null'
                  settlement:
                    anyOf:
                    - type: object
                      required:
                      - amount
                      - shares
                      - appliedNAV
                      properties:
                        amount:
                          $ref: '#/components/schemas/NonNegativeAmount'
                        shares:
                          $ref: '#/components/schemas/BigDecimal'
                        appliedNAV:
                          type: object
                          required:
                          - day
                          - amount
                          properties:
                            day:
                              type: string
                              title: Day
                              description: a day in ISO format "YYYY-MM-DD"
                            amount:
                              $ref: '#/components/schemas/NonNegativeAmount'
                          additionalProperties: false
                      additionalProperties: false
                    - type: 'null'
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpApiDecodeError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/Unauthorized'
                - $ref: '#/components/schemas/DistributorAuthenticationError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: NotFound
      description: '

        **Retrieve information about a specific withdrawal order.**


        - Includes order status (`pending` / `executed` / `canceled`).

        '
      summary: Get withdrawal order
  /v0/withdrawal-orders/all/:
    get:
      tags:
      - Withdrawal orders
      operationId: withdrawalOrders.getAllDistributorWithdrawalOrders
      parameters:
      - name: page
        in: query
        schema:
          type: string
          title: Page number
          description: 'defaults to "1" if not provided '
        required: false
        description: 'defaults to "1" if not provided '
      - name: limit
        in: query
        schema:
          type: string
          title: Number of items per page
          description: defaults to "50" if not provided
        required: false
        description: defaults to "50" if not provided
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - investorId
                  - accountId
                  - shareClassId
                  - destination
                  - quantity
                  - status
                  - createdAt
                  - executedAt
                  - canceledAt
                  - settlement
                  properties:
                    id:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    investorId:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    accountId:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    shareClassId:
                      type: string
                      description: a Universally Unique Identifier
                      format: uuid
                    destination:
                      anyOf:
                      - type: object
                        required:
                        - type
                        - bankAccountId
                        properties:
                          type:
                            type: string
                            enum:
                            - bank-transfer
                          bankAccountId:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                        additionalProperties: false
                      - type: object
                        required:
                        - type
                        - bankAccountId
                        properties:
                          type:
                            type: string
                            enum:
                            - instant-bank-transfer
                          bankAccountId:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                        additionalProperties: false
                      - type: object
                        required:
                        - type
                        - walletId
                        properties:
                          type:
                            type: string
                            enum:
                            - stablecoin-transfer
                          walletId:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                        additionalProperties: false
                    quantity:
                      anyOf:
                      - type: object
                        required:
                        - mode
                        - amount
                        properties:
                          mode:
                            type: string
                            enum:
                            - amount
                          amount:
                            $ref: '#/components/schemas/NonNegativeAmount'
                        additionalProperties: false
                      - type: object
                        required:
                        - mode
                        - shares
                        properties:
                          mode:
                            type: string
                            enum:
                            - shares
                          shares:
                            $ref: '#/components/schemas/BigDecimal'
                        additionalProperties: false
                      - type: object
                        required:
                        - mode
                        properties:
                          mode:
                            type: string
                            enum:
                            - total
                        additionalProperties: false
                    status:
                      type: string
                      enum:
                      - pending
                      - executed
                      - canceled
                    createdAt:
                      $ref: '#/components/schemas/Date'
                  

# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spiko/refs/heads/main/openapi/spiko-withdrawal-orders-api-openapi.yml