openapi: 3.1.0
info:
  title: OTC Public Quote API
  version: 0.1.0
  description: >-
    Spot quotes, quote acceptance, orders, balances and sandbox certification.
    Authenticate with an environment-specific bearer key.
servers:
  - url: https://api.elkcrypto.com/sandbox
    description: Shared sandbox;  use a sandbox key after access activation.
  - url: https://api.elkcrypto.com
    description: Production; use a separate production key after approval.
security:
  - ApiKey: []
tags:
  - name: Quotes
    description: Authenticated counterparty-bound quote issuance and trade booking.
paths:
  /v1/catalogue:
    get:
      operationId: catalogue
      tags: [Quotes]
      summary: Read eligible products and centrally selected source capabilities
      description: >-
        Lists products available to your account, including quantity rules and
        pricing availability. Requires ViewQuotes and an approved source IP.
        Use limit and after_id for pagination. No request body is required.
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - name: limit
          in: query
          required: false
          description: Maximum products per page, integer 1 through 200.
          schema: {type: integer, minimum: 1, maximum: 200, default: 50}
        - name: after_id
          in: query
          required: false
          description: Exclusive product UUID cursor from next_after_id; omit on the first page.
          schema:
            $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: Eligible product page; pricing availability is indicative capability only.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CataloguePage'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '405':
          description: invalid_request; only GET is supported.
          headers:
            Allow:
              required: true
              schema: {type: string, const: GET}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: catalogue_unavailable or service_unavailable; database or authorization storage failure.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/sandbox/progress:
    get:
      operationId: sandbox_progress
      summary: Read automatic progress for the authenticated sandbox key
      servers:
        - url: https://api.elkcrypto.com/sandbox
      description: >-
        Sandbox only. Records observed API scenarios automatically. No request body,
        query parameters or idempotency key. Production returns 404. Completion
        does not grant production access. Replaced keys start with fresh progress.
      responses:
        '200':
          description: Current per-key progress
          content:
            application/json:
              schema:
                type: object
                required: [key_id, account_id, checklist_version, completed, passed_checks, missing_checks, first_observed_at, completed_at, expires_at_ms, revoked_at_ms]
                additionalProperties: false
                properties:
                  key_id: {type: string, format: uuid}
                  account_id: {type: string, format: uuid}
                  checklist_version: {type: string, const: sandbox-auto-v1}
                  completed: {type: boolean}
                  passed_checks:
                    type: array
                    uniqueItems: true
                    items: {type: string}
                  missing_checks:
                    type: array
                    uniqueItems: true
                    items: {type: string}
                  first_observed_at: {type: [string, 'null'], format: date-time}
                  completed_at: {type: [string, 'null'], format: date-time}
                  expires_at_ms: {type: integer, format: int64}
                  revoked_at_ms: {type: [integer, 'null'], format: int64}
        '401':
          description: Invalid, expired or revoked sandbox key
        '403':
          description: Source IP or account not authorized
        '404':
          description: Route not present in production
        '503':
          description: Progress storage unavailable; retry later
  /v1/get_quote:
    post:
      operationId: get_quote
      tags: [Quotes]
      summary: Obtain a new caller-specific Spot quote or recover its original result
      description: >-
        Returns a quote for the requested symbol, side and quantity. Requires
        ViewQuotes, SubmitRfq and access to the requested product and market.
        Supply market when the symbol is available in multiple eligible markets.
        Retries with the same Idempotency-Key and body return the original quote,
        including its original price and expires_at. Replay requires read access.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            example:
              symbol: BTC/USD
              side: buy
              quantity: '0.25'
      responses:
        '200':
          description: >-
            Quote with price, pay/receive amounts and expires_at.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: idempotency_conflict; same scoped key with different canonical terms.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: >-
            pricing_unavailable for absent, unavailable or timed-out pricing;
            quote_unavailable for invalid pricing or changed authorization/product
            snapshot; service_unavailable for an internal failure.
            Retry using the original Idempotency-Key and request body.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/accept:
    post:
      operationId: accept
      tags: [Quotes]
      summary: Book an owned quote exactly once or recover its original acceptance
      description: >-
        Accepts a quote by quote_id using its original terms. Requires ViewQuotes,
        AcceptTrade, product and market access, and sufficient funds or credit.
        The quote must be unexpired for a new acceptance. Use a distinct
        Idempotency-Key for acceptance; retries with that key and body return
        the existing order and its current status, including after quote expiry.
        Replay requires read access.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptRequest'
            example:
              quote_id: 22222222-2222-4222-8222-222222222222
      responses:
        '200':
          description: >-
            Order ID, quote terms, accepted_at and current status.
            Initial status is pending; subsequent statuses are filled or cancelled.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Acceptance'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            quote_not_found. Missing and foreign-account quotes produce identical
            responses after current account/IP validation; no terms or ownership leak.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: >-
            idempotency_conflict for different canonical terms under the same
            scoped key; quote_already_accepted for an owned readable quote booked
            under another key; quote_expired for an owned readable unaccepted
            quote that has expired; insufficient_funds or insufficient_credit
            when available capacity cannot cover the pay amount.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: >-
            service_unavailable for an internal failure;
            funding_source_unavailable when funding capacity cannot be checked.
            Retry using the original Idempotency-Key and request body.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/heartbeat:
    get:
      operationId: heartbeat
      tags: [Health]
      summary: Check authenticated API and account-authority reachability
      description: >-
        Requires a valid key, approved source IP, active enrolled account, ViewQuotes
        and current KYC for linked desk clients. No body, query parameters or
        Content-Encoding is accepted. No Content-Type or Idempotency-Key is needed.
        Returns API and account-authority connectivity checks. Poll every
        15 seconds; use backoff and jitter after failures.
      responses:
        '200':
          description: API and current account-authority checks succeeded
          headers:
            Cache-Control:
              $ref: '#/components/headers/NoStore'
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [status, as_of, checks]
                properties:
                  status:
                    type: string
                    const: ok
                  as_of:
                    $ref: '#/components/schemas/UtcTimestamp'
                  checks:
                    type: object
                    additionalProperties: false
                    required: [api, account_authority]
                    properties:
                      api:
                        type: string
                        const: ok
                      account_authority:
                        type: string
                        const: ok
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: service_unavailable; API/database/account authority could not be checked
  /v1/balances:
    get:
      operationId: balances
      tags: [Balances]
      summary: Read the authenticated client's desk-owned balances and credit display
      description: >-
        Returns asset balances, holds, available funds and USD credit.
        Requires a linked account, current KYC, an approved IP and ViewQuotes.
        Available credit equals limit minus outstanding exposure minus holds.
        A zero credit limit permits funded orders only. No request body is required.
      responses:
        '200':
          description: Current balances, holds and credit
          headers:
            Cache-Control:
              $ref: '#/components/headers/NoStore'
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balances'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: service_unavailable; desk contract is unavailable, invalid or not installed
  /v1/orders:
    get:
      operationId: orders
      tags: [Orders]
      summary: Read the authenticated account's API orders, newest first
      description: >-
        Returns up to 50 orders. No body, Content-Type or Idempotency-Key is needed.
        Requires ViewQuotes and market access. Results are scoped to your account.
      parameters:
        - name: after_id
          in: query
          description: next_after_id from the preceding page
          schema:
            $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: Account-scoped API order history
          content:
            application/json:
              schema:
                type: object
                required: [records, next_after_id]
                properties:
                  records:
                    type: array
                    maxItems: 50
                    items:
                      $ref: '#/components/schemas/Acceptance'
                  next_after_id:
                    type: [string, 'null']
                    format: uuid
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: service_unavailable; retry the read with bounded backoff
  /v1/orders/{order_id}:
    get:
      operationId: order
      tags: [Orders]
      summary: Read an owned API order and its current reporting status
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: Current order report with immutable quote terms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Acceptance'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: quote_not_found; missing and foreign orders are indistinguishable
        '503':
          description: service_unavailable; retry the read with bounded backoff
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        Send Authorization: Bearer <key> over HTTPS. Each key is associated with
        an account and environment. Invalid, expired or revoked keys return 401.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        Client-generated UUID, scoped to account and operation. Use the same
        UUID and body for retries. Decimal strings are normalized and JSON
        property order is ignored when comparing requests. A changed request
        with the same UUID returns idempotency_conflict.
      schema:
        $ref: '#/components/schemas/Identifier'
    RequestId:
      name: X-Request-ID
      in: header
      required: false
      description: >-
        Optional request tracing UUID. The server generates one if omitted.
      schema:
        $ref: '#/components/schemas/Identifier'
  headers:
    RequestId:
      description: Request tracing UUID, also present in error bodies.
      required: true
      schema:
        $ref: '#/components/schemas/Identifier'
    NoStore:
      description: Authenticated responses must not be cached.
      required: true
      schema:
        type: string
        const: no-store
  schemas:
    CataloguePage:
      type: object
      additionalProperties: false
      required: [records, next_after_id]
      properties:
        records:
          type: array
          maxItems: 200
          items:
            $ref: '#/components/schemas/CatalogueProduct'
        next_after_id:
          description: Exclusive cursor for the next page, null when no lookahead product exists.
          oneOf:
            - $ref: '#/components/schemas/Identifier'
            - type: 'null'
    CatalogueProduct:
      type: object
      additionalProperties: false
      required: [product_id, instrument_id, market_id, market, base_asset_id, quote_asset_id, symbol, enabled, broker_rules, underlying_ids, offerings, pricing_available]
      properties:
        product_id: {$ref: '#/components/schemas/Identifier'}
        instrument_id: {$ref: '#/components/schemas/Identifier'}
        market_id: {$ref: '#/components/schemas/Identifier'}
        market: {$ref: '#/components/schemas/Market'}
        base_asset_id: {$ref: '#/components/schemas/Identifier'}
        quote_asset_id: {$ref: '#/components/schemas/Identifier'}
        symbol: {$ref: '#/components/schemas/Symbol'}
        enabled: {type: boolean, const: true}
        broker_rules: {$ref: '#/components/schemas/BrokerRules'}
        underlying_ids:
          type: array
          minItems: 1
          uniqueItems: true
          items: {$ref: '#/components/schemas/Identifier'}
        offerings:
          type: array
          maxItems: 1
          description: >-
            Selected centrally routed offering only, not an input choice. A retained
            stale, disabled or withdrawn offering may be present but unavailable.
            No route or no matching selected pair yields an empty array.
          items: {$ref: '#/components/schemas/SelectedOffering'}
        pricing_available:
          type: boolean
          description: Current selected RFQ capability only; not a live quote or execution guarantee.
    BrokerRules:
      description: >-
        Independent broker economics. Legacy-fixed products retain these rules in
        addition to source quantity and raw-price rules. Dynamic products have no
        invented global economics and use selected source precision.
      oneOf:
        - type: object
          additionalProperties: false
          required: [mode, price_tick, minimum_quantity, quantity_step]
          properties:
            mode: {type: string, const: legacy_fixed}
            price_tick: {$ref: '#/components/schemas/CanonicalDecimal'}
            minimum_quantity: {$ref: '#/components/schemas/CanonicalDecimal'}
            quantity_step: {$ref: '#/components/schemas/CanonicalDecimal'}
        - type: object
          additionalProperties: false
          required: [mode]
          properties:
            mode: {type: string, const: venue_dynamic}
    SelectedOffering:
      type: object
      additionalProperties: false
      required: [gateway_id, provider, offering_id, revision, rules, present, available, last_seen_at_ms, offering_source_observed_at_ms, offering_inventory_mode, inventory_mode, source_observed_at_ms, generated_at_ms, expires_at_ms]
      properties:
        gateway_id:
          type: string
          pattern: '^[a-z][a-z0-9_-]{0,63}$'
          description: Server-selected connection identity; never accepted as a customer selector.
        provider: {type: string, pattern: '^[a-z][a-z0-9_-]{0,31}$'}
        offering_id: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_./-]{0,95}$'}
        revision: {type: string, pattern: '^[0-9a-f]{64}$'}
        rules: {$ref: '#/components/schemas/OfferingRules'}
        present: {type: boolean}
        available:
          type: boolean
          description: Current connection/offering lease and controls; RFQ support is separate in rules.
        last_seen_at_ms: {type: integer, format: int64, minimum: 0}
        offering_source_observed_at_ms: {type: integer, format: int64, minimum: 0}
        offering_inventory_mode: {$ref: '#/components/schemas/InventoryMode'}
        inventory_mode: {$ref: '#/components/schemas/InventoryMode'}
        source_observed_at_ms: {type: integer, format: int64, minimum: 0}
        generated_at_ms: {type: integer, format: int64, minimum: 0}
        expires_at_ms: {type: integer, format: int64, minimum: 0}
    InventoryMode:
      type: string
      enum: [reviewed_configuration, live_discovery]
      description: Metadata provenance, not a provider entitlement or session-health certification.
    OfferingRules:
      type: object
      additionalProperties: false
      required: [instrument_id, base_asset, quote_asset, kind, provider_instrument, provider_stream_instrument, rfq_supported, indicative_stream_supported, enabled, minimum_quantity, maximum_quantity, quantity_step, price_tick, price_significant_digits]
      properties:
        instrument_id: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_./-]{0,95}$'}
        base_asset: {$ref: '#/components/schemas/Asset'}
        quote_asset: {$ref: '#/components/schemas/Asset'}
        kind: {type: string, const: SPOT}
        provider_instrument: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_./-]{0,95}$'}
        provider_stream_instrument: {type: string, pattern: '^(?:[A-Za-z0-9][A-Za-z0-9_./-]{0,95})?$'}
        rfq_supported: {type: boolean}
        indicative_stream_supported: {type: boolean}
        enabled: {type: boolean}
        minimum_quantity: {$ref: '#/components/schemas/Decimal'}
        maximum_quantity: {$ref: '#/components/schemas/Decimal'}
        quantity_step: {$ref: '#/components/schemas/Decimal'}
        price_tick:
          oneOf:
            - {$ref: '#/components/schemas/Decimal'}
            - {type: string, const: ''}
        price_significant_digits: {type: integer, minimum: 0, maximum: 18}
      oneOf:
        - properties:
            price_tick: {$ref: '#/components/schemas/Decimal'}
            price_significant_digits: {const: 0}
        - properties:
            price_tick: {const: ''}
            price_significant_digits: {minimum: 1, maximum: 18}
      description: >-
        Exact source constraints. Quantity must satisfy min/MAX/step, without rounding.
        Raw price precision is either fixed tick or significant digits, never a guessed
        conversion. Legacy broker final-price precision is independently retained.
    Identifier:
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
      description: UUID identifier; server responses use lowercase canonical spelling.
    QuoteId:
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
      description: >-
        Cryptographically random server-generated UUIDv4. Nonselectable and
        immutably account-bound. Knowledge of an ID never grants access.
    Decimal:
      type: string
      minLength: 1
      maxLength: 39
      pattern: '^(?!0(?:\.0+)?$)(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{1,18})?$'
      description: >-
        Positive exact decimal string, up to 20 integer and 18 fractional digits.
        No sign, exponent, whitespace, integer leading zeros or JSON numbers.
        Catalogue tick/lot/minimum rules also apply. Trailing fractional zeros
        normalize before comparison and fingerprinting (1.0 equals 1).
    CanonicalDecimal:
      type: string
      minLength: 1
      maxLength: 39
      pattern: '^(?!0$)(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{0,17}[1-9])?$'
      description: Positive exact decimal; canonical output has no trailing fractional zeros.
    UtcTimestamp:
      type: string
      format: date-time
      pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$'
      description: UTC ISO 8601, exactly millisecond precision; server/database authority.
    Asset:
      type: string
      pattern: '^[A-Z][A-Z0-9]{1,11}$'
    Symbol:
      type: string
      pattern: '^[A-Z][A-Z0-9]{1,11}/[A-Z][A-Z0-9]{1,11}$'
      description: Distinct base/quote asset codes, such as BTC/USD.
    Market:
      type: string
      pattern: '^[A-Z][A-Z0-9-]{1,23}$'
    AssetAmount:
      type: object
      additionalProperties: false
      required: [asset, amount]
      properties:
        asset:
          $ref: '#/components/schemas/Asset'
        amount:
          $ref: '#/components/schemas/CanonicalDecimal'
    Side:
      type: string
      enum: [buy, sell]
      description: >-
        Client perspective. Buy acquires base and owes quote; sell delivers base
        and receives quote. Price is quote-asset units per one base unit.
    QuoteRequest:
      type: object
      additionalProperties: false
      required: [symbol, side, quantity]
      properties:
        symbol:
          $ref: '#/components/schemas/Symbol'
        market:
          oneOf:
            - $ref: '#/components/schemas/Market'
            - type: 'null'
          description: Required on market_required; omission and null are equivalent.
        side:
          $ref: '#/components/schemas/Side'
        quantity:
          $ref: '#/components/schemas/Decimal'
          description: Base units; never resized by pricing.
    AcceptRequest:
      type: object
      additionalProperties: false
      required: [quote_id]
      properties:
        quote_id:
          $ref: '#/components/schemas/QuoteId'
    Quote:
      type: object
      additionalProperties: false
      required: [quote_id, symbol, market, side, price, pay, receive, issued_at, expires_at]
      description: >-
        Quoted price, final pay/receive amounts and expiry. Use pay and receive
        as the complete exchange amounts.
      properties:
        quote_id:
          $ref: '#/components/schemas/QuoteId'
        symbol:
          $ref: '#/components/schemas/Symbol'
        market:
          $ref: '#/components/schemas/Market'
        side:
          $ref: '#/components/schemas/Side'
        price:
          $ref: '#/components/schemas/CanonicalDecimal'
          description: Quote-asset units per base unit.
        pay:
          $ref: '#/components/schemas/AssetAmount'
        receive:
          $ref: '#/components/schemas/AssetAmount'
        issued_at:
          $ref: '#/components/schemas/UtcTimestamp'
        expires_at:
          $ref: '#/components/schemas/UtcTimestamp'
          description: Exclusive expiry. Retry never refreshes the quote.
      example:
        quote_id: 22222222-2222-4222-8222-222222222222
        symbol: BTC/USD
        market: OTC-SPOT
        side: buy
        price: '65000'
        pay: {asset: USD, amount: '16250'}
        receive: {asset: BTC, amount: '0.25'}
        issued_at: '2026-09-23T14:30:00.000Z'
        expires_at: '2026-09-23T14:30:05.000Z'
    SignedAmount:
      type: string
      maxLength: 128
      pattern: '^-?(0|[1-9][0-9]*)(\.[0-9]+)?$'
      description: Signed finite plain decimal string; never floating point JSON or exponent notation.
    Balances:
      type: object
      additionalProperties: false
      required: [schema_version, source, as_of, balances, credit]
      properties:
        schema_version:
          type: integer
          enum: [1, 2]
        source:
          type: string
          const: desk_journal
        as_of:
          $ref: '#/components/schemas/UtcTimestamp'
          description: Desk statement observation time, not a provider mark timestamp.
        balances:
          type: array
          maxItems: 1000
          items:
            type: object
            additionalProperties: false
            required: [asset, balance]
            properties:
              asset:
                type: string
                maxLength: 64
                pattern: '^[A-Z0-9_-]+$'
              balance:
                $ref: '#/components/schemas/SignedAmount'
              on_hold:
                $ref: '#/components/schemas/SignedAmount'
              available:
                $ref: '#/components/schemas/SignedAmount'
        credit:
          type: object
          additionalProperties: false
          required: [currency, basis, limit, outstanding, available]
          properties:
            currency:
              type: string
              const: USD
            basis:
              type: string
              enum: [desk_total_owed, asset_deficits_v1]
            limit:
              oneOf:
                - $ref: '#/components/schemas/SignedAmount'
                - type: 'null'
            outstanding:
              $ref: '#/components/schemas/SignedAmount'
            on_hold:
              $ref: '#/components/schemas/SignedAmount'
            available:
              oneOf:
                - $ref: '#/components/schemas/SignedAmount'
                - type: 'null'
      allOf:
        - if:
            properties:
              schema_version: {const: 2}
          then:
            properties:
              balances:
                items:
                  required: [asset, balance, on_hold, available]
              credit:
                required: [on_hold]
                properties:
                  basis: {const: asset_deficits_v1}
                  available:
                    $ref: '#/components/schemas/SignedAmount'
    Acceptance:
      type: object
      additionalProperties: false
      required: [order_id, trade_id, quote, accepted_at, status, updated_at]
      properties:
        order_id:
          $ref: '#/components/schemas/Identifier'
          description: Same opaque identifier as trade_id; preferred for order queries.
        status:
          type: string
          enum: [pending, filled, cancelled]
          description: Current order status.
        updated_at:
          $ref: '#/components/schemas/UtcTimestamp'
        trade_id:
          $ref: '#/components/schemas/Identifier'
        quote:
          $ref: '#/components/schemas/Quote'
        accepted_at:
          $ref: '#/components/schemas/UtcTimestamp'
          description: Time the quote was accepted.
    ApiError:
      type: object
      additionalProperties: false
      required: [code, message, request_id]
      properties:
        code:
          type: string
          enum:
            - invalid_request
            - market_required
            - unauthenticated
            - sandbox_key_on_production
            - permission_denied
            - action_unavailable
            - quote_not_found
            - idempotency_conflict
            - quote_expired
            - quote_already_accepted
            - insufficient_funds
            - insufficient_credit
            - funding_source_unavailable
            - request_too_large
            - unsupported_media_type
            - rate_limited
            - pricing_unavailable
            - quote_unavailable
            - service_unavailable
            - catalogue_unavailable
        message:
          type: string
          description: Safe human-readable text; not a stable parsing contract; no secret or denied terms.
        request_id:
          $ref: '#/components/schemas/Identifier'
      example:
        code: pricing_unavailable
        message: Pricing is unavailable.
        request_id: 77777777-7777-4777-8777-777777777777
  responses:
    InvalidRequest:
      description: >-
        market_required when an eligible symbol needs explicit market disambiguation;
        invalid_request for invalid JSON/schema/headers or catalogue-incompatible
        quantity. Unknown/duplicate JSON fields and duplicate semantic headers
        are rejected; errors do not echo credentials or private terms.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthenticated:
      description: >-
        unauthenticated for missing, malformed, unknown, expired or revoked keys.
        sandbox_key_on_production for a structurally valid sandbox-prefixed key
        on production routes; message explains the /sandbox base URL. This
        diagnostic does not confirm that the supplied key exists.
      headers:
        WWW-Authenticate:
          required: true
          schema:
            type: string
            const: Bearer
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: >-
        permission_denied for inactive account, disallowed IP or missing current
        read eligibility. Unknown and unauthorized requested products share this
        response. action_unavailable for missing new-operation mutation permission
        on an otherwise readable resource. Never expose denied quote terms or
        receipt contents. Committed readable retries do not need mutation permission.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    TooLarge:
      description: request_too_large. Configured body bound exceeded.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    UnsupportedMediaType:
      description: unsupported_media_type. Content-Type must be application/json.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: >-
        rate_limited. Configured admission limit reached. Delay then retry the
        original command; never substitute an idempotency key for uncertain work.
      headers:
        Retry-After:
          description: Optional delay in whole seconds.
          schema:
            type: integer
            minimum: 0
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
