Time Seventeen | Positions and Balances

Settled and unsettled exposure, reservations, collateral, P&L, snapshots, and reconciliation.

Draft v0.1 — design contract, not yet a live service

This documentation set defines a proposed Time Seventeen protocol for review and implementation planning. https://api.t17.capital is the approved and reserved REST origin, but neither that origin nor any documented endpoint is claimed to be live. The WebSocket origin remains unspecified. Credentials, chain IDs, contract addresses, rate limits, and SLAs remain unapproved; IDs, prices, and timestamps shown throughout are illustrative, not real production data.

Position and Balance resources are account projections derived from signed orders, immutable Fills, adjustments, transfers, fees, and settlement. They are queryable snapshots, not replacements for the underlying ledger/audit records.

Endpoints

Method & path	Purpose
`GET /positions`	List account positions
`GET /positions/{market_id}`	Read all Outcome positions for one Market
`GET /balances`	Read asset balances and reservations

All endpoints require canonical API-key authentication and account:read.

Position schema

Illustrative position item

{
  "position_id": "pos_demo_001",
  "account_id": "acct_demo_001",
  "market_id": "mkt_demo_001",
  "outcome_id": "out_demo_yes_001",
  "net_quantity": "150.00",
  "settled_quantity": "50.00",
  "unsettled_quantity": "100.00",
  "reserved_sell_quantity": "20.00",
  "available_to_sell": "130.00",
  "average_entry_price": "0.6200",
  "mark_price": "0.6410",
  "mark_observation_id": "mktobs_demo_101",
  "cost_basis": "93.00",
  "market_value": "96.15",
  "realized_pnl": "4.20",
  "unrealized_pnl": "3.15",
  "pnl_asset_id": "asset_demo_collateral_001",
  "pending_settlement_ids": ["set_demo_001"],
  "source_fill_sequence": 992011,
  "projection_version": 18,
  "as_of": "2026-08-31T12:00:03.150Z"
}

net_quantity = settled_quantity + unsettled_quantity before reservations; reservations affect availability, not ownership. Negative quantity is permitted only where the account/Market explicitly allows short exposure. available_to_sell MUST reflect reduce-only and risk policy rather than being inferred solely from net quantity.

P&L is labeled with the pricing method, mark observation, asset, and as-of time. Draft v0.1 does not specify tax-lot accounting or a legally authoritative valuation method; those remain production/accounting policy.

Balance schema

Illustrative balance item

{
  "balance_id": "bal_demo_001",
  "account_id": "acct_demo_001",
  "asset_id": "asset_demo_collateral_001",
  "total": "10000.00",
  "available": "9720.00",
  "reserved": "96.00",
  "pending_settlement_credit": "84.00",
  "pending_settlement_debit": "100.00",
  "withdrawal_hold": "0.00",
  "projection_version": 44,
  "ledger_sequence": 120044,
  "as_of": "2026-08-31T12:00:03.150Z"
}

The response includes an account-level reconciliation identity. A typical projection satisfies:

available + reserved + withdrawal_hold
  = total - pending_settlement_debit

projected_equity
  = asset totals + marked positions + pending credits - pending debits - accrued fees

The exact collateral/equity formula, haircuts, and cross-margin behavior are production risk configuration and MUST be returned as versioned policy references rather than guessed by a client.

Query behavior

GET /positions accepts market_id, outcome_id, nonzero_only, settlement_state, as_of, cursor, and limit; default order is (market_id, outcome_id) ascending. GET /balances accepts asset_id and as_of.

If point-in-time reconstruction is not available for a requested as_of, the server returns an explicit validation/capability error. It MUST NOT return the current account snapshot under an old timestamp.

Reservations

Accepted resting BUY orders reserve collateral/notional plus configured fee/risk buffers. SELL orders reserve Outcome quantity or collateral according to the position model. A partial Fill consumes the corresponding reservation; cancel/expiry releases only unmatched remainder. Reservation release and Fill effects are sequenced so clients do not temporarily double-count spendable funds.

Settlement boundary

Unsettled quantity records matched exposure whose finalization is pending. A confirmed settlement moves quantity/asset between unsettled and settled buckets; failed or reversed settlement creates explicit projections and audit links rather than deleting the Fill. See Settlement.

Reconciliation procedure

Fetch Positions and Balances; retain projection_version, ledger_sequence, source_fill_sequence, and as_of.
Fetch Fills/adjustments after source_fill_sequence and settlement changes after the snapshot cursor.
Subscribe/resume private streams from the returned cursor.
Deduplicate by event/resource ID and apply only increasing projection versions.
On a sequence gap or invariant mismatch, discard the local projection and request a fresh REST snapshot.

Clients MUST NOT calculate available collateral by summing WebSocket deltas forever without periodic snapshot reconciliation.

Positions and Balances