openapi: 3.1.0
info:
  title: Transactions
  version: 10.3.0
  description: tastytrade Transactions API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
tags:
  - name: transactions
  - name: accounts
paths:
  /accounts/{account_number}/transactions:
    get:
      description: Returns a paginated list of an account's transactions — orders,
        cash movements, position transfers, dividends, interest, and other
        ledger events. Results default to descending order (newest first); use
        the query parameters to page, sort, and filter by date range, symbol,
        instrument type, action, or transaction type. Note that `type` and
        `types` are mutually exclusive — supply one or the other, not both.
      parameters:
        - in: path
          name: account_number
          required: true
          schema:
            type: string
          example: 5WX01234
        - in: query
          name: page-offset
          required: false
          schema:
            type: integer
            format: int32
            default: 0
          example: 10
        - in: query
          name: per-page
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 2000
            default: 250
          example: 10
        - in: query
          name: currency
          description: Currency
          required: false
          schema:
            type: string
        - in: query
          name: sort
          description: The order to sort results in. Defaults to Desc, Accepts `Desc` or
            `Asc`.
          required: false
          schema:
            type: string
            enum:
              - Desc
              - Asc
            default: Desc
          example: Desc
        - in: query
          name: sub-type
          description: "Filter based on transaction_sub_type (example:
            sub-type[]={value1}&sub-type[]={value2})"
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - in: query
          name: type
          description: Filter based on transaction_type
          required: false
          schema:
            type: string
        - in: query
          name: types
          description: "Allows filtering on multiple transaction_types (example:
            types[]={value1}&types[]={value2})"
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - in: query
          name: action
          description: The action of the transaction. i.e. `Allocate`, `Buy`, `Buy to
            Close`, `Buy to Open`, `Sell`, `Sell to Close` or `Sell to Open`
          required: false
          schema:
            type: string
          example: Allocate
        - in: query
          name: end-date
          description: The end date of transactions to query. Defaults to now.
          required: false
          schema:
            type: string
            format: date
          example: 2024-01-15
        - in: query
          name: futures-symbol
          description: >-
            The full TW Future Symbol `/ESZ9` or \
                                                      `/NGZ19` if two year digit are appropriate
          required: false
          schema:
            type: string
          example: /ESZ9
        - in: query
          name: instrument-type
          description: The type of Instrument. i.e. `Bond`, `Cryptocurrency`, `Currency
            Pair`, `Equity`, `Equity Offering`, `Equity Option`, `Event
            Contract`, `Fixed Income Security`, `Future`, `Future Option`,
            `Index`, `Liquidity Pool`, `Unknown` or `Warrant`
          required: false
          schema:
            type: string
          example: Bond
        - in: query
          name: partition-key
          description: Account partition key
          required: false
          schema:
            type: string
        - in: query
          name: start-date
          description: The start date of transactions to query.
          required: false
          schema:
            type: string
            format: date
          example: 2024-01-15
        - in: query
          name: symbol
          description: >-
            The Stock Ticker Symbol `AAPL`, OCC Option Symbol
            `AAPL  191004P00275000`, \
                                                             TW Future Symbol `/ESZ9`, or TW Future Option Symbol `./ESZ9 EW4U9 190927P2975`
          required: false
          schema:
            type: string
          example: AAPL
        - in: query
          name: underlying-symbol
          description: >-
            The Underlying Symbol. The Ticker Symbol `FB` or \
                                                                          TW Future Symbol with out date component `/M6E` or
                                                                          the full TW Future Symbol `/ESU9`
          required: false
          schema:
            type: string
          example: FB
        - in: query
          name: end-at
          description: DateTime end range for filtering transactions in full date-time
          required: false
          schema:
            type: string
            format: date-time
          example: 2024-01-15T14:30:00.000Z
        - in: query
          name: start-at
          description: DateTime start range for filtering transactions in full date-time
          required: false
          schema:
            type: string
            format: date-time
          example: 2024-01-15T14:30:00.000Z
      responses:
        "200":
          description: A paginated list of transactions wrapped in the standard envelope,
            with an `items` array and a `pagination` block describing the
            current page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/Transaction"
                    required:
                      - items
                  context:
                    type: string
                    example: /accounts/{account_number}/transactions
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: "Unauthorized — the `Authorization: Bearer <token>` header is
            missing, expired, or invalid (access tokens last 15 minutes), or the
            required `User-Agent: <product>/<version>` 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 transactions.
          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: Not Found — no account matches the supplied `account_number`, or
            the wrong environment is being 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: Too Many Requests — the request rate exceeded the read rate limit.
            Back off exponentially and page steadily rather than bursting.
          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:
        - transactions
      operationId: getAccountsAccountNumberTransactions
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: List Account Transactions
  /accounts/{account_number}/transactions/total-fees:
    get:
      description: Returns the total fees charged on an account for a single day. Pass
        `date` to choose the day (defaults to today). The response reports the
        aggregated fee amount and its direction via `total-fees-effect`.
      parameters:
        - in: path
          name: account_number
          required: true
          schema:
            type: string
          example: 5WX01234
        - in: query
          name: date
          description: The date to get fees for, defaults to today
          required: false
          schema:
            type: string
            format: date
          example: 2024-01-15
      responses:
        "200":
          description: The aggregated fees for the requested day, wrapped in the standard
            envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      total-fees:
                        type: string
                        format: decimal
                        description: The total fees charged on the account for the requested day,
                          returned as a string decimal.
                        example: "100.0"
                      total-fees-effect:
                        type: string
                        description: "The direction of `total-fees`: `Credit`, `Debit`, or `None`."
                        example: Debit
                  context:
                    type: string
                    example: /accounts/{account_number}/transactions/total-fees
                required:
                  - data
                  - context
        "401":
          description: "Unauthorized — the `Authorization: Bearer <token>` header is
            missing, expired, or invalid, or the required `User-Agent:
            <product>/<version>` 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 fees.
          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: Not Found — no account matches the supplied `account_number`, or
            the wrong environment is being 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: Too Many Requests — the request rate exceeded the read rate limit.
            Back off exponentially before retrying.
          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:
        - accounts
      operationId: getAccountsAccountNumberTransactionsTotalFees
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Total Fees For A Day
  /accounts/{account_number}/transactions/{id}:
    get:
      description: Retrieves a single transaction on the account by its numeric
        transaction `id`. Use this to fetch the full detail of one ledger event
        after locating it in the list endpoint.
      parameters:
        - in: path
          name: account_number
          required: true
          schema:
            type: string
          example: 5WX01234
        - in: path
          name: id
          required: true
          schema:
            type: integer
            format: int32
          example: 1
      responses:
        "200":
          description: The requested transaction, wrapped in the standard envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Transaction"
                  context:
                    type: string
                    example: /accounts/{account_number}/transactions/{id}
                required:
                  - data
                  - context
        "401":
          description: "Unauthorized — the `Authorization: Bearer <token>` header is
            missing, expired, or invalid, or the required `User-Agent:
            <product>/<version>` 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 transactions.
          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: Not Found — no transaction matches the supplied `id` on this
            account, no account matches `account_number`, or the wrong
            environment is being 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: Too Many Requests — the request rate exceeded the read rate limit.
            Back off exponentially before retrying.
          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:
        - accounts
      operationId: getAccountsAccountNumberTransactionsId
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Transaction By ID
servers:
  - url: https://api.cert.tastyworks.com
    description: Sandbox
  - url: https://api.tastyworks.com
    description: Production
components:
  schemas:
    Transaction:
      type: object
      properties:
        id:
          description: Unique numeric identifier of the transaction within tastytrade.
          type: integer
          format: int32
          example: 252640963
        account-number:
          description: The account number the transaction belongs to.
          type: string
          example: 5WX01234
        action:
          description: The trade action, when applicable. One of `Allocate`, `Buy`, `Buy
            to Close`, `Buy to Open`, `Sell`, `Sell to Close`, or `Sell to
            Open`.
          type: string
          example: Buy to Open
        agency-price:
          description: Decimal value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
        clearing-fees:
          description: Clearing fees charged on the transaction. Decimal value serialized
            as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.02"
        clearing-fees-effect:
          description: "The direction of `clearing-fees`: `Credit`, `Debit`, or `None`."
          type: string
          example: Debit
        commission:
          description: Commission charged on the transaction. Decimal value serialized as
            a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "1.0"
        commission-effect:
          description: "The direction of `commission`: `Credit`, `Debit`, or `None`."
          type: string
          example: Debit
        lots:
          description: Cost-basis lot detail associated with the transaction, when
            available.
          type: object
          properties:
            id:
              description: ""
              type: string
            executed-at:
              description: ""
              type: string
              format: date-time
            price:
              description: Decimal value serialized as a JSON string (e.g. "150.25").
              type: string
              format: decimal
            quantity:
              description: Decimal value serialized as a JSON string (e.g. "150.25").
              type: string
              format: decimal
            quantity-direction:
              description: ""
              type: string
            transaction-date:
              description: ""
              type: string
              format: date
            transaction-id:
              description: ""
              type: integer
              format: int32
        cost-basis-reconciliation-date:
          description: ""
          type: string
          format: date
        created-at:
          description: The full date-time at which the transaction record was created
            (ISO-8601).
          type: string
          format: date-time
          example: 2024-01-12T21:00:01.000+00:00
        currency:
          description: The currency of the transaction's monetary amounts.
          type: string
          example: USD
        currency-conversion-fees:
          description: Decimal value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
        currency-conversion-fees-effect:
          description: ""
          type: string
        description:
          description: Human-readable description of the transaction.
          type: string
          example: Received 1.68074 Long KBWD via Dividend
        destination-venue:
          description: The venue to which the order was routed.
          type: string
          example: TEST_A
        exchange:
          description: The exchange on which the trade executed.
          type: string
          example: CBOE
        exchange-affiliation-identifier:
          description: ""
          type: string
        exec-id:
          description: ""
          type: string
        executed-at:
          description: The full date-time at which the transaction executed (ISO-8601).
          type: string
          format: date-time
          example: 2024-01-12T21:00:00.000+00:00
        ext-exchange-order-number:
          description: ""
          type: string
        ext-exec-id:
          description: ""
          type: string
        ext-global-order-number:
          description: ""
          type: integer
          format: int32
        ext-group-fill-id:
          description: ""
          type: string
        ext-group-id:
          description: ""
          type: string
        instrument-type:
          description: The instrument type, such as `Bond`, `Cryptocurrency`, `Equity`,
            `Equity Offering`, `Equity Option`, `Future`, `Future Option`,
            `Index`, `Unknown`, or `Warrant`.
          type: string
          example: Equity
        is-estimated-fee:
          description: Whether the fees on this transaction are estimated rather than final.
          type: boolean
          example: true
        leg-count:
          description: The number of legs in the originating order, when the transaction
            stems from a trade.
          type: integer
          format: int32
          example: 1
        net-value:
          description: The net monetary value of the transaction after fees and
            commissions, returned as a string decimal. Decimal value serialized
            as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "27.74"
        net-value-effect:
          description: "The direction of `net-value`: `Credit`, `Debit`, or `None`."
          type: string
          example: Credit
        order-id:
          description: The identifier of the order that produced this transaction, when
            applicable.
          type: integer
          format: int32
          example: 987654321
        other-charge:
          description: Decimal value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
        other-charge-description:
          description: ""
          type: string
        other-charge-effect:
          description: ""
          type: string
        price:
          description: The per-unit price of the instrument for this transaction. Decimal
            value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "16.46"
        principal-price:
          description: Decimal value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
        proprietary-index-option-fees:
          description: Decimal value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
        proprietary-index-option-fees-effect:
          description: ""
          type: string
        quantity:
          description: The quantity of the instrument involved in the transaction. Decimal
            value serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "1.68074"
        regulatory-fees:
          description: Regulatory fees charged on the transaction. Decimal value
            serialized as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "0.03"
        regulatory-fees-effect:
          description: "The direction of `regulatory-fees`: `Credit`, `Debit`, or `None`."
          type: string
          example: Debit
        reverses-id:
          description: ""
          type: integer
          format: int32
        symbol:
          description: The instrument symbol associated with the transaction (e.g. equity
            ticker, OCC option symbol, or future/future-option symbol).
          type: string
          example: AAPL
        transaction-date:
          description: The ledger date of the transaction (ISO-8601 date).
          type: string
          format: date
          example: 2024-01-12
        transaction-sub-type:
          description: The finer-grained sub-type, such as `Dividend`, `Deposit`,
            `Withdrawal`, `Credit Interest`, `Debit Interest`, `Assignment`,
            `Exercise`, `Expiration`, `Fee`, or `Transfer`.
          type: string
          example: Dividend
        transaction-type:
          description: "The high-level category of the transaction: `Administrative
            Transfer`, `Money Movement`, `Receive Deliver`, or `Trade`."
          type: string
          example: Trade
        underlying-symbol:
          description: The underlying symbol for the transaction's instrument — the ticker
            for equities/options, or the future contract code for futures.
          type: string
          example: AAPL
        value:
          description: The gross monetary value of the transaction before fees and
            commissions, returned as a string decimal. Decimal value serialized
            as a JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "27.74"
        value-effect:
          description: "The direction of `value`: `Credit`, `Debit`, or `None`."
          type: string
          example: Credit
      description: A single event in an account's history that changed its balances or
        positions — for example a trade fill, cash deposit or withdrawal,
        position transfer, dividend, or interest credit. Monetary amounts are
        returned as string decimals paired with a separate `*-effect` field
        indicating Debit, Credit, or None.
x-tastytrade-service:
  serviceName: account-history-api
  group: transactions
  title: Transactions
