tZERO Trading API

openapi: 3.2.0
info:
  title: Issuance & Secondary Markets Trading API
  description: APIs to Create Individual broker dealer accounts, Trigger KYC on the investors in the account, Review account information and KYC results, View Primary offering that are available to invest and manage investments in the assets.
servers:
- url: https://gateway-web-api.tzero.com/app
tags:
- name: Trading
  description: Order management for secondary-market trading (fees, submit, cancel, list orders).
paths:
  /trading/v1/fee:
    get:
      tags:
      - Trading
      summary: Calculates an estimated fee for the trade
      description: Calculates anticipated order fees prior to actually submitting order changes and incurring the fees.
      operationId: getOrderFee
      security:
      - x-api-key: []
        bearerAuth: []
      parameters:
      - name: price
        in: query
        required: true
        schema:
          type: string
        description: Price (in USD) of a single unit of the item intended to be traded.
      - name: assetId
        in: query
        required: true
        schema:
          type: string
      - name: quantity
        in: query
        required: true
        schema:
          type: string
        description: The total quantity of the item intended to be traded.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeResponse'
        '400':
          description: The request is invalid. The provided data must be changed.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /trading/v1/accounts/{accountId}/orders:
    post:
      tags:
      - Trading
      summary: Creates an order for an Account
      description: Creates an order for the Account Id in the URL
      operationId: createOrder
      security:
      - x-api-key: []
        bearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Account identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            example:
              symbol: tZERO
              assetId: '39737'
              side: BUY
              timeInForce: DAY
              expireDate: '2026-12-31'
              type: LIMIT
              quantity: 100
              limitPrice: 10
              transactionId: TRAN-123
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
              example:
                transactionId: TRAN-123
                id: ORDER-123456
                status: SUBMITTED
                symbol: tZERO
                assetId: '39737'
                side: BUY
                timeInForce: DAY
                type: LIMIT
                quantity: 100
                limitPrice: 10
                expireTs: '2026-04-29T23:34:59.000000-04:00'
                createdTs: '2026-04-20T23:34:59.000000-04:00'
                fee: 1.23
        '400':
          description: 'Bad Request (validation failed or invalid payload). Body: `errors` array; each item has `code`, `message`, optional `field`.


            **Submit trade order — example error codes (non-exhaustive):**


            | Code | Meaning |

            |------|---------|

            | TRANSACTION_ID_REQUIRED | transactionId is required. |

            | INVALID_TIME_IN_FORCE | timeInForce value is not recognized. Valid: DAY, GTC, GTD. |

            | EXPIRE_DATE_REQUIRED | expireDate is required when timeInForce is GOOD_TIL_DATE. |

            | EXPIRE_DATE_NOT_ALLOWED | expireDate must be null when timeInForce is DAY. |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
        '503':
          description: Service Unavailable
    get:
      tags:
      - Trading
      summary: Gets All orders placed for an Account
      description: Retrieve a list of orders for the given account, filtered by query parameters when supplied.
      operationId: getOrders
      security:
      - x-api-key: []
        bearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Account identifier.
      - name: symbol
        in: query
        required: false
        schema:
          type: string
      - name: assetId
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
        description: Start of time range filter (ISO-8601).
      - name: to
        in: query
        required: false
        schema:
          type: string
        description: End of time range filter (ISO-8601).
      - name: zone
        in: query
        required: false
        schema:
          type: string
        description: Time zone identifier(America/New_York, America/Los_Angeles) for interpreting `from`/`to`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersListResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /trading/v1/accounts/{accountId}/orders/{orderId}:
    get:
      tags:
      - Trading
      summary: Retrieve a single order for the given Order Id
      description: Retrieve a single trade order by ID for the given account.
      operationId: getOrder
      security:
      - x-api-key: []
        bearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Account identifier.
      - name: orderId
        in: path
        required: true
        schema:
          type: string
        description: Order identifier.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Order not found
        '500':
          description: Internal Server Error
    delete:
      tags:
      - Trading
      summary: Attempts to a Cancel a OPEN Order
      description: Attempts to Cance a OPEN order associated to the Account Id and Order Id in the URL.
      operationId: cancelOrder
      security:
      - x-api-key: []
        bearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Account identifier.
      - name: orderId
        in: path
        required: true
        schema:
          type: string
        description: Order identifier.
      responses:
        '202':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'
        '400':
          description: Bad Request (e.g. missing orderId or transactionId).
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Order not found
        '422':
          description: Order cannot be cancelled
        '500':
          description: Internal Server Error
        '503':
          description: Service Unavailable
