POST Flatten Positions
- NT8
- Tradovate
Flatten positions by account and/or instrument NT8
Flatten allows for flattening all positions and orders in an account or for a specific instrument in an account. Differs from Flatten Everything, which flattens all positions and order in all accounts for all instruments.
Endpoint
POST /v1/api/accounts/{account}/positions/flatten
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <token> |
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account | string | Required | Name of account in NT8 |
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
instrument | string | Optional | If provided, only flatten positions for this instrument. |
marketPosition | string | Optional | If provided, only flatten positions matching this side: "Long" or "Short". Can be combined with instrument. |
cancelOrders | boolean | Optional | If true, explicitly cancels all remaining working orders for the account (and instrument, if specified) after the flatten call. Default: false. Recommended for sim accounts where NT8's native flatten does not reliably cancel attached stop/target orders. |
Code examples
- Python
- JavaScript
- cURL
import requests
token = 'my-secret-token'
url = "https://app.crosstrade.io/v1/api/accounts/Sim101/positions/flatten"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
data = {}
try:
response = requests.post(url, headers=headers, json=data)
print(f"Response Code: {response.status_code}, Response Text: {response.text}")
except Exception as e:
print(f"An error occurred: {e}")
const token = 'my-secret-token';
const url = "https://app.crosstrade.io/v1/api/accounts/Sim101/positions/flatten";
fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({})
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
TOKEN="my-secret-token"
curl -X POST "https://app.crosstrade.io/v1/api/accounts/Sim101/positions/flatten" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Response
- 200
- 400
- 401
- 403
- 408
- 429
- 500
{
"success": true,
"pending": true,
"verified": false,
"canceledOrders": ["example-order"],
"closedPositions": [],
"closingPositions": [
{
"type": "NinjaTrader.Cbi.Position",
"account": "Sim101",
"instrument": "MES 12-25",
"instrumentType": "Future",
"marketPosition": "Short",
"quantity": 1,
"averagePrice": 5803.25,
"marketPrice": 5802.0,
"unrealizedProfitLoss": 6.25,
"tag": null
}
],
"closeRequests": [
{
"success": true,
"pending": true,
"verified": false,
"disposition": "pending",
"remainingQuantity": 1,
"account": "Sim101",
"instrument": "MES 12-25"
}
]
}
{
"error": "The request timed out, please check connection to NT8 Add-On."
}
{
"error": "Invalid bearer token"
}
{
"error": "Endpoint not available"
}
{
"error": "Client not ready to receive requests, disconnected."
}
// retryAfter is integer seconds; also sent as Retry-After.
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
{
"success": false,
"error": "internal_error"
}
Success field types
Close-verification fields depend on the add-on version and whether a close is still pending.
| Field | Type | Description |
|---|---|---|
success, pending, verified | boolean | Overall outcome and optional verification flags. |
canceledOrders | array of strings | Cancelled order IDs. |
closedPositions, closingPositions | array of objects | Confirmed-flat and still-closing positions. |
closedPositions[], closingPositions[] | object | NT8 position fields. |
closeRequests | array of objects | Optional per-position close outcomes. |
closeRequests[].account, closeRequests[].instrument, closeRequests[].disposition | string | Position identity and close disposition. |
closeRequests[].success, closeRequests[].pending, closeRequests[].verified | boolean | Per-position outcome and verification. |
closeRequests[].remainingQuantity | integer | Remaining position size. |
warning | string | Optional warning. |
Platform nuances
A close is submitted first and confirmed second. closedPositions lists only positions the
add-on saw reach flat before it answered. Anything still working is listed in
closingPositions with overall pending: true and verified: false. Each entry in
closeRequests reports its remainingQuantity and verification state. Poll
GET Positions to confirm the final state.
Overlapping close requests for the same account and instrument join the operation already
running instead of starting a second one, so a retry cannot leave two closing orders in the
market. When a close cannot be completed safely the response carries an error code, such
as close_in_progress or close_needs_reconciliation, with a detail message, and no
further order is sent.
cancelOrders: true mattersClosing a position cancels the resting orders on that same instrument first. cancelOrders: true additionally sweeps working orders on instruments that are already flat, which is what
you want when a stop or target is left over from a position that closed earlier. If you need
a guaranteed clean exit on a single instrument, this is the correct pattern:
{
"instrument": "ES 12-26",
"cancelOrders": true
}
Flatten Everything always cancels orders explicitly and does not require this flag.
WebSocket API
This request can also be made over the WebSocket API. The account path parameter and request body fields are all passed inside args.
{
"action": "rpc",
"id": "my-request-id",
"api": "Flatten",
"args": {
"account": "Sim101",
"instrument": "ES 12-26"
}
}
Flatten positions by account and/or instrument Tradovate
Flattens positions on one linked Tradovate account, optionally filtered by instrument and side. The request executes server-side through the same validation and controls as a Tradovate webhook signal, including field validation, Account Manager locks, and Trade Copier fan-out.
Endpoint
POST /v1/api/tv/accounts/{account}/positions/flatten
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Bearer <token> |
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account | string | Required | Tradovate account name, such as DEMO12345678 |
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
instrument | string | Optional | Continuous (ES1!), NT8 (ES 12-26), or Tradovate (ESZ6) instrument filter |
marketPosition | string | Optional | Position-side filter: long or short; can be combined with instrument |
An empty body flattens every position on the specified account. Tradovate does not use the NT8
cancelOrders body field on this endpoint.
Code examples
- Python
- JavaScript
- cURL
import requests
token = 'my-secret-token'
url = "https://app.crosstrade.io/v1/api/tv/accounts/DEMO12345678/positions/flatten"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
data = {
"instrument": "ES1!"
}
try:
response = requests.post(url, headers=headers, json=data)
print(f"Response Code: {response.status_code}, Response Text: {response.text}")
except Exception as e:
print(f"An error occurred: {e}")
const token = 'my-secret-token';
const url = "https://app.crosstrade.io/v1/api/tv/accounts/DEMO12345678/positions/flatten";
const data = {
instrument: "ES1!"
};
fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify(data)
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
TOKEN="my-secret-token"
curl -X POST "https://app.crosstrade.io/v1/api/tv/accounts/DEMO12345678/positions/flatten" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"instrument": "ES1!"}'
Response
- 200
- 400
- 401
- 403
- 429
- 500
- 502
- 503
{
"success": true,
"destination": "tradovate",
"api": "flatten_filtered",
"account": "DEMO12345678",
"instrument": null,
"durationMs": 904,
"response": {
"flattened": 1,
"positions": [
{
"accountId": 12345678,
"contractId": 1234,
"netPos": 1,
"success": true
}
]
}
}
{
"destination": "tradovate",
"api": "flatten_filtered",
"account": "DEMO12345678",
"instrument": "ESZ6",
"durationMs": 6103,
"success": false,
"error": "Failed to flatten 1 of 1 position(s).",
"response": {
"flattened": 0,
"positions": [
{
"accountId": 12345678,
"contractId": 1234,
"netPos": -1,
"success": false,
"error": "Tradovate returned an unexpected response, so this order's outcome could not be confirmed. Check your orders and positions in Tradovate before sending it again."
}
],
"error": "Failed to flatten 1 of 1 position(s)."
}
}
{
"success": false,
"error": "inactive_subscription"
}
{
"success": false,
"error": "tradovate_not_linked"
}
// retryAfter is integer seconds; also sent as Retry-After.
{
"success": false,
"error": "rate_limited",
"detail": "CrossTrade API rate limit exceeded (180 requests/min per user). Retry after 1s.",
"retryAfter": 1
}
{
"success": false,
"error": "internal_error"
}
{
"success": false,
"error": "tradovate_unavailable",
"detail": "Tradovate is temporarily unavailable. Please try again shortly."
}
{
"success": false,
"error": "temporarily_disabled"
}
Success field types
| Field | Type | Description |
|---|---|---|
success | boolean | Overall outcome. |
destination, api, account | string | Dispatcher and target account. |
instrument | string or null | Optional instrument filter. |
durationMs | integer | Duration in milliseconds. |
response | object | Flatten results. |
response.flattened | integer | Flattened position count. |
response.detail | string | Optional explanatory message. |
response.positions | array of objects | Per-position outcomes; may be empty. |
response.positions[].accountId, response.positions[].contractId, response.positions[].netPos | integer | Account, contract and signed net quantity. |
response.positions[].success | boolean | Per-position outcome. |
Failure response fields
An HTTP 400 response can retain the dispatcher envelope and per-position results. Inspect response.positions[] for individual outcomes. An unconfirmed liquidation is not proof that the position stayed open; check current orders and positions before retrying.
| Field | Type | Description |
|---|---|---|
success | boolean | false for the failed request. |
error, response.error | string | Overall failure summary. |
response.flattened | integer | Reported flattened-position count. |
response.positions | array of objects | Per-position results, with the identifiers and quantities listed above. |
response.positions[].success | boolean | Individual position outcome. |
response.positions[].error | string | Failure message for the position, when present. |
Platform nuances
- Tradovate uses lowercase
long/shortvalues formarketPosition, unlike NT8'sLong/Short. - Tradovate accepts three instrument naming forms.
- Account Manager and Trade Copier behavior is applied by the shared dispatcher.
- Use
POST /v1/api/tv/positions/flattento liquidate positions and cancel working orders across every linked Tradovate identity.
See the Tradovate API overview for the full field grammar, mutation safety guarantees, and error table.