Time Seventeen | Settlement and Redemption

Post-match finalization, settlement states, external references, failure/reversal handling, and the draft redemption command.

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.

Settlement is the independent lifecycle that finalizes matched exposure through an approved custodial ledger, venue, or chain. A Filled order can still have pending or failed settlement; the original Fill remains immutable.

Endpoints

Method & path	Purpose
`GET /settlements`	List settlement/redemption records
`GET /settlements/{settlement_id}`	Read state, attempts, external references, and links
`POST /settlements/{settlement_id}/redeem`	Design placeholder only: request redemption of an eligible record

Reads require API-key authentication and settlement:read. The placeholder redemption command requires canonical request authentication, Idempotency-Key, and an approved EIP-712 economic authorization; exact production signing/deployment details are not defined.

State machine

State	Meaning
`pending`	Fill/obligation recorded; no external submission final yet
`submitted`	Submitted to the settlement rail with an attempt/reference
`confirmed`	Required finality threshold reached
`failed`	Attempt failed; retryability and reason are explicit
`reversed`	A previously confirmed effect was reversed by an explicit adjustment
`redeemable`	Resolved position/value is eligible for redemption
`redeemed`	Redemption finalized and linked to its credit/transaction

Allowed paths depend on the rail, but history MUST retain every attempt. failed may return to submitted only through a new attempt; confirmed may become reversed only through an authorized append-only reversal record. An Order or Fill is never relabeled because settlement changes state.

Settlement schema

Illustrative GET /settlements/{settlement_id} response

{
  "data": {
    "settlement_id": "set_demo_001",
    "account_id": "acct_demo_001",
    "state": "submitted",
    "kind": "trade_settlement",
    "fill_ids": ["fill_demo_001"],
    "market_id": "mkt_demo_001",
    "outcome_id": "out_demo_yes_001",
    "quantity": "100.00",
    "amount": "64.00",
    "fee": "0.20",
    "asset_id": "asset_demo_collateral_001",
    "rail": "YOUR_APPROVED_SETTLEMENT_RAIL",
    "attempts": [
      {
        "attempt_id": "setatt_demo_001",
        "attempt_number": 1,
        "state": "submitted",
        "submitted_at": "2026-08-31T12:00:05Z",
        "external_reference": "YOUR_APPROVED_EXTERNAL_REFERENCE_FORMAT",
        "chain_id": "YOUR_APPROVED_CHAIN_ID",
        "transaction_hash": null,
        "confirmation_count": null,
        "failure_code": null,
        "retryable": null
      }
    ],
    "created_at": "2026-08-31T12:00:03.130Z",
    "updated_at": "2026-08-31T12:00:05Z",
    "confirmed_at": null,
    "reversal_id": null,
    "redemption_id": null,
    "projection_version": 2
  },
  "meta": {
    "request_id": "req_demo_settlement_001",
    "published_at": "2026-08-31T12:00:05Z",
    "schema_version": "1.0"
  }
}

chain_id, transaction hash, confirmation policy, contract address, and asset address are omitted/null until a production rail is approved. The docs do not imply that settlement is on-chain; rail may identify a custodial or venue process.

Failure and retry

Each attempt records stable failure code, human message, rail response reference, retryability, next-action requirement, and timestamps. A retry creates a new attempt_id; it never overwrites the failed attempt. Automated retry policy, finality thresholds, gas/fee policy, and timing are production configuration.

Representative codes include SETTLEMENT_RAIL_UNAVAILABLE, SETTLEMENT_SUBMISSION_REJECTED, SETTLEMENT_FINALITY_TIMEOUT, SETTLEMENT_ASSET_MISMATCH, SETTLEMENT_REVERSED, and REDEMPTION_NOT_ELIGIBLE.

List and history

GET /settlements accepts state, kind, market_id, fill_id, asset_id, created_after, updated_after, cursor, and limit. Default order is (updated_at, settlement_id) descending. The detail response preserves all attempts, state transitions, external references, and adjustment/reversal links.

Redemption placeholder

POST /settlements/{settlement_id}/redeem is documented only to reserve the protocol boundary. A production implementation MUST define eligibility, resolution finality, payout calculation, authorization type, beneficiary, asset/rail, fees, idempotency retention, and failure/reversal behavior before enabling it.

Illustrative, non-executable redemption intent

{
  "account_id": "acct_demo_001",
  "beneficiary": "YOUR_APPROVED_BENEFICIARY_FORMAT",
  "asset_id": "asset_demo_collateral_001",
  "maximum_fee": "1.00",
  "authorization_nonce": "redeem_nonce_demo_001",
  "signature_type": "YOUR_APPROVED_SIGNATURE_TYPE",
  "authorization_signature": "YOUR_APPROVED_SIGNATURE_VALUE"
}

Until those production decisions exist, servers MUST NOT expose this route as a live command merely because it appears in Draft v0.1 documentation.

Reconciliation

Positions/Balances consume settlement state by settlement_id and projection_version. Stream clients deduplicate transition events, apply increasing versions, and request a new snapshot after a sequence gap. A confirmed or reversed settlement always remains linked to its Fill(s) and accounting adjustments.

Settlement and Redemption