components:
  schemas:
    CancelOrderResponse:
      type: object
      required:
      - transactionId
      - status
      - id
      properties:
        transactionId:
          type: string
        id:
          type: string
        status:
          type: string
          enum:
          - CANCEL_REQUESTED
    FeeResponse:
      type: object
      required:
      - fee
      - status
      - feeFormatted
      properties:
        fee:
          type: number
          format: double
          description: The amount in USD which will be charged if the previously proposed trade is completed.
        feeFormatted:
          type: string
          description: A formatted string representing the amount in USD which will be charged if the previously proposed trade is completed
        status:
          type: string
          description: DEPRECATED. Text description roughly equivalent to a HTTP status code
    CreateOrderRequest:
      type: object
      required:
      - transactionId
      - symbol
      - assetId
      - side
      - timeInForce
      - type
      - quantity
      - limitPrice
      properties:
        symbol:
          type: string
        assetId:
          type: string
        side:
          type: string
          description: BUY or SELL
          enum:
          - BUY
          - SELL
        timeInForce:
          type: string
          enum:
          - DAY
          - GTD
          - GTC
          description: 'Time in Force. Accepts (DAY, GTC, GTD)

            '
        expireDate:
          type:
          - string
          - 'null'
          description: Expiration date (yyyy-MM-dd). Required only when timeInForce is GOOD_TIL_DATE; must be null for DAY/GTC.
        type:
          type: string
          enum:
          - LIMIT
        quantity:
          type: number
          format: double
        limitPrice:
          type: number
          format: double
        transactionId:
          type: string
          description: Client-provided transaction identifier for idempotency and tracing.
    OrderResponse:
      type: object
      required:
      - accountId
      - id
      - symbol
      - side
      - type
      - limitPrice
      - quantity
      - filledQuantity
      - leavesQuantity
      - averagePrice
      - timeInForce
      - estimatedFee
      - estimatedSubTotal
      - estimatedGrandTotal
      - assetClass
      - status
      properties:
        accountId:
          type: string
        id:
          type: string
        symbol:
          type: string
        side:
          type: string
          enum:
          - BUY
          - SELL
        type:
          type: string
          enum:
          - LIMIT
        limitPrice:
          type: number
          format: double
        quantity:
          type: number
          format: double
        filledQuantity:
          type: number
          format: double
        leavesQuantity:
          type: number
          format: double
        averagePrice:
          type:
          - number
          - 'null'
          format: double
        timeInForce:
          type: string
          enum:
          - DAY
          - GTD
          - GTC
          description: 'Time until the order is valid for (DAY, GTC, GTD)

            '
        expireTs:
          type:
          - string
          - 'null'
          format: date-time
          description: Optional expiration time for the order when applicable.
        estimatedFee:
          type: number
          format: double
          description: Estimated fee that will be charged if the entire order is executed for exactly the requested limitPrice. This value will become more accurate as more and more quantity are executed and we know actual amounts billed, as opposed to what is listed in limitPrice.
        estimatedSubtotal:
          type: number
          format: double
          description: The total amount a customer will pay for just the securities e.g. (limitPrice * quantity). This does not include the fee.This value will become more accurate as more and more quantity are executed and we know actual amounts billed, as opposed to what is listed in limitPrice.
        estimatedGrandTotal:
          type: number
          format: double
          description: The total amount a customer will be expected to pay ((limitPrice * quantity) + estimatedFee). This value will become more accurate as more and more quantity are executed and we know actual amounts billed, as opposed to what is listed in limitPrice.
        cumulativeFee:
          type:
          - number
          - 'null'
          format: double
          description: The total amount charged to facilitate the trade so far. If the order is only partially filled then it is expected this balance will grow with each additional partial fill, or fill.
        cumulativeSubtotal:
          type:
          - number
          - 'null'
          format: double
          description: The amount (in USD) paid so far for all fills in the order. If order was placed at a limit price of $10 for 100 units, but was able to get 10 units for $10 each, 10 units for $9, and 10 units for $8 each then the cumulative would be $170. When the remaining 70 units are filled then this balance is expected to grow. This does not include any fees charged by a broker dealer to facilitate the trade.
        cumulativeGrandTotal:
          type:
          - number
          - 'null'
          format: double
          description: The total amount (in USD) paid so far, for both the executed trsdes as well as the fee(s) charged for facilitating the exchange. This balance is expected to grow if the order is unfilled or only partially filled.
        status:
          type: string
          enum:
          - SUBMITTED
          - OPEN
          - PARTIALLY_FILLED
          - FILLED
          - CANCEL_REQUESTED
          - PENDING_CANCEL
          - CANCEL_REJECTED
          - CANCELED
          - DONE_FOR_DAY
          - EXPIRED
          - REJECTED
          - STOPPED
        createdTs:
          type:
          - string
          - 'null'
          format: date-time
        modifiedTs:
          type:
          - string
          - 'null'
          format: date-time
        assetClass:
          type: string
        executionHistory:
          type: array
          items:
            $ref: '#/components/schemas/OrderExecution'
          description: Execution history for an order.
    ErrorItem:
      type: object
      properties:
        code:
          type: string
          description: Error/validation code (e.g. DATE_OF_BIRTH_IN_FUTURE, JURISDICTION_COUNTRY_NOT_ALLOWED). See x-businessValidationErrorCodes for business logic codes.
        message:
          type: string
          description: Human-readable message.
        field:
          type:
          - string
          - 'null'
          description: Request field path when applicable (e.g. investor.dateOfBirth, investor.physicalAddress.country).
        details:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: 'Optional object that will be sent for certain error `code` and documented in the endpoint''s error table.

            '
    OrdersListResponse:
      type: object
      required:
      - orders
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/OrderResponse'
    OrderExecution:
      type: object
      required:
      - executionTs
      - cumulativeQuantity
      - leavesQuantity
      - averagePrice
      - executionResult
      properties:
        executionTs:
          type: string
          description: ISO-8601 timestamp of the execution.
        affectedQuantity:
          type:
          - number
          - 'null'
          format: double
          description: Quantity affected by this execution (fills and cancels).
        fillQuantity:
          type:
          - number
          - 'null'
          format: double
          description: Quantity filled on this execution.
        fillPrice:
          type:
          - number
          - 'null'
          format: double
          description: Price per share on this fill.
        cumulativeQuantity:
          type: number
          format: double
          description: Total filled quantity across all executions so far.
        executionResult:
          type:
          - string
          - 'null'
          enum:
          - OPEN
          - PARTIALLY_FILLED
          - FILLED
          - CANCELED
          - REJECTED
          - CANCEL_REJECTED
          - EXPIRED
          - STOPPED
          - DONE_FOR_DAY
          description: Execution result.
        leavesQuantity:
          type: number
          format: double
          description: Remaining unfilled quantity.
        averagePrice:
          type: number
          format: double
          description: Average price across all fills.
        text:
          type:
          - string
          - 'null'
          description: Execution context text.
        fee:
          type:
          - number
          - 'null'
          format: double
          description: Fee charged for this execution (in USD).
        subtotal:
          type:
          - number
          - 'null'
          format: double
          description: Execution subtotal before fees (in USD).
        grandTotal:
          type:
          - number
          - 'null'
          format: double
          description: Execution total including fees (in USD).
    ErrorResponse:
      type: object
      description: Error response body for validation and business-rule failures. Contains a list of errors; each item has code, message, and optional field (JSON path).
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
    CreateOrderResponse:
      type: object
      properties:
        transactionId:
          type: string
        id:
          type: string
        accountId:
          type: string
        symbol:
          type: string
        assetId:
          type: string
        side:
          type: string
          enum:
          - BUY
          - SELL
        quantity:
          type: number
          format: double
        type:
          type: string
          enum:
          - LIMIT
        limitPrice:
          type: number
          format: double
        timeInForce:
          type: string
          enum:
          - DAY
          - GTD
          - GTC
          description: 'Time the order is valid for (DAY, GTC, GTD)

            '
        status:
          type: string
          enum:
          - SUBMITTED
        expireTs:
          type:
          - string
          - 'null'
          format: date-time
        createdTs:
          type:
          - string
          - 'null'
          format: date-time
        modifiedTs:
          type:
          - string
          - 'null'
          format: date-time
        fee:
          type:
          - number
          - 'null'
          format: double
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-apikey
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    refreshToken:
      type: refreshToken
      in: header
      name: refreshToken