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:

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).

Related topics

• Money-moving (orders) is separate from these read-only endpoints. Always submit a dry-run first and set a unique client-supplied external-identifier on the order. The API does not deduplicate retried submissions (there is no idempotency-key header), so on an uncertain outcome check your live orders for that identifier before resubmitting — see /docs/guides/idempotency-and-retries.
• Error responses use standard codes (400/401/403/404/422/429/5xx); see /reference/errors.
• Back off on 429 per /docs/guides/rate-limits-and-backoff.
• The MCP server exposes balances and positions to agents.