order-history.md

# order-history

Query historical or specific orders via:

- `GET /v1/accounts/{id}/orders` — list orders, optional filters
- `GET /v1/orders/{order_id}` — single order detail with fills and state history

## When to consult this

User says "查订单", "历史订单", "查 ord_xxx", "list orders", "show working
orders", "什么单子还没成交". No confirmation required.

## Calling

    python3 -c "
    from scripts._http import Client
    c = Client()

    # All orders (no cursor = all since epoch)
    print(c.get('/v1/accounts/acc_default/orders'))

    # WORKING orders only
    print(c.get('/v1/accounts/acc_default/orders?status=WORKING'))

    # Orders after a specific ISO timestamp
    print(c.get('/v1/accounts/acc_default/orders?since=2026-05-21T09:00:00'))

    # Single order by id (includes fills + state_history)
    print(c.get('/v1/orders/ord_accdefault_abc12345'))
    "

## Response shape — list

    {
      "orders": [
        {
          "order_id":      "ord_accdefault_abc12345",
          "symbol":        "600519.SH",
          "side":          "BUY",
          "type":          "LIMIT",
          "qty":           100,
          "price":         1680.00,
          "state":         "WORKING",
          "remaining_qty": 100,
          "created_at":    "2026-05-21T09:31:00+00:00"
        }
      ]
    }

`price` is `null` for MARKET orders. `remaining_qty` is 0 for fully-filled
or cancelled orders and equals `qty` for WORKING orders (partial fills are
not supported in v1).

## Response shape — single order

Same as list item, plus:

    {
      ...,
      "client_order_id": "<uuid>",
      "fills": [
        {"qty": 100, "price": 1680.05, "fees": 50.41, "ts": "..."}
      ],
      "state_history": [
        {"state": "NEW",     "ts": "...", "reason": null},
        {"state": "WORKING", "ts": "...", "reason": null}
      ]
    }

## Filtering

`status` query param accepts: `NEW`, `WORKING`, `FILLED`, `CANCELLED`,
`EXPIRED`, `REJECTED` (case-sensitive). Omit to get all states.

`EXPIRED` — a WORKING LIMIT DAY order that reached its session-close
`expires_at` without filling (scheduler/engine expire pass at end of day).

`since` accepts an ISO 8601 datetime string. Orders with `created_at` after
this value are returned. Use this for incremental polling.

## Error responses

| Code | HTTP | recovery_hint | Action |
|------|------|---------------|--------|
| `ACCOUNT_NOT_FOUND` | 404 | fix_input | account_id wrong; default is acc_default |
| `ORDER_NOT_FOUND`   | 404 | fix_input | order_id wrong or does not belong to this service |