Skip to main content

Protected order book

Read and reconcile protected workflow evidence without submitting entry or recovery orders. This read is non-billable.

Offline source contract; this page is not a production deployment announcement. Replace symbols, expiries, quantities and mode snapshots with current account evidence before use.

POST /api/v1/protectedorderbook​

Authentication: apikey JSON; identity checked in route/service. Send a JSON object with Content-Type: application/json.

Parameters​

FieldTypeRequiredDefault / omissionMeaning
expected_modeStringYesrequiredCurrent server mode: live or analyze.
expected_balance_typeStringYesrequiredCurrent balance type: live or sandbox.
expected_mode_versionIntegerYesrequiredCurrent integer version returned by Funds/Analyzer; refresh after a mode switch.
request_idStringYesrequiredSave before submission. For protected placement retain the same ID and payload for an intentional retry; do not replay an ambiguous submission automatically.
apikeyStringYesrequiredPer-broker IMC key; never use the broker access token.

Request example​

{
  "expected_mode": "analyze",
  "expected_balance_type": "sandbox",
  "expected_mode_version": 7,
  "request_id": "saved-business-request-001",
  "apikey": "YOUR_BROKER_IMC_KEY"
}

Python SDK​

from layr0_imc import api

client = api(api_key="YOUR_BROKER_IMC_KEY", host="https://YOUR_IMC_HOST")
# Copy the current snapshot from Funds/Analyzer for this same key.
client.set_mode_context(expected_mode="analyze", expected_balance_type="sandbox", expected_mode_version=7)

result = client.protectedorderbook(request_id='saved-business-request-001')
print(result)

Response and errors​

Illustrative 200 success; values are examples, not broker evidence:

{
  "status": "success",
  "contract_version": 2,
  "data": [],
  "mode": "analyze",
  "balance_type": "sandbox",
  "mode_version": 7
}

All incoming JSON objects and arrays follow recursive forbidden-field validation. A prohibited documentation key returns 400 before execution:

{
  "status": "error",
  "error_code": "FORBIDDEN_JSON_FIELD",
  "message": "Documentation fields are not allowed in request JSON."
}

Schema errors use 400. Authentication and broker-session failures retain endpoint-specific errors. Missing mode preconditions use 428 in services (the REST schema can reject missing fields with 400); stale mode snapshots use 409. See HTTP errors and authentication/mode requirements. No error response authorizes an automatic order retry.

Modes, capabilities and usage​

Requires current mode metadata and a saved request_id. One top-level mode lease fences the operation; placement separately persists durable business identity. Do not replace a saved placement ID or change its payload to retry an unknown submission. Acknowledgement, trigger acceptance, a missing order, or zero exposure is not fill evidence. Production registration in source is limited to Dhan, Upstox, Zerodha and FYERS; eligible workflows depend on broker capabilities and account authorization. Dhan uses explicit SUPER intent; Upstox uses its native composite workflow; unsupported capabilities remain errors. See protected-order workflow, Dhan Super, and DDPI authorization. ProtectedOrderBook enforces authentication, license validity and mode fencing but is non-billable; it reconciles evidence and does not automatically attach protection. The success envelope has contract_version=2 and data; each record exposes execution_evidence, verified_by_broker and recovery_required where applicable.

Source handler: restx_api.protected_orders.ProtectedOrderBook.post. Source services: services.protected_order_service.protected_orderbook.