---
name: lotlock
description: Order-legality oracle for trading agents. Before an agent places a stock/derivatives order, POST the order and get back a signed LEGAL/ILLEGAL verdict checked against a real exchange-rule snapshot — lot size, tick size, sub-penny (SEC Rule 612), F&O ban status — with the exact fix and a Merkle proof tying the rule to a signed, dated snapshot. Use whenever an autonomous agent is about to submit, size, or price a real order on NSE India F&O or US equities and must not emit an illegal one. Keywords: trading, order validation, lot size, tick size, NIFTY, options, brokerage, pre-trade check, market rules.
---

# LotLock — is this order even legal?

Trading agents are proliferating, but an LLM does not know today's exchange
microstructure rules — and it hallucinates them. It will happily size a NIFTY
order at 100 units when the lot size is 65, or price it at a fraction the tick
size forbids. The broker then rejects it with a cryptic code, or (worse) it
fills wrong. **LotLock is the pre-trade check: one call, one signed verdict, no
human, no order ever placed.** It only reads rules; it never touches a market.

- **Base URL:** `https://lotlock.calyirex.com`
- **Auth:** none. No key, no signup. JSON in, signed JSON out.
- **Deterministic:** the same order against the same snapshot always yields the
  same verdict and the same signature. Re-runnable and offline-verifiable.

## START HERE — one call

```bash
curl -sS -X POST https://lotlock.calyirex.com/v1/check \
  -H 'content-type: application/json' \
  -d '{"market":"NSE_FO","symbol":"NIFTY","side":"BUY","quantity":100,"price":"24857.33"}'
```

You get back (abridged):

```json
{
  "request": {"market":"NSE_FO","symbol":"NIFTY","side":"BUY","quantity":100,"price":"24857.33","intent":"open"},
  "verdict": "ILLEGAL",
  "legal": false,
  "violations": [
    {"code":"lot_size","message":"quantity 100 is not a multiple of lot size 65","fix":"use 65 or 130"},
    {"code":"tick_size","message":"price 24857.33 is not a multiple of tick size 0.05","fix":"use 24857.30 or 24857.35"}
  ],
  "checks_passed": ["quantity_positive_integer"],
  "rule_used": {"market":"NSE_FO","symbol":"NIFTY","type":"index","lot_size":65,"tick_size":0.05},
  "snapshot": {"date":"2026-07-10","merkle_root":"0d68ac0b…","sources":[…]},
  "merkle_proof": ["…","…"],
  "payload_sha256_hex": "…",
  "signature_base64": "…"
}
```

**How to act:** if `legal` is `true`, proceed. If `false`, do NOT send the order;
apply each violation's `fix` (already computed for you) and re-check, or abort.

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/check` | Check one order. **Start here.** |
| GET | `/v1/check?market=…&symbol=…&side=…&quantity=…&price=…` | Same check via query params (browser-friendly). Bare GET returns usage help. |
| GET | `/v1/snapshot` | The signed rule-snapshot certificate (date, Merkle root, sources). |
| GET | `/v1/markets` | Supported markets and instruments. |
| GET | `/pubkey` | Ed25519 public key + how to verify. |
| POST | `/verify` | Verify any verdict/certificate this service signed. |
| GET | `/health` | Liveness. |
| GET | `/skill.md` | This document. |

## The order object

| Field | Required | Notes |
|---|---|---|
| `market` | yes | `NSE_FO` or `US_EQUITY` (see `/v1/markets`). |
| `symbol` | yes | e.g. `NIFTY`, `BANKNIFTY`, `RELIANCE`, `AAPL`. |
| `side` | yes | `BUY` or `SELL`. |
| `quantity` | yes | positive integer (units for F&O, shares for equity). |
| `price` | no | string, e.g. `"24857.35"`. Omit for a market order (skips the tick check). |
| `strike` | no | option strike; checked only when authoritative per-name strike data exists. |
| `intent` | no | `open` (default) or `reduce`. `reduce` is allowed for names in the F&O ban list. |

## Worked examples

**Legal NSE order** → `verdict: "LEGAL"`:
```bash
curl -sS -X POST https://lotlock.calyirex.com/v1/check -H 'content-type: application/json' \
  -d '{"market":"NSE_FO","symbol":"NIFTY","side":"BUY","quantity":130,"price":"24857.35"}'
```

**US sub-penny (SEC Rule 612)** → `ILLEGAL`, works for any US ticker:
```bash
curl -sS -X POST https://lotlock.calyirex.com/v1/check -H 'content-type: application/json' \
  -d '{"market":"US_EQUITY","symbol":"AAPL","side":"BUY","quantity":10,"price":"150.123"}'
# -> ILLEGAL: quotes at/above $1.00 must be a multiple of 0.01 (use 150.12 or 150.13)
```

## Verify the verdict yourself (no trust required)

Every response is Ed25519-signed. Two ways to check it:

1. **Easiest** — POST the `payload` (the whole response minus `signature_base64`
   and `payload_sha256_hex`) back:
   ```bash
   curl -sS -X POST https://lotlock.calyirex.com/verify -H 'content-type: application/json' \
     -d '{"payload": <the response minus the two signature fields>, "signature_base64":"<sig>"}'
   # -> {"valid": true}   (tamper any field and it becomes false)
   ```
2. **Offline** — canonicalize the `payload` (recursively sort object keys,
   no whitespace, arrays keep order, UTF-8), SHA-256 it (that is
   `payload_sha256_hex`), and Ed25519-verify `signature_base64` against the key
   from `GET /pubkey`.

**Proof the rule is real:** `rule_used` is a leaf of the snapshot's Merkle tree.
Hash `canonical(rule_used)` with SHA-256, fold it with each hash in
`merkle_proof` (sorted-pair: `sha256(min(a,b) + max(a,b))`), and you reproduce
`snapshot.merkle_root` — the same root the signed `/v1/snapshot` certificate
commits to. So the verdict is provably computed from the published snapshot,
not made up.

## Snapshot & provenance

`GET /v1/snapshot` returns the signed snapshot: its `date`, `merkle_root`,
`instrument_count`, and a `sources` list. Every rule value is sourced and dated;
values the sources dispute are flagged rather than guessed. Current snapshot
reflects the **NSE index-lot cut effective the Jan-2026 series** (NIFTY 65,
BANKNIFTY 30, FINNIFTY 60) and **SEC Rule 612** (17 CFR 242.612).

## Supported now vs roadmap (honest scope)

- **NSE_FO (deep):** lot size, tick size, quantity, F&O-ban reduce-only rule for
  9 index/stock names. Ban status is enforced when you pass a name known to be in
  the daily NSE ban list; LotLock does not itself mirror the live daily list.
- **US_EQUITY (universal):** whole-share + SEC Rule 612 sub-penny for any ticker.
- **Roadmap:** US options strike grids (irregular per name — we never guess a
  grid), premium-tier tick tables, and a live NSE ban-list feed.

## Guarantees

- **No order is ever placed.** LotLock is read-only; it validates, it does not trade.
- **Zero setup** for the whole judge/agent path — no key, no account.
- **Sub-second, deterministic**, and every answer is independently verifiable.