anthid-com Control Evaluation API

openapi: 3.2.0
info:
  title: controls Control Evaluation API
  description: Effective control-state evaluation
  license:
    name: ''
  version: 0.1.0
servers:
- url: https://api.anthid.com
  description: Production
tags:
- name: Control Evaluation
  description: Effective control-state evaluation
paths:
  /v1/controls/evaluate:
    post:
      tags:
      - Control Evaluation
      summary: Evaluate controls
      description: Evaluates organization controls for JSON `null`, or effective order controls for an order context with a resolved `instrument`. Non-equity instruments are blocked. Supply `side` when position or daily-loss controls apply; those controls block orders without it. Both allowed and blocked results return 200. Users and API keys require Controls Basic or Premium. Users need an organization role; API keys need control read permission for the account environment, or both environments for `null`. Services need `control:evaluate` and `x-organization-id`.
      operationId: evaluateControls
      parameters:
      - name: x-organization-id
        in: header
        description: Organization ID required for service-account credentials
        required: false
        schema:
          type:
          - string
          - 'null'
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440222
      requestBody:
        description: JSON null for organization-only evaluation, or a complete order context including its required instrument
        content:
          application/json:
            schema:
              oneOf:
              - type: 'null'
              - $ref: '#/components/schemas/EvaluateRequest'
            example:
              account_id: 550e8400-e29b-41d4-a716-446655440000
              instrument:
                asset_class: EQUITY
                exchange: NASDAQ
                symbol: AAPL
              quantity: '100'
              side: BUY
              symbol: AAPL
        required: true
      responses:
        '200':
          description: Control evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluateResult'
              example:
                allowed: false
                triggered:
                - control_type: Manual
                  reason: Symbol restricted during earnings
                  scope:
                    Symbol:
                      account_id: 550e8400-e29b-41d4-a716-446655440000
                      symbol: AAPL
        '400':
          description: JSON syntax is invalid, or the service-account `x-organization-id` header is missing or invalid
          content:
            application/json:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '401':
          description: Missing or invalid authentication credentials
        '403':
          description: Caller lacks controls entitlement, evaluation access, or account ownership
          content:
            application/json:
              schema:
                type: string
        '413':
          description: Request body exceeds the size limit
          content:
            text/plain:
              schema:
                type: string
        '415':
          description: Content-Type must be application/json
          content:
            text/plain:
              schema:
                type: string
        '422':
          description: JSON does not match the request schema
          content:
            text/plain:
              schema:
                type: string
        '429':
          description: Caller exceeded the request rate limit
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: string
      security:
      - bearerAuth: []
      - clientCredentials: []
      - apiKeyAuth: []
components:
  schemas:
    TriggeredControl:
      type: object
      required:
      - scope
      - control_type
      - reason
      properties:
        control_type:
          $ref: '#/components/schemas/ControlType'
        reason:
          type: string
        scope:
          $ref: '#/components/schemas/ControlScope'
    OptionType:
      type: string
      enum:
      - call
      - put
    Settlement:
      type: string
      description: 'Which asset a [`Perpetual`] pays out in.


        The difference is not bookkeeping. A linear contract is quoted and settled

        in the quote asset, so its value rises with price like anything else. An

        inverse contract is quoted in the quote asset and settled in the **base**

        one, which puts price in the denominator: the position is worth

        `multiplier * quantity / price`, and it is worth *less* as price rises.


        A venue commonly lists both against the same pair - `BTCUSDT` linear beside

        `XBTUSD` inverse - so the spelling is not a reliable guide and this field

        is the only thing that says which is which.'
      enum:
      - LINEAR
      - INVERSE
    OrderSide:
      type: string
      enum:
      - UNSPECIFIED
      - BUY
      - SELL
      - SELL_SHORT
    PredictionOutcome:
      type: string
      description: Which side of a prediction market a contract pays on.
      enum:
      - 'YES'
      - 'NO'
    Perpetual:
      type: object
      description: "A perpetual contract: a derivative with no settlement date.\n\nIt tracks its underlying without ever expiring, held in line by a funding\npayment exchanged between longs and shorts on a fixed schedule rather than\nby convergence to a settlement price. Two consequences matter more than the\nrest, and both are places where treating a perpetual as a future goes\nwrong quietly:\n\n1. **There is no expiry.** [`Instrument::expiration`](super::Instrument::expiration)\n   answers `None`, and\n   that `None` means \"never\" rather than \"unknown\". Anything that rolls,\n   ages or expires positions has to tell those apart.\n2. **Settlement can invert the position.** See [`Settlement`].\n\nFunding is carried as a schedule rather than a rate because the rate is\nmarket data that changes every interval, and an instrument identity that\nwent stale every eight hours would be cached wrongly everywhere. What\nbelongs here is *when* funding happens; what it costs belongs on a quote."
      required:
      - symbol
      - base
      - quote
      - venue
      - underlying
      - settlement
      - multiplier
      - funding
      - tick_size
      - quantity_increment
      properties:
        base:
          type: string
        funding:
          $ref: '#/components/schemas/FundingSchedule'
        multiplier:
          $ref: '#/components/schemas/Multiplier'
          description: 'Units of the underlying per contract.


            Read through [`Instrument::notional`](super::Instrument::notional). For an

            inverse contract this is

            an amount of the *quote* asset - one contract of `XBTUSD` is one dollar

            of bitcoin - which is why it cannot simply be multiplied through.'
        quantity_increment:
          $ref: '#/components/schemas/Quantity'
        quote:
          type: string
        settlement:
          $ref: '#/components/schemas/Settlement'
        symbol:
          type: string
          description: The venue's spelling - `BTCUSDT`, `BTC-PERP`, `XBTUSD`.
        tick_size:
          $ref: '#/components/schemas/Price'
        underlying:
          $ref: '#/components/schemas/PerpetualUnderlying'
          description: 'What the contract tracks.


            Perpetuals started on crypto and did not stay there: the same structure

            now wraps equity indices and event outcomes, and the contract mechanics

            are identical in each. This says what the exposure actually is, so a

            risk check can ask what it is looking at without parsing a ticker.'
        venue:
          type: string
    Crypto:
      type: object
      description: 'Spot crypto: the asset itself, held outright.


        # Precision


        The type is not the constraint here, and this note exists to say so.


        [`Quantity`] holds eighteen decimal places, so a satoshi - `0.00000001` -

        has ten places to spare, and on-chain token amounts at their own native

        precision fit without rounding. Crypto is the asset class that used to make

        this worth reading: while the scale was six, a bitcoin size was silently

        rounded two places short of the asset''s own divisibility, exact enough to

        order with and wrong for anything reconciling a balance. See

        [`SCALE`](crate::numeric::SCALE) for why that is no longer true of any

        value this crate carries.


        What does constrain a size is [`Self::quantity_increment`], which is the

        venue''s own step and is data rather than a property of the type. A size that

        is exactly representable here can still be refused by the venue for being

        off the increment, so that field is the one to check against - not the width

        of the number.'
      required:
      - symbol
      - base
      - quote
      - venue
      - price_increment
      - quantity_increment
      properties:
        base:
          type: string
          description: The asset being bought - `BTC`.
        price_increment:
          $ref: '#/components/schemas/Price'
        quantity_increment:
          $ref: '#/components/schemas/Quantity'
          description: 'The smallest size step the venue accepts. See the precision note above

            for what this type can and cannot express.'
        quote:
          type: string
          description: The asset it is priced in - `USD`.
        symbol:
          type: string
          description: The venue's spelling - `BTC-USD` on Coinbase, `XXBTZUSD` on Kraken.
        venue:
          type: string
    ExerciseStyle:
      type: string
      enum:
      - american
      - european
    Currency:
      type: object
      description: A currency pair.
      required:
      - symbol
      - base
      - quote
      properties:
        base:
          type: string
          description: The currency being bought or sold - `EUR`.
        quote:
          type: string
          description: The currency it is priced in - `USD`.
        symbol:
          type: string
          description: The pair as the venue spells it - `EURUSD`, or `EUR/USD`.
    Equity:
      type: object
      description: A share in a listed company.
      required:
      - symbol
      properties:
        exchange:
          type:
          - string
          - 'null'
          description: 'The primary listing venue, where it was resolved.


            Where the security *is listed*, which is a fact the instruments

            catalogue owns - not where an order on it is sent. That is

            [`OrderVenue`](crate::broker::order::order_venue::OrderVenue), it lives

            on the order, and the two differ constantly: an equity listed on one

            exchange is routable to several, and two orders on this instrument can

            name different destinations while this field says the same thing for

            both.


            Optional because an equity can be traded without the listing ever being

            resolved - the order carries its own destination - so most equities

            reach this type without one.'
        symbol:
          type: string
    EvaluateResult:
      type: object
      required:
      - allowed
      - triggered
      properties:
        allowed:
          type: boolean
        triggered:
          type: array
          items:
            $ref: '#/components/schemas/TriggeredControl'
    PerpetualUnderlying:
      type: string
      description: 'What a [`Perpetual`] is a perpetual *on*.


        The mechanics do not change between these; the exposure does, and so does

        which desk is allowed to hold it.'
      enum:
      - UNSPECIFIED
      - CRYPTO
      - FUTURE
      - PREDICTION
    EvaluateRequest:
      type: object
      required:
      - account_id
      - symbol
      - quantity
      - instrument
      properties:
        account_id:
          type: string
          format: uuid
        instrument:
          $ref: '#/components/schemas/Instrument'
          description: 'What is being traded.


            Mandatory, and that is the safety property. A control has to be

            evaluated against the same instrument the order is placed in, so the

            caller resolves once and carries it: this service resolving

            independently would leave a window where it judged one instrument and

            the order was placed in another, which a catalogue sync between the

            two is enough to open.


            There is deliberately no "unknown" case. An order in something the

            catalogue cannot identify is not an order this platform can price, and

            the caller refuses it before reaching here rather than sending an

            absence for the evaluator to interpret.'
        quantity:
          $ref: '#/components/schemas/Quantity'
        side:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/OrderSide'
            description: 'Which way the order moves the position.


              Position size and daily loss limits need it: whether an order opens or

              closes a position is the whole question they ask. Optional on the wire

              so a caller built before it existed still parses, but a request without

              it is refused by any control that needs it rather than guessed at.'
        symbol:
          type: string
          description: 'The venue''s spelling, which is what symbol-scoped controls are keyed

            on. Kept beside `instrument` rather than read out of it: a control the

            tenant wrote against `ESZ25` has to match whether or not the catalogue

            resolved that order, and the key must not change depending on whether

            the resolution succeeded.'
    ControlScope:
      oneOf:
      - type: object
        required:
        - Organization
        properties:
          Organization:
            type: string
            format: uuid
      - type: object
        required:
        - Account
        properties:
          Account:
            type: string
            format: uuid
      - type: object
        required:
        - Symbol
        properties:
          Symbol:
            type: object
            required:
            - account_id
            - symbol
            properties:
              account_id:
                type: string
                format: uuid
              symbol:
                type: string
    Instrument:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/Equity'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - EQUITY
      - allOf:
        - $ref: '#/components/schemas/Future'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - FUTURE
      - allOf:
        - $ref: '#/components/schemas/OptionInstrument'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - OPTION
      - allOf:
        - $ref: '#/components/schemas/Currency'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - CURRENCY
      - allOf:
        - $ref: '#/components/schemas/Crypto'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - CRYPTO
      - allOf:
        - $ref: '#/components/schemas/Perpetual'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - PERPETUAL
      - allOf:
        - $ref: '#/components/schemas/Prediction'
        - type: object
          required:
          - asset_class
          properties:
            asset_class:
              type: string
              enum:
              - PREDICTION
      description: 'A tradable instrument, with the facts that make its price mean something.


        Not `Copy` - every variant carries at least one venue-spelled string - and

        deliberately `Eq` and `Hash`, so it can key a position map and sit inside

        the order parameter types, which are hashed.'
    Future:
      type: object
      description: A dated futures contract.
      required:
      - symbol
      - root
      - exchange
      - expiration
      - tick_size
      - multiplier
      - currency
      properties:
        currency:
          type: string
          description: What a point is denominated in - `USD`.
        exchange:
          type: string
          description: 'The exchange, in that exchange''s own spelling - `CME`, `CBOT`, `NYMEX`.


            A string rather than an enum because the set is open and every vendor

            spells it differently: Rithmic says `CME` where Databento says

            `GLBX.MDP3` for the same venue. An enum would have to pick one spelling

            and translate the rest, and this string goes back out on the order.'
        expiration:
          type: string
          format: date-time
          description: 'Last trade, not settlement - the moment the contract stops being

            tradable, which is what an adapter needs to know before sending.'
        multiplier:
          $ref: '#/components/schemas/Multiplier'
          description: Currency per full point of price movement - `50.0` for ES.
        root:
          type: string
          description: 'The contract family the month belongs to - `ES`.


            Held separately because it is what a strategy is actually expressed in.

            A position in "the ES front month" outlives any one `symbol`, and

            recovering the root by trimming characters off the end of a symbol is

            guesswork the venue already answered.'
        symbol:
          type: string
          description: The venue's spelling of this contract month - `ESZ5`, or `ESZ25`.
        tick_size:
          $ref: '#/components/schemas/Price'
    Price:
      type: string
    OptionInstrument:
      type: object
      description: A listed option on an equity or an index.
      required:
      - symbol
      - underlying
      - expiration
      - strike
      - option_type
      - exercise_style
      - multiplier
      properties:
        exchange:
          type:
          - string
          - 'null'
        exercise_style:
          $ref: '#/components/schemas/ExerciseStyle'
        expiration:
          type: string
          format: date-time
        multiplier:
          $ref: '#/components/schemas/Multiplier'
          description: Shares per contract - `100.0` for a standard listed option.
        option_type:
          $ref: '#/components/schemas/OptionType'
        strike:
          $ref: '#/components/schemas/Price'
        symbol:
          type: string
          description: The OCC ticker.
        tick_size:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Price'
        underlying:
          type: string
    Quantity:
      type: string
    ControlType:
      type: string
      enum:
      - Manual
      - Time
      - Risk
    FundingSchedule:
      type: object
      description: 'How often a [`Perpetual`] exchanges funding.


        The schedule, not the rate - see the note on [`Perpetual`] for why the rate

        is deliberately absent.'
      required:
      - interval_seconds
      properties:
        interval_seconds:
          type: integer
          format: int32
          description: 'Seconds between funding exchanges. Eight hours on most venues, one hour

            on some, and a handful settle continuously.'
          minimum: 0
    Multiplier:
      type: string
    Prediction:
      type: object
      description: 'A binary event contract, settling at [`Self::payout`] or at nothing.


        The price is a probability rather than a value, which is what separates this

        from everything else here: a contract trading at `0.62` is the market saying

        sixty-two percent, and it pays `payout` if the event resolves true. Sizing

        it with a share-price formula produces a number with no meaning.'
      required:
      - symbol
      - market
      - outcome
      - venue
      - payout
      - currency
      - tick_size
      properties:
        currency:
          type: string
          description: 'What the payout is denominated in - `USD` on Kalshi, `USDC` on

            Polymarket.'
        expiration:
          type:
          - string
          - 'null'
          format: date-time
          description: 'When the event resolves, where the venue has published it.


            `None` for a market resolving on an event rather than a clock - "when

            the bill passes" has no date until it does.'
        market:
          type: string
          description: 'The market this contract is one side of.


            Both sides of an event are separately tradable instruments with their

            own books, so the pair is only recoverable through this.'
        outcome:
          $ref: '#/components/schemas/PredictionOutcome'
          description: Which side of the market this contract pays on.
        payout:
          $ref: '#/components/schemas/Price'
          description: 'What one contract pays if it resolves in its favour - `1.0` on Kalshi

            and Polymarket both.'
        symbol:
          type: string
          description: 'The venue''s identifier for this contract - a Kalshi market ticker, or a

            Polymarket token id.'
        tick_size:
          $ref: '#/components/schemas/Price'
        venue:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    clientCredentials:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Machine bearer token minted via the client_credentials grant.
x-tagGroups:
- name: Organization
  tags:
  - Organization Controls
- name: Account
  tags:
  - Account Manual Controls
  - Account Risk Controls
  - Account Time Controls
- name: Symbols
  tags:
  - Symbol Manual Controls
  - Symbol Risk Controls
  - Symbol Time Controls
  - Effective Controls
- name: Evaluation
  tags:
  - Control Evaluation