# AuctionTrace ES trade-list specification

This is the customer contract for the human-first AuctionTrace ES trade-list
analysis.

- Introductory price: **$10 one time**.
- Scope: **ES only** — CME E-mini S&P 500 futures (`ES`).
- Included delivery: buyer-specific analysis **plus the complete $5 AuctionTrace
  ES Book Pressure kit**.
- Intake: one CSV plus strategy fields after verified payment.
- Guaranteed capacity: up to **10,000 completed trades**.
- Privacy: after verified payment, the server validates the submission, binds
  the first accepted SHA-256 to the paid order, and stores only an authenticated
  AES-256-GCM encrypted normalized object in the private assessment namespace.
  Raw submissions are retained for 7 days and private reports for 30 days unless
  the buyer deletes them sooner.
- Fulfillment: an authorized operator imports exact matched outputs and a
  mandatory human review must pass before the private report is released. If
  the requested interval cannot support the promised comparison, AuctionTrace
  refunds the purchase.

Choose one CSV format per submission:

- Simple completed trades: [blank template](https://api.auctiontrace.com/trade-list/template.csv)
  and [valid sample](https://api.auctiontrace.com/trade-list/sample.csv).
- Scaled positions: [blank position-event template](https://api.auctiontrace.com/trade-list/position-events-template.csv)
  and [valid scale-in/partial-exit sample](https://api.auctiontrace.com/trade-list/position-events-sample.csv).
- [Example strategy form values](https://api.auctiontrace.com/trade-list/sample-metadata.json)
  are a machine-readable example, not a second human file.

The post-payment upload page is:

`https://auctiontrace.com/trade-list/`

The machine-readable schema is:

`https://api.auctiontrace.com/api/v1/outcome-assessment/schema`

Current coverage and paid-fulfillment state are published at:

`https://api.auctiontrace.com/api/v1/outcome-assessment/coverage`

## Upload one CSV and enter the strategy details once

One CSV represents one ES strategy. The strategy definition is supplied once
in the page's form instead of being repeated on every trade row. A human uploads
only one file. The submission is complete when it receives:

1. **One CSV file in one selected format**: `completed_trades` for simple
   one-entry/one-exit positions, or `position_events` for entries, scale-ins,
   partial exits, and final exits. Every fill requires its actual quantity,
   time, and price.
2. **Strategy details entered in the form once**: `strategy_id`, exact `ES`
   instrument, `bar_type`, the applicable bar definition (`bar_size` for
   minute/range/tick/volume bars or exact `bar_parameters` plus platform and
   version for FlexRenko/custom bars), test dates, and timezone.

Input format, bar type, and bar size have not been removed from the contract. They are
strategy-level fields entered beside the file because this format accepts one
strategy per CSV. The human does not upload a second metadata file. An API or
coding agent sends the same strategy fields as the `metadata` object in its one
JSON validation request.

The examples use one `range` strategy with `bar_size: 5`. Replace every sample
value with the submitting strategy's real values. If one export contains trades
from more than one strategy or bar definition, split it into one CSV per
strategy/bar definition and enter the matching form values for each validation.

## Common file contract

- UTF-8 RFC 4180-compatible CSV, with or without a UTF-8 BOM.
- `LF` or `CRLF` line endings.
- One header followed by rows for exactly one selected input format.
- Header order may vary.
- Unknown columns are rejected. Do not send unrelated account, personal,
  strategy-formula, or payment data.
- Blank trailing lines are ignored. Blank rows inside the data must be removed.

## Format A: simple completed trades

Use this format only when every position has one entry fill and one exit fill,
with no scale-in and no partial exit. Required columns:

| Column | Rule |
| --- | --- |
| `trade_id` | Unique stable ID, 1-128 letters/numbers/`.`/`_`/`:`/`-`. |
| `entry_datetime` | Timezone-aware RFC3339 timestamp. |
| `direction` | `long` or `short`. |
| `entry_quantity` | Positive finite quantity. |
| `exit_datetime` | Timezone-aware RFC3339 timestamp, not before entry. |
| `exit_quantity` | Positive finite quantity equal to entry quantity for this simple format. |
| `exit_reason` | `stop`, `target`, `time_exit`, `signal_exit`, `discretionary`, or `unknown`. |
| `entry_price` | Actual positive finite ES entry fill price. Required to reconstruct the submitted baseline. |
| `exit_price` | Actual positive finite ES exit fill price. Required to reconstruct the submitted baseline. |

There are no optional columns in the Phase 01 simple completed-trade
format. A file missing either fill price cannot support the matched Order Flow-
ATM comparison and fails validation with exact repair instructions.

## Format B: scaled position events

Use this format when a position adds size or exits in parts. Exact header:

`trade_id,event_id,event_datetime,event_type,direction,quantity,price,exit_reason`

| Column | Rule |
| --- | --- |
| `trade_id` | Stable ID repeated on every event in the same position lifecycle. |
| `event_id` | Globally unique stable event ID. |
| `event_datetime` | Timezone-aware RFC3339 fill timestamp. Events for a trade must be in nondecreasing order; equal timestamps preserve CSV row order. |
| `event_type` | `entry`, `scale_in`, `partial_exit`, or `final_exit`. |
| `direction` | `long` or `short`, unchanged throughout the lifecycle. |
| `quantity` | Positive actual fill quantity for this event. |
| `price` | Positive actual fill price for this event. |
| `exit_reason` | `none` for `entry`/`scale_in`; otherwise `stop`, `target`, `time_exit`, `signal_exit`, `discretionary`, or `unknown`. |

The automated gate requires the first event to be `entry`, permits any number
of `scale_in` and properly bounded `partial_exit` events, prevents exits from
exceeding open size, requires every `partial_exit` to leave positive size, and
requires one `final_exit` that reconciles the position exactly to zero. Events
after the final exit, repeated entries, direction changes, duplicate event IDs,
missing fills, and unfinished positions fail validation with exact repair codes.

Do **not** calculate or submit Book Pressure, MFE, MAE, profit factor, P&L,
strategy category, treatment flags, or AuctionTrace features.

## Strategy metadata

The human upload form—or the `metadata` object inside an agent/API
request—must supply these strategy-level values once:

- `input_format` — `completed_trades` or `position_events`; it must match the uploaded CSV.
- `strategy_id` — required stable identifier.
- `instrument` — must be `ES`.
- `bar_type` — `minute`, `range`, `tick`, `volume`, `flexrenko`, or `custom`.
- `bar_size` — required for minute, range, tick, and volume bars.
- `bar_parameters` — required for FlexRenko or custom bars.
- `test_start` and `test_end` — timezone-aware RFC3339 timestamps.
- `timezone` — IANA name, `UTC`, or explicit UTC offset.
- `session_template` — recommended.
- `platform` and `platform_version` — required together for synthetic/custom
  bars; otherwise optional.

The `$10` assisted intake does not force the customer back into the immutable
Release 008 `$5` dataset dates. The customer supplies the real `test_start` and
`test_end`. AuctionTrace reviews the private coverage needed for the requested
interval during fulfillment. If that coverage cannot support the promised
comparison, the buyer is refunded. A structurally valid file is never mislabeled
invalid merely because its dates fall outside the fixed Release 008 sample window.

## Validation response

Every validation returns either:

- `ready` — the file meets the current automated intake contract; or
- `needs_fixes` — one or more issues include a stable code, row, field,
  explanation, and exact correction.

A `ready` response confirms that the file matches the intake contract. The paid
order remains the source of entitlement, and the comparison is complete only
after private processing and mandatory human review.

Support: `help@auctiontrace.com`. Send only a validation code, row number,
submission SHA-256, and sanitized error text. Never email raw trade rows,
credentials, card data, payment signatures, wallet secrets, private keys,
strategy formulas, private network addresses, or local filesystem paths.