From provider to order

1. Start with the right posture #

Choose the execution posture before connecting anything. A connection is never assumed to be trade-enabled simply because the provider exists.

2. Build and approve the provider first #

For a broker-specific provider, select trading-build and start a new Build task with $tcx-build on the first meaningful line. The plain token or matching workspace skill link is accepted. If the provider is missing, Build implements and statically validates it before rendering or registering a connector; a provider_development_required connector appears first only when you explicitly ask for scaffold-only output.

$tcx-build
Research public official sources, implement the <provider> provider, and stop for exact-hash approval. Use only credential_ref; do not connect or trade.

Public HTTP(S) GET/HEAD or read-only HTTPS Git source is staged only under $TRADINGCODEX_SCRATCH/provider-sources/<provider-id>/ for review, hashing, diffing, and static checks. Git Smart HTTP uses the proxy's full transport only for its protocol POST; model-authored general POST remains blocked. Downloaded source is never installed or executed. Final provider files are written with apply_patch, and externally informed bundles record a secret-free source-provenance.json. Authenticated requests, local/private services, package installs, remote publication, and direct broker calls remain blocked.

Build may report an inert bundle-only provenance summary and hash with service_check_required when its sandbox cannot read the central ledger. That output is not canonical approval state. Provider source remains untrusted until you repeat inspection and approve its exact bundle hash in your interactive terminal. A provenance or helper change invalidates approval. After approval, restart the service; connector rendering, registration, and validation continue in a fresh Build task. Credentials are stored only as a reviewed credential_ref, never pasted into a prompt, workspace file, API response, MCP response, or audit record.

3. Establish a usable broker connection #

Broker connections start disabled or read-only, except the built-in paper adapter. After a provider has been prepared and approved, the service must verify signed health for its credential reference, discover the broker account, apply the right account scope, and review canonical-to-broker instrument mapping before any execution posture is usable.

1. Check provider and connection status. Ask $tcx-server for current workspace, service, MCP, and recovery posture.
2. Sync read-only account state. The service can discover accounts, cash, positions, orders, and fills and record a reconciliation trail.
3. Review mapping and limits. The connection needs the correct provider, account, instrument mapping, execution posture, health, and trading-enabled state.
4. Confirm the mode. Paper, validation, and live have separate policy and connection gates; a healthy connection alone does not open an order path.

4. Prepare the order before asking to execute #

Start with evidence, then let the protected workflow create the canonical preparation state. The user-facing workflow coordinates the fixed roles; the service holds the central order records.

1. Research. Use tcx-workflow to establish evidence, scope, and any exclusions.
2. Draft a ticket. Portfolio work creates an OrderTicket; it is the canonical draft, not a workspace Markdown order file.
3. Run checks. Schema, policy, cash/position, market, broker-validation, and risk checks must be ready.
4. Get risk approval. The approval receipt binds the exact order payload hash, broker/account scope, limits, order type, time-in-force, and expiry.

At this point the user has a ticket and, if approved, a matching receipt—not an automatic execution.

5. Choose one exact final-action path #

When the ticket and approval receipt are already known, use the action-only tcx-order-submit grammar. When a normal workflow may determine the canonical identifiers later in the same root task, use the exact first-meaningful-line tcx-order-allow grant and let it admit at most one later attempt. A matching workspace skill link may replace only the leading skill token; argument grammar stays strict.

$tcx-order-submit --ticket-id <ticket-id> --approval-receipt-id <approval-receipt-id>

Immediately before provider invocation, the service rechecks policy and approval, validates the structured payload, reserves idempotency, writes the mandatory intent audit, verifies the connection, then records a finalized or uncertain result. Never retry a needs-review or authorizing result blindly.

What extra live execution would require #

Live is not enabled by workspace generation, provider scaffold, connector registration, or an order approval alone. A separately installed and reviewed live provider must have enabled live configuration, policy permission for live_broker, environment opt-in, enabled adapter, signed health, trading-enabled connection, exact approved order hash, and an explicit live confirmation. Until every gate is present, use paper or validation and treat the live path as blocked.