tastytrade API Overview

1. API Conventions (REST / JSON)
2. Auth Patterns
   1. Session Tokens
   2. Authorization Header
   3. Two Factor Authentication
3. tastytrade Symbology
4. Error Codes
5. High-level Concepts

API Conventions (REST / JSON)

Headers

All requests must include a User-Agent header or they will be rejected. The format muse be <product>/<version>. The product and version you choose does not matter as long as it is submitted in the proper format. Most people make it specific to the client they are using, like tastytrade-api-client/1.0 or my-custom-client/2.0.

Content-Type and Accept headers should be application/json since requests and responses will always be in json format.

Parameters

Json keys are dasherized in the request and response body. For example:

{
  "this-key-is-dasherized": "value goes here"
}

GET requests must send parameters in the url (i.e. query parameters). Some GET endpoints have a parameter of type Array[String]. These must be provided in the format my-key[]=value. If you wanted to send multiple values, you would simply repeat the key: my-key[]=value1&my-key[]=value2.

For all other HTTP methods (POST, PUT, PATCH, DELETE), use a json body. Remember to dasherize-the-parameter-names:

{
  "underlying-symbol": "AAPL",
  "quantity": 1,
  "time-in-force": "Day"
  // other params here
}

Response Schema

Response json will have a data key and a context key. Multi-object responses will have an items array nested inside the data object:

  {
    "data": {
      "items": [
        /* list of json objects */
      ]
    },
    "context": "/accounts/{account_number}/positions"
  }

Error responses will include an error object with code and message properties:

{
  "error": {
    "code": "not_permitted",
    "message": "User not permitted access"
  }
}

Auth Patterns

Session Tokens

All requests to the tastytrade API are authenticated with a session token representing a single session initiated by a given user. This token is generated by the POST /sessions endpoint.

For detailed instructions on creating a session, see our Create a Session API guide.

A session token is valid for 24 hours or until the user invalidates the session via DELETE /sessions. Invalidating the session token will also invalidate the remember token.

There is currently no session extension beyond 24 hours. Your client application should anticipate that a session token will expire at some point and either:

1. Include a workflow for the customer to provide their credentials and log back in by creating a new session.
2. Make use of remember tokens for creating a new session.

For detailed instructions on how create and redeem a remember token, see our Remember Tokens API guide.

Your client application should not retain a server-side copy of customer credentials.

Authorization Header

All requests to the tastytrade api are authenticated via the Authorization header on the request. The Authorization header's value should be the full session-token provided by the tastytrade API with no additional text. Users should not include the word Bearer in the header value. For example:

Authorization: YkF_8uB6tiiGKF2hNRZ4QVs6gLr-d6DMn-Hovg9FrU9-8pCJLCnu8A+C

Requests that do not include the Authorization header will receive an Http 401 response code (Unauthorized).

Requests with an expired session token in the Authorization header will also receive an Http 401 response code.

Two Factor authentication

Some api requests may require a two factor authentication (2FA) code. A 2FA code is included in the request via a custom header named X-Tastyworks-OTP.

Accounts can enable 2FA through the tastytrade account management site. 2FA codes are obtained via something like an authenticator app or a text message. These codes are one-time use only.

For example, assuming you have enabled 2FA for login, your request would look something like this:

curl -X POST https://api.cert.tastyworks.com/sessions \
  -H "X-Tastyworks-OTP: 123456" \
  -H "Content-Type: application/json" \
  -d '{ "login": "myusername", "password": "mypassword" }'

$headers = @{
  "X-Tastyworks-OTP" = "123456"
}
$response = Invoke-WebRequest -Uri "https://api.cert.tastyworks.com/sessions" `
  -Method Post `
  -Headers $headers `
  -ContentType "application/json" `
  -Body "{ `"login`": `"myusername`", `"password`": `"mypassword`" }"

If you leave out the 2FA code or submit an invalid code, you will get an http 401 response like this:

{
    "error": {
        "code": "invalid_credentials",
        "message": "You must provide a valid two factor code."
    }
}

tastytrade Symbology

Equities

Equity symbols contain only alphanumeric characters (A-Z, 0-9) with an occasional /. A few examples: AAPL BRK/A

Equity Options

tastytrade uses the same conventions as the OCC for equity option symbols. In short, there are 4 pieces that make up an equity option symbol:

1. Root symbol - 6 alphanumeric digits with whitespace padding.
   • AAPL  
   • FB    
   • BRK/A 
2. Expiration date - 6 numeric digits with format yymmdd.
3. Option type - P or C
4. Strike price - 8 numeric digits front-padded with 0s. No decimals. Multiply strike by 1000.
   • 64.0 strike: 00064000
   • 1050.55 strike: 01050550
   • 0.50 strike: 00000500

Example equity option symbols:

AAPL June 17, 2022 150 Put: AAPL 220617P00150000

SPY Nov 18, 2022 400 Call: SPY 221118C00400000

SPX May 20, 2022 4025 Call: SPXW 220520C04025000

Futures

Futures symbols always start with a slash followed by the contract code. The contract code consists of 3 things: the product code (A-Z), the month code, and a 1-2 digit number for the year. For a full list of futures products that we support, hit the List Future Products endpoint. Each item in the response has a code, which is the product code.

E-mini S&P 500 December 2022: /ESZ2

Crude Oil December 2022: /CLZ2

CBOE Volatility Index November 2022: /VXX22

You can find a list of all month codes here.

Future Options

Future options are different from equity options in that each future option expiration series has a unique product code. For example, monthly CL future options have a product code LO. Weekly CL options have product codes LO1, LO2, LO3, LO4, and LO5 where LO1 is the first Friday of the month, LO2 is the second Friday of the month, etc.

Other future products may have weekly options for any day of the week with their own set of option product codes. For example, ES has weekly Monday options with product codes E1A, E2A, E3A, E4A, E5A.

Both the future product code and the future option product code will be present in a future option symbol. The future option symbol will always start with a ./, followed by the future contract code, the option contract code, the expiration date, option type (C/P), and strike price. Here are some examples:

./CLZ2 LO1X2 221104C91

LO1X2 means it's a November weekly option product. CLZ2 means this option settles into the December CL future contract, which expires 2022-11-21. The 221104C91 means it's a Call option at the 91 strike expiring 2022-11-04.

./ESZ2 E1AZ2 221205P3720

The option contract code is E1AZ2. Future contract code is ESZ2. The option product code is E1A, which is a weekly Monday product. So this is a 2022-12-05 Put at the 3720 strike which settles into the December ES Future contract.

For a full list of future option products that we support, hit the List Future Option Products endpoint. Each item in the response has a root-symbol, which is the product code.

Cryptocurrencies

Cryptocurrency symbols can be found via GET /instruments/cryptocurrencies in the symbol field of the response data. Some examples:

BCH/USD - Bitcoin cash

BTC/USD - Bitcoin

Error Codes

400 - Invalid request. Often indicates that your request body has missing or invalid parameters.

401 - Authorization token has expired or is invalid. Also indicates an invalid username/password when logging in.

403 - User is not authorized to access this resource. This may occur when a customer tries to access data for an account belonging to a different customer, for example.

404 - Endpoint or resource not found. This may occur when attempting to fetch data that does not exist (a specific order, for example).

422 - Unprocessable content. This occurs when the action you are performing is invalid, depending on the context. For example, our order system will return a 422 with a message in the response json if your order was rejected.

429 - Too Many Requests. This occurs when you send a high amount of requests in a short period of time to the point where it exceeds reasonable thresholds.

500 - Indicates an issue with tastytrade's servers. Returns a support identifier that our team can use to track down the issue.

High-level Concepts

Orders

Orders are the mechanism by which you trade. They are also how you manage your positions. Each order can have a maximum of 4 legs. Each leg has a symbol, a quantity, and an action.

The action includes both a direction (buy/sell) and an effect (open/close). Open means "Increase my position." Close means "Decrease my position."

In other words, an opening order will increase the quantity of your position (if you don't have a position, a new one will be created when the order fills). A closing order will decrease the quantity of your exiting position.

For example, to buy 100 shares of AAPL stock, you would submit an order with a single leg. The leg's symbol would be AAPL. The leg's quantity would be 100. The leg's action would be Buy to Open, meaning you are buying with the intent to open a new position. When this order fills, tastytrade creates a position in your account with a quantity of 100, a direction of Long, and a symbol of AAPL.

If you then decide to sell 10 shares of AAPL stock, you'd submit an order with a single leg. The leg's symbol would again be AAPL. The leg's quantity would be 10. The leg's action would be Sell to Close, meaning you are closing 10 shares of your existing position. When this order fills, tastytrade adjusts your position quantity down by 10, leaving you with 90 long shares.

It is perfectly acceptable to close out your entire position in a single order. If you are long 100 shares of AAPL, you can close them all by submitting an order to Sell to Close 100 shares.

It is perfectly acceptable to submit an opening sell order. Most call this "selling short." This type of order will result in a position with a Short direction. Please note you cannot Sell to Open if you have an existing Long position. Likewise you cannot Buy to Open if you have an existing Short position. Holding both a long and short position is not permitted at tastytrade.

For a detailed overview of how to structure and submit an order, head to the Order Submission page.

Orders have a status once they are submitted. The tastytrade order status lifecycle is explained in detail on the Order Flow page.

Positions

A position is created/adjusted when an order fills. Positions have a symbol, a quantity, and a direction.

You cannot create multiple positions with the same symbol. For example, you cannot simultaneously be long AAPL stock and short AAPL stock. If you are long AAPL stock and submit a sell order, the quantity of your position will decrease until it hits zero. If you continue to sell stock after hitting 0, the direction of your position will flip from long to short. Position quantity is always a positive number.

See our Account Positions Api Guide for more information.

Accounts

Your account is tied to almost every api endpoint. You can open multiple accounts, but each api endpoint will operate on a single account. You cannot submit an order to multiple accounts in a single http request.

See our Customer Account Information Api Guide for more information.

Trading Statuses

Each tastytrade account is linked to a single trading status. The trading status gives information on what privileges your account has, such as futures trading, crypto trading, options trading strategies, etc.

See our Account Trading Status Api Guide for more information.

Balances

Each tastytrade account is linked to a single account balance. The account balance gives current information about cash, buying power, the value of long and short positions, net liquidating value, and other data.

Your account balance is updated when events like order fills and cash deposits occur.

See our Account Balances Api Guide for more information.

Transactions

tastytrade maintains a historical ledger of each account activity that affects your balance. We create a transaction for each of these account activities. Some examples include order fills, dividends, fees, cash deposits, cash withdrawals, etc.

See our Account Transactions Api Guide for more information.

Instruments

An instrument is a single tradeable security, such as an equity, equity option, future, future option, or cryptocurrency. Each has a unique symbol by which it is identified. The symbol is used when submitting an order and when positions are created.

See our Instruments Api Guide for more information.