Positions & Balances

Balances and positions answer two related questions about an account: what is it worth right now, and what does it hold. This page explains the concepts behind both so you can read the API responses confidently. For the full endpoint contracts, parameters, and every field, see /reference/balances-and-positions.

All requests go to the sandbox base URL https://api.cert.tastyworks.com or production https://api.tastyworks.com, require an OAuth access token (15-minute lifetime via POST /oauth/token), and must send a User-Agent: product/version header. JSON keys are dasherized (for example net-liquidating-value). See /docs/get-started for authentication setup.

Balances

Each account has a single balance object describing its monetary values. Fetch it with:

GET /accounts/{account_number}/balances

Key fields:

Field	Meaning
`cash-balance`	Settled cash in the account. May be positive or negative.
`net-liquidating-value`	Total current value of the account — roughly the cash you would end up with if you closed every position.
`equity-buying-power`	Funds available to open equity positions.
`derivative-buying-power`	Funds available to open options (derivative) positions.
`day-trading-buying-power`	Funds available for day trades.
`maintenance-requirement`	Margin the account must maintain against current positions.
`cash-available-to-withdraw`	Cash that can be withdrawn right now.
`pending-cash` / `pending-cash-effect`	Cash mid-transfer that has not cleared. `Credit` is an incoming deposit; `Debit` is an outgoing withdrawal. Usually `0.0`.

Position values are broken out by instrument type and side, for example long-equity-value, short-equity-value, long-derivative-value (options), long-futures-value, and long-cryptocurrency-value. Margin fields such as margin-equity, reg-t-margin-requirement, and futures-margin-requirement describe the account's margin state.

A balance snapshot is captured twice daily (morning and after the equities close). Fetch one with GET /accounts/{account_number}/balance-snapshots. The time-of-day parameter (BOD for beginning of day, EOD for end of day) is required per the API spec; optionally pass snapshot-date to select a specific date.

Positions

A position records a single holding. Fetch all open positions with:

GET /accounts/{account_number}/positions

{
  "data": {
    "items": [
      {
        "account-number": "5WT00000",
        "symbol": "AAPL",
        "instrument-type": "Equity",
        "underlying-symbol": "AAPL",
        "quantity": "100",
        "quantity-direction": "Long",
        "average-open-price": "288.7",
        "close-price": "282.48",
        "multiplier": 1,
        "realized-day-gain": "0.0",
        "realized-today": "0.0"
      }
    ]
  },
  "context": "/accounts/5WT00000/positions"
}

(Some position fields omitted for brevity.)

Important fields:

symbol / underlying-symbol — tastytrade symbology covers equities, OCC options, futures (/ESZ4), future options (./ESZ4 EW3U4 240920P5650), and crypto pairs.
quantity and quantity-direction (Long, Short, Zero). A quantity of 0 is closed; closed positions are purged overnight.
average-open-price — running average open price, the cost basis for unrealized gain since open.
multiplier — notional units delivered on exercise/assignment (equity options are typically 100).
realized-today and realized-day-gain — realized profit/loss since open and for the current day, paired with *-effect and *-date fields. Ignore the value if its date is not today.

Equity option and futures positions also carry an expires-at timestamp.

Profit / loss and mark

The API does not return a live profit/loss figure. You compute it using mark (current value of one unit) against a cost basis:

Long positions:  (mark - cost-basis) * quantity * multiplier
Short positions: (cost-basis - mark) * quantity * multiplier

Use average-open-price as the cost basis for unrealized gain since open; note the operands flip for short positions. Mark is best taken from live quote data — for long positions use the bid, for short positions the ask, or the mid (bid + ask) / 2. The positions endpoint can also return point-in-time mark and mark-price fields when called with include-marks=true (off by default; can decrease performance). For live P/L, subscribe via streaming market data and recalculate as quotes change (throttling to about once per second is sensible).

Calculating net liquidating value

The net-liquidating-value returned by GET /accounts/{account_number}/balances is the authoritative figure. This section explains a client-side estimate you can recompute between balance fetches as streamed quotes move. The estimate can differ from the API figure, so use the API value as the source of truth.

Start with the current value of each position:

current value = mark * quantity * multiplier * direction

Take direction from the position's quantity-direction: 1 for Long and -1 for Short. A Zero position has a quantity of 0, so it adds 0 whichever direction you apply. Use quantity as the API returns it. The API reference does not say whether quantity is signed, so check a short position in your own account before relying on the sign; if a short position's quantity already comes back negative, do not apply direction a second time. Add up the position values, then add cash:

net liq estimate = (sum of position current values) + cash-balance

pending-cash is cash that has not cleared yet and is usually 0.0. The estimate ignores it.

Scope and limits

The formula is for equities and equity options. Futures, futures options, cryptocurrency and other instruments are not covered here.
mark is the price you supply. The example below uses a given mark. For live marks, use market data as described in the Profit/loss section above (or the positions endpoint with include-marks=true).
How the balances service itself computes net-liquidating-value, including how it treats pending-cash, is not covered here. If your figure has to match the account's value exactly, use the net-liquidating-value the API returns.

Worked example

Say the account is long 100 shares of ABC with a mark of $100, short 100 shares of XYZ with a mark of $50, and holds $1,000 cash.

Position	Calculation	Current value
ABC (long)	$100 * 100 * 1 * 1	$10,000
XYZ (short)	$50 * 100 * 1 * -1	-$5,000

The estimate is $10,000 - $5,000 + $1,000 = $6,000.

Throttle recalculation to about once per second when you drive it from streaming quotes.