{
  "openapi": "3.1.0",
  "info": {
    "title": "FirmTape Orders API",
    "version": "1.0.0",
    "description": "Every large SPX order of a session, rebuilt from the tape as an ORDER rather than a print: legs folded back into the parent, the structure named, and each one placed against the measured dealer book at the minute it printed. Rows come sorted by what the order did to the book, which is not the size of the cheque -- the rank agreement between the two is 0.017. Finished sessions are free on the site; the plan buys today's session and reading it from code.",
    "termsOfService": "https://firmtape.com/terms",
    "contact": {
      "url": "https://firmtape.com/orders/docs"
    }
  },
  "servers": [
    {
      "url": "https://firmtape.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/orders/api/day": {
      "get": {
        "summary": "One session's ledger",
        "operationId": "ordersDay",
        "parameters": [
          {
            "name": "day",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ledger. A day whose ledger has not run answers 200 with an empty list and a note.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ledger"
                }
              }
            }
          },
          "400": {
            "description": "Bad day.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No key, or a revoked one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key is real; the account is not on the API or Team plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "The day's calls are spent; the count resets at midnight ET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders/api/latest": {
      "get": {
        "summary": "The newest session the ledger has",
        "description": "Today's while the market is open, and the last finished one after the close.",
        "operationId": "ordersLatest",
        "responses": {
          "200": {
            "description": "The ledger.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ledger"
                }
              }
            }
          },
          "401": {
            "description": "No key, or a revoked one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key is real; the account is not on the API or Team plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "The day's calls are spent; the count resets at midnight ET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders/api/sessions": {
      "get": {
        "summary": "Every day a ledger exists for",
        "operationId": "ordersSessions",
        "responses": {
          "200": {
            "description": "Oldest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "first": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "last": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No key, or a revoked one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key is real; the account is not on the API or Team plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "The day's calls are spent; the count resets at midnight ET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Ledger": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "example": "2026-08-17"
          },
          "sym": {
            "type": "string",
            "example": "SPX",
            "description": "SPX only: an order is placed against the measured book, and SPX is the only root that has one."
          },
          "min_premium": {
            "type": "number",
            "description": "The floor the ledger was built at."
          },
          "asof": {
            "type": [
              "string",
              "null"
            ],
            "example": "15:59:57"
          },
          "orders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "oid": {
                  "type": "string",
                  "description": "Stable id of the parent order within the session."
                },
                "t": {
                  "type": "string",
                  "example": "13:43",
                  "description": "When the parent order printed, ET."
                },
                "g": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Dealer gamma the order ADDED, $M per index point. NULL when the order could not be priced -- usually one printing inside the last half hour of its own expiry, where Black-Scholes gamma is true and meaningless. Null is not zero."
                },
                "kind": {
                  "type": "string",
                  "example": "vertical",
                  "description": "The structure, from package reconstruction rather than leg count."
                },
                "legs": {
                  "type": "string",
                  "example": "7740P/7750P",
                  "description": "The contract, for reading."
                },
                "lg": {
                  "type": "array",
                  "description": "The same legs as data: [strike, \"C\"|\"P\", sign]. The sign is what the package rule concluded the CUSTOMER did; 0 means it could not tell, never 'flat'.",
                  "items": {
                    "type": "array",
                    "items": {}
                  }
                },
                "exp": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "Aug 17",
                  "description": "The expiry carrying most of the order's gamma."
                },
                "size": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Contracts in the parent order."
                },
                "net": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Net premium, $M. A spread is priced at its NET: the gross of the legs double-counts money that never changed hands."
                },
                "flip": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Index points from the zero-gamma flip at that minute."
                },
                "side": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "over",
                    "under",
                    null
                  ],
                  "description": "Which side of the flip."
                }
              }
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "n": {
                "type": "integer",
                "description": "Orders above the floor in the whole session, not in the page returned."
              },
              "net": {
                "type": "number",
                "description": "Their net premium, $M."
              },
              "no_side": {
                "type": "integer",
                "description": "Orders the package rule could not orient. Between a quarter and a half of them, measured over 684 sessions."
              },
              "no_gamma": {
                "type": "integer",
                "description": "Orders it could not price. A different admission from no_side, reported apart."
              },
              "gamma_up": {
                "type": "integer"
              },
              "gamma_dn": {
                "type": "integer"
              }
            }
          },
          "note": {
            "type": "string",
            "description": "Present when the day has no ledger yet. The list is then empty and this says so; it is not an error."
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "oid": {
            "type": "string",
            "description": "Stable id of the parent order within the session."
          },
          "t": {
            "type": "string",
            "example": "13:43",
            "description": "When the parent order printed, ET."
          },
          "g": {
            "type": [
              "number",
              "null"
            ],
            "description": "Dealer gamma the order ADDED, $M per index point. NULL when the order could not be priced -- usually one printing inside the last half hour of its own expiry, where Black-Scholes gamma is true and meaningless. Null is not zero."
          },
          "kind": {
            "type": "string",
            "example": "vertical",
            "description": "The structure, from package reconstruction rather than leg count."
          },
          "legs": {
            "type": "string",
            "example": "7740P/7750P",
            "description": "The contract, for reading."
          },
          "lg": {
            "type": "array",
            "description": "The same legs as data: [strike, \"C\"|\"P\", sign]. The sign is what the package rule concluded the CUSTOMER did; 0 means it could not tell, never 'flat'.",
            "items": {
              "type": "array",
              "items": {}
            }
          },
          "exp": {
            "type": [
              "string",
              "null"
            ],
            "example": "Aug 17",
            "description": "The expiry carrying most of the order's gamma."
          },
          "size": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Contracts in the parent order."
          },
          "net": {
            "type": [
              "number",
              "null"
            ],
            "description": "Net premium, $M. A spread is priced at its NET: the gross of the legs double-counts money that never changed hands."
          },
          "flip": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Index points from the zero-gamma flip at that minute."
          },
          "side": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "over",
              "under",
              null
            ],
            "description": "Which side of the flip."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "no_key",
                  "plan",
                  "rate",
                  "bad_day",
                  "no_route"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A key made on https://firmtape.com/account, on the API or Team plan. It starts with ordk_ and is shown once. 20,000 calls a day on API, 100,000 on Team, counted per account rather than per key."
      }
    }
  }
}