API Architecture & Design

Understanding Tradovate’s Partner API architecture helps you build robust, scalable integrations that leverage our high-performance trading infrastructure.

Architecture Overview

The Tradovate Partner API is built on a modern, cloud-native architecture designed for institutional-grade trading operations:

Core Design Principles

Operation-Based Design

Our API follows operation-based patterns with predictable endpoint structures:

Common Operations: These GET query operations are common across most entity types. Familiarize yourself with these requests as they will be some of the most common requests you make during your integration.

GET /[entity]/item?id={id}        # Get specific entity by ID
GET /[entity]/list                # List all entities
GET /[entity]/find?name={name}    # Find entity by name
GET /[entity]/deps?masterid={id}  # Get dependent entities
GET /[entity]/items?ids={id1,id2} # Get multiple entities by IDs

Action Operations:

POST /user/createEvaluationAccounts # Create new account entities
POST /entity/update                 # Update existing entity

Real-Time Data Streaming

Real-time updates are a core service of our API. You can run your whole application from WebSocket instances. We now support “socket sharding” as well, to assist in recording and handling large amounts of real-time data. Our WebSocket protocol is new-line delimited (\n), where each line represents a separate parameter of the request.

WebSocket Message Format

1
<ENDPOINT_NAME>\n<REQUEST_ID>\n<QUERY_PARAMETERS>\n<JSON_BODY>

Example Message:

1
// Get details on a list of accounts
2
ws.send(
3
  'account/items\n1\n\n{"ids": [123456, 234567, 345678]}'
4
);

For more information on real time data access, see the Websockets section.

Response Format: Websocket responses are one of 4 characters:

• o: open frame. Every time a new session is established, the server must immediately send the open frame.
• a: data frame, this message is always followed by a JSON array
• h: heartbeat frame, basically a ping. The server sends a heartbeat about every 2.5 seconds. To keep the connection alive the client must also send a response beat in the form of an empty array, stringified (’[]’)
• c: close frame

Each of the a data frames will be followed by a JSON array. There are two main types of message you can receive from the server - real-time event messages, and request-response messages.

Server Event Message

An event message has the following structure:

1
{
2
  "e":"props",
3
  "d":{
4
    "entityType":"order",
5
    "eventType":"Created",
6
    "entity":{
7
      "id":210518,
8
      "accountId":25,
9
      "contractId":560901,
10
      "timestamp":"2016-11-04T00:02:36.626Z",
11
      "action":"Sell",
12
      "ordStatus":"PendingNew",
13
      "admin":false
14
    }
15
  }
16
}

The “e” field specifies an event kind:

• "props": this is a notification that some entity was created, updated or deleted. The "d" field in this case specifies details of the event with the next structure:

  • "entityType" field
  • "entity" field. JSON structure of object (or array of objects) specified in this field is identical to JSON of entity that accessible via corresponding REST API request like entityType/item. For example, if entityType=account, JSON can be found in the response specification of account/item call
  • "eventType" field with options "Created", "Updated" or "Deleted"

• "shutdown": a notification before graceful shutdown of connection. For this type "d" field specifies details:

  • "reasonCode" field with options "Maintenance", "ConnectionQuotaReached", "IPQuotaReached"
  • "reason" field is optional and may contain a readable explanation

• "md" and "chart": these notifications are used by market data feed services. Their "d" fields will be described in the Market Data section of WebSockets.

• "clock": Market Replay clock synchronization message. See the Market Replay section below.

Response Message

A response message is issued when a client makes a request. These messages are intended to mimic REST API responses and have the following structure:

1
{
2
  "i":26,
3
  "s":200,
4
  "d":{
5
    "id":478866,
6
    "name":"6EZ6",
7
    "contractMaturityId":23574
8
  }
9
}

• "i" field is a id of corresponding client request (see “Client requests” below). A responses id will always match the id of the request that generated it.
• "s" field is a HTTP status code of response
• "d" field is a content of response. If HTTP status is 2xx, this field contains JSON response as defined in Swagger specification of the corresponding request. Otherwise, “d” is a string representation of error text.

Error Handling Architecture

Error Classification

The Tradovate Partner API uses a consistent error handling pattern across all endpoints. Errors are communicated through HTTP status codes and structured response fields.

REST Response Types

We follow typical HTTP status code format for most responses. See Error Handling for more details.

Standard Error Response Format

Most API errors that send a 200 level response return JSON containing the errorText field. This is the standard error response structure used throughout the API:

1
{
2
  "errorText": "Invalid access token",
3
  "accessToken": null
4
}

API Usage Patterns & Conventions

The Tradovate API exposes data with fine granularity to avoid limiting how applications compose them. It’s the responsibility of client applications to request all needed dependencies and join them.

Query Data Operations

All data query operations use HTTP GET method when called via REST API.

Query by ID

All entities have unique IDs and can be requested using the item operation:

$
curl -X GET \
>
  --header 'Accept: application/json' \
>
  --header 'Authorization: Bearer YOUR_TOKEN' \
>
  'https://demo.tradovateapi.com/v1/order/item?id=1000'

Query All Entities

Use the /list endpoint to retrieve all entities of a particular type:

$
curl -X GET \
>
  --header 'Accept: application/json' \
>
  --header 'Authorization: Bearer YOUR_TOKEN' \
>
  'https://demo.tradovateapi.com/v1/fill/list'

Query by Master-Detail Relationship

Use the deps operation to load dependent entities. The masterid parameter should be the ID of the master entity:

$
curl -X GET \
>
  --header 'Accept: application/json' \
>
  --header 'Authorization: Bearer YOUR_TOKEN' \
>
  'https://demo.tradovateapi.com/v1/position/deps?masterid=123'

Query by Name

Some entities (accounts, products, contracts, currencies) have names and can be found using the find operation:

$
curl -X GET \
>
  --header 'Accept: application/json' \
>
  --header 'Authorization: Bearer YOUR_TOKEN' \
>
  'https://demo.tradovateapi.com/v1/product/find?name=ES'

Batch Operations

For efficiency, replace multiple item operations with one items operation using comma-separated IDs:

$
curl -X GET \
>
  --header 'Accept: application/json' \
>
  --header 'Authorization: Bearer YOUR_TOKEN' \
>
  'https://demo.tradovateapi.com/v1/contract/items?ids=840972,840944'

Note: The number of returned entities may be less than requested IDs (if not found), and order is not guaranteed.

Error Handling Patterns

The API uses two methods to communicate errors:

HTTP Status Codes

Used for request-level errors:

• 401 - Unauthorized (invalid token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (resource doesn’t exist)
• 429 - Too Many Requests (rate limited)
• 500 - Internal Server Error

Business Logic Errors

Communicated via errorText field in successful HTTP responses:

1
{
2
  "errorText": "Insufficient buying power for this order",
3
  "orderId": null,
4
  "timestamp": "2024-03-15T14:30:00Z"
5
}

Best Practices

Performance Optimization

1. Minimize API calls - API calls are rate-limited. Although this structure is flexible, to prevent disruptions consider the following:

   • Use batch endpoints where possible
   • Implement efficient caching
   • Optimize database queries by storing relevant entries in your database.
   • In many cases it can help to create an in-memory map of relevant entities.

2. Handle rate limits gracefully

   • See Rate Limits & Best Practices

Next Steps

Now that you understand our architecture:

1. Rate Limits & Best Practices - Learn usage limits and optimization
2. Error Handling - Implement robust error handling
3. WebSocket Connections - Real-time data streaming