openapi: 3.1.0
info:
  version: 11.24.0
  title: Margin Requirements
  description: tastytrade Margin Requirements API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
tags:
  - name: margin-requirements
paths:
  /margin/accounts/{account_number}/requirements:
    get:
      description: Returns the account's current margin and capital requirements
        report, grouped by underlying symbol. The top level summarizes the whole
        account (margin-requirement, maintenance-requirement, margin-equity,
        maintenance-excess, and buying-power figures, including separate reg-t-*
        values), while each entry under groups breaks down one underlying with
        its own requirement totals, position-entries, and price-increase-percent
        / price-decrease-percent values. Read this to understand how much of the
        account is committed to margin before placing new orders.
      parameters:
        - in: path
          name: account_number
          required: true
          schema:
            type: string
          example: 5WX01234
      responses:
        "200":
          description: The account's current margin/capital requirements report, grouped
            by underlying symbol.
          content:
            application/json: {}
        "401":
          description: Authentication failed. The Authorization bearer token is missing,
            expired (access tokens last 15 minutes), or the required User-Agent
            header is missing or malformed.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Forbidden. The token is valid but its scope or the account's
            authority level does not permit reading this account's margin
            requirements.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "404":
          description: No account was found for the supplied account_number, or the wrong
            environment was used (sandbox vs production).
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
        "429":
          description: Rate limit exceeded. Back off exponentially and reduce the request
            rate.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      tags:
        - margin-requirements
      operationId: getMarginAccountsAccountNumberRequirements
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Account Margin Requirements
  /margin/accounts/{account_number}/dry-run:
    post:
      description: Estimates the margin impact of a prospective order on the account
        without placing it. The body matches the order you would submit, plus
        account-number, underlying-symbol, and underlying-instrument-type
        (Equity, Equity Option, Future, Future Option, or Cryptocurrency). The
        response compares the account before and after via
        change-in-margin-requirement, change-in-buying-power, and the
        current-buying-power vs new-buying-power pair, with full per-underlying
        breakdowns under last-results, base-results, and new-order-results. A
        dry-run never creates an order, so it is safe to repeat; always run it
        before submitting a real order.
      parameters:
        - in: path
          name: account_number
          required: true
          schema:
            type: string
          example: 5WX01234
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - order-type
                - time-in-force
                - account-number
                - underlying-symbol
                - underlying-instrument-type
              properties:
                account-number:
                  type: string
                underlying-symbol:
                  type: string
                order-type:
                  type: string
                time-in-force:
                  type: string
                gtc-date:
                  type: string
                  format: date
                price:
                  type: string
                  format: numeric
                price-effect:
                  type: string
                  enum:
                    - Credit
                    - Debit
                stop-trigger:
                  type: string
                  format: numeric
                replaces-order-id:
                  type: string
                  format: numeric
                legs:
                  type: array
                  minItems: 1
                  maxItems: 4
                  uniqueItems: true
                  items:
                    type: object
                    required:
                      - symbol
                      - instrument-type
                      - action
                    properties:
                      symbol:
                        type: string
                      instrument-type:
                        type: string
                      quantity:
                        type: string
                        format: numeric
                      action:
                        type: string
                      remaining-quantity:
                        type: string
                        format: numeric
                underlying-instrument-type:
                  type: string
                  description: The instrument type of the underlying symbol.
                  enum:
                    - Equity
                    - Equity Option
                    - Future
                    - Future Option
                    - Cryptocurrency
                  example: Equity
        description: the order to evaluate for margin requirements
      responses:
        "200":
          description: The estimated margin impact of the order, comparing the account
            before and after, with per-underlying breakdowns.
          content:
            application/json: {}
        "401":
          description: Authentication failed. The Authorization bearer token is missing,
            expired (access tokens last 15 minutes), or the required User-Agent
            header is missing or malformed.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Forbidden. The token is valid but its scope or the account's
            authority level does not permit running a margin dry-run on this
            account.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "404":
          description: No account was found for the supplied account_number, or the wrong
            environment was used (sandbox vs production).
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
        "422":
          description: The order could not be evaluated. The body is missing required
            fields, uses non-dasherized or wrong-typed keys, or describes an
            order that is invalid in context (for example an unknown symbol).
            Read error.message for the specific reason.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: preflight_check_failure
                    message: One or more preflight checks failed
                    errors:
                      - code: preflight_check_failure
                        message: A specific validation failed for this order.
        "429":
          description: Rate limit exceeded. Back off exponentially and reduce the request
            rate.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      tags:
        - margin-requirements
      operationId: createMarginAccountsAccountNumberDryRun
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Margin Requirements Dry Run
servers:
  - url: https://api.tastyworks.com
x-tastytrade-service:
  serviceName: amargination-server
  group: margin-requirements
  title: Margin Requirements
