Developers menu

Your positions

All the account's positions with catalogue (the kinds and their legs, every condition with its unit, default threshold and range, the label counts and the alert defaults); with id, one position.

GET/api/positions

Plan ORDERSKey scope ordersLimit 20,000 calls a day on Orders API, 100,000 on Orders Team, per accountVersion 1.0.0Since 2026-10-04

This endpoint serves

ORDERS: POSITIONS panel and editor

Plan: ORDERS. Free on every finished session. Today's ledger, live, and the live POSITIONS check are the ORDERS plan. Pricing.

Parameters

Name	What it does	Default	Error
idquery · string	One position, `p_...`.		`not_found`

Response

{ positions, max, catalogue }, or { position } with id.

Field	Meaning	Unit
positionsarray	Up to `max`.
positions[].idstring	`p_...`, given by `add`.
positions[].kindcondor \| strangle \| put_spread \| call_spread	`condor`, `strangle`, `put_spread` or `call_spread`.
positions[].legsobject	The strikes, rising, as the kind needs them.
positions[].legs.lpnumber	Long put.
positions[].legs.spnumber	Short put.
positions[].legs.scnumber	Short call.
positions[].legs.lcnumber	Long call.
positions[].entrystring	Entry minute, `HH:MM` ET.
positions[].conditionsarray	`[{ id, on, threshold }]`: which conditions count, and where they switch on.
positions[].labelobject	`{ caution, skip }`: how many conditions on make each label.
positions[].alertobject	`{ channel: telegram \| email \| webhook \| off, url, before }`: where the alerts go and how many minutes before entry they start.
positions[].sessionstring	`YYYY-MM-DD`: the session the strikes were set against.
maxinteger	Positions an account may keep (5).
catalogueobject	Kinds, conditions, label counts and alert defaults.
positionobject	A short options position: `kind` (`condor`, `strangle`, `put_spread`, `call_spread`), `legs` (`lp`, `sp`, `sc`, `lc`, rising), `entry` (`HH:MM` ET) and optionally `conditions`, `label`, `alert` (`{ channel: telegram \| email \| webhook \| off, url, before }`) and `session`.
position.idstring	`p_...`, given by `add`.
position.kindcondor \| strangle \| put_spread \| call_spread	`condor`, `strangle`, `put_spread` or `call_spread`.
position.legsobject	The strikes, rising, as the kind needs them.
position.legs.lpnumber	Long put.
position.legs.spnumber	Short put.
position.legs.scnumber	Short call.
position.legs.lcnumber	Long call.
position.entrystring	Entry minute, `HH:MM` ET.
position.conditionsarray	`[{ id, on, threshold }]`: which conditions count, and where they switch on.
position.labelobject	`{ caution, skip }`: how many conditions on make each label.
position.alertobject	`{ channel: telegram \| email \| webhook \| off, url, before }`: where the alerts go and how many minutes before entry they start.
position.sessionstring	`YYYY-MM-DD`: the session the strikes were set against.

Errors

Status	Code	What to do
401	`no_key`	No key, or a revoked one. Send `Authorization: Bearer <key>` with a key of the product's scope.
403	`plan`	The account is not on the Orders API or Team plan. Move to the Orders API or Team plan.
404	`not_found`	No position with this id on this account. Check the path or the id.
429	`rate`	The day's calls are spent. Wait for midnight ET, when the count resets.

Every code: Errors.

Changes

2026-10-04 Added.

OpenAPI operation positionsList in /docs/developers/openapi.json.

Request

curlPythonNode

curl \
  -H "Authorization: Bearer $FIRMTAPE_ORDERS_KEY" \
  "https://firmtape.com/api/positions"

import os, requests

H = {"Authorization": f"Bearer {os.environ['FIRMTAPE_ORDERS_KEY']}"}
r = requests.get("https://firmtape.com/api/positions", headers=H)
print(r.status_code, r.text[:500])

const r = await fetch("https://firmtape.com/api/positions", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.FIRMTAPE_ORDERS_KEY}` },
});
console.log(r.status, await r.text());

Response

401403404429

{
  "error": {
    "code": "no_key",
    "message": "No key was sent (Orders: no key, or one that is unknown or revoked)."
  }
}

{
  "error": {
    "code": "plan",
    "message": "The key is real; the account is not on the Orders API or Team plan."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "No such endpoint (levels API), or no position with this id on this account (POSITIONS)."
  }
}

{
  "error": {
    "code": "rate",
    "message": "The account's calls for the day are spent."
  }
}

Measurements of dealer positioning, never a forecast or a trade call. This page is built from FirmTape's public contract, the same files the OpenAPI document is built from; the tests hold them against the route code. Markdown: /docs/developers/orders/positions.md.