Accounts & Customers

Almost everything you do with the tastytrade API happens in the context of a customer and one of their accounts. Understanding that relationship is the key to navigating the rest of the reference: it tells you which path parameters an endpoint expects and which account a request will actually touch.

The customer → accounts model

A customer is the authenticated person (or entity) behind an access token. A customer has one or more accounts — for example, an individual margin account, a retirement account, and so on. Each account is identified by its account-number (e.g. 5WT00001), and the vast majority of trading, balances, positions, and order endpoints operate on a single account at a time, addressed by that account number.

So the typical flow after you authenticate is:

1. Read the customer (optional — mostly for profile/suitability data).
2. List the customer's accounts to discover their account-number values and your authority over each.
3. Make subsequent calls against a specific account-number.

The me shortcut

For simplicity and security, tastytrade does not expose a customer's internal identifier through the API. Wherever a customer endpoint takes a customer_id path parameter, the only accepted value is me, which resolves to the customer linked to the access token you authenticated with.

GET /customers/me
GET /customers/me/accounts
GET /customers/me/accounts/{account_number}

GET /customers/me returns the customer's profile, including address, contact, suitability, and identity data. GET /customers/me/accounts lists every account the customer can access. You can fetch a single account directly with GET /customers/me/accounts/{account_number} (note that {account_number} is a path parameter — substitute the real account number).

curl -s https://api.cert.tastyworks.com/customers/me/accounts \
  -H "Authorization: Bearer <access_token>" \
  -H "User-Agent: my-app/1.0.0"

Use the sandbox base URL https://api.cert.tastyworks.com while developing and https://api.tastyworks.com for production. Every request must send a User-Agent header in the form <product>/<version>, and OAuth access tokens are short-lived (15 minutes) — refresh them via POST /oauth/token. See Get started for the full handshake.

Authority levels

Listing accounts returns an authority-level for each one, describing what the authenticated customer is allowed to do with that account. The account itself lives under an account object; the authority is reported alongside it.

Always check the authority level before attempting a write. A read-only or trade-only authority will cause money-moving or trading requests to be rejected — typically with a 403 (see error codes).

{
  "account": {
    "account-number": "5WT00001",
    "nickname": "Individual",
    "account-type-name": "Individual",
    "margin-or-cash": "Margin",
    "is-closed": false,
    "is-futures-approved": true
  },
  "authority-level": "owner"
}

Responses use dasherized JSON keys (account-number, authority-level), and account-scoped collections are wrapped in a data.items array with a context echoing the request path.

Acting on an account

Once you have an account-number, you can read balances and positions and place orders against it. Because orders move money, follow the standard discipline: dry-run first, then submit the live order with a unique client-supplied external-identifier. The API does not deduplicate retried submissions and there is no idempotency-key header — if a submission times out or fails ambiguously, check GET /accounts/{account_number}/orders for your identifier before resubmitting. See Idempotency & retries and Rate limits & backoff.

Reference

For the full request/response schemas of these endpoints, see Accounts & Customers in the API reference and the broader reference.