# yaml-language-server: $schema=https://spec.openapis.org/oas/3.1/schema/2022-10-07
openapi: 3.1.0
info:
  title: "⚡ HyperCore API"
  version: "1.0"
  description: |
    HyperCore read and historical methods for private preview.
servers:
  - url: https://api.g.alchemy.com/hypercore/v1
    description: HyperCore REST base URL.
paths:
  "/{apiKey}/info":
    post:
      operationId: get-info
      summary: Get info
      description: |
        Execute a native-compatible HyperCore read selected by the required type discriminator.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/InfoRequest"
            examples:
              userFills:
                value:
                  type: userFills
                  user: "0x1111111111111111111111111111111111111111"
              userFillsByTime:
                value:
                  type: userFillsByTime
                  user: "0x1111111111111111111111111111111111111111"
                  startTime: 1780000000000
                  endTime: 1780086400000
      responses:
        "200":
          "$ref": "#/components/responses/InfoResponse"
  "/{apiKey}/user-fills":
    post:
      operationId: get-user-fills
      summary: Get user fills
      description: |
        Retrieve fills associated with a user. Coming with HyperCore; this route is not yet callable.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserFillsRequest"
            examples:
              userFills:
                value:
                  type: userFills
                  user: "0x1111111111111111111111111111111111111111"
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserFillsResponse"
              examples:
                default:
                  "$ref": "#/components/examples/UserFillsResponse"
  "/{apiKey}/user-fills-by-time":
    post:
      operationId: get-user-fills-by-time
      summary: Get user fills by time
      description: |
        Retrieve fills associated with a user over a time range. Coming with HyperCore; this route is not yet callable.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserFillsByTimeRequest"
            examples:
              userFillsByTime:
                value:
                  type: userFillsByTime
                  user: "0x1111111111111111111111111111111111111111"
                  startTime: 1780000000000
                  endTime: 1780086400000
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserFillsByTimeResponse"
              examples:
                default:
                  "$ref": "#/components/examples/UserFillsByTimeResponse"
  "/{apiKey}/clearinghouse-state":
    post:
      operationId: get-clearinghouse-state
      summary: Get clearinghouse state
      description: |
        Retrieve clearinghouse state associated with a user.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ClearinghouseStateRequest"
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ClearinghouseStateResponse"
              examples:
                default:
                  "$ref": "#/components/examples/ClearinghouseStateResponse"
  "/{apiKey}/historical-orders":
    post:
      operationId: get-historical-orders
      summary: Get historical orders
      description: |
        Retrieve historical orders associated with a user. Coming with HyperCore; this route is not yet callable.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/HistoricalOrdersRequest"
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HistoricalOrdersResponse"
              examples:
                default:
                  "$ref": "#/components/examples/HistoricalOrdersResponse"
  "/{apiKey}/portfolio-state":
    post:
      operationId: get-portfolio-state
      summary: Get normalized portfolio state
      description: |
        Retrieve a normalized portfolio-state composite for a user. Coming with HyperCore; this route is not yet callable.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserRequest"
            examples:
              default:
                value:
                  user: "0x1111111111111111111111111111111111111111"
                  include: [positions, balances, margin]
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PortfolioState"
              examples:
                default:
                  "$ref": "#/components/examples/PortfolioStateResponse"
  "/{apiKey}/extra-agents":
    post:
      operationId: get-extra-agents
      summary: Get agent and API-wallet state
      description: |
        Retrieve agent and API-wallet information associated with a user.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserRequest"
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExtraAgentsResponse"
              examples:
                default:
                  "$ref": "#/components/examples/ExtraAgentsResponse"
  "/{apiKey}/l2-book-diff-snapshot":
    post:
      operationId: get-l2-book-diff-snapshot
      summary: Get an L2 book snapshot for diff-stream bootstrap
      description: |
        Retrieve aggregated L2 books at a common block height with each market's diff sequence.
      parameters:
        - "$ref": "#/components/parameters/apiKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/L2BookDiffSnapshotRequest"
            examples:
              default:
                value:
                  coins: [BTC, ETH]
                  nSigFigs: 5
                  mantissa: 2
                  nLevels: 20
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/L2BookDiffSnapshotResponse"
              examples:
                default:
                  "$ref": "#/components/examples/L2BookDiffSnapshotResponse"
components:
  parameters:
    apiKey:
      name: apiKey
      in: path
      required: true
      schema:
        type: string
  schemas:
    InfoTypeRequest:
      type: object
      required: [type]
      properties:
        type:
          type: string
          description: HyperCore `/info` request discriminator. Most values are native-compatible reads; `l4Snapshots` and `triggerOrderSnapshot` are Alchemy-original snapshot reads. The `portfolioState` and `extraAgents` composites are not `/info` discriminators; they are exposed as purpose-built endpoints at `/portfolio-state` and `/extra-agents`.
          enum:
            - openOrders
            - frontendOpenOrders
            - userFills
            - userFillsByTime
            - historicalOrders
            - userFunding
            - userNonFundingLedgerUpdates
            - clearinghouseState
            - spotClearinghouseState
            - userRateLimit
            - maxBuilderFee
            - subAccounts
            - userVaultEquities
            - userRole
            - userFees
            - userDexAbstraction
            - allMids
            - candleSnapshot
            - l4Snapshots
            - triggerOrderSnapshot
            - meta
            - spotMeta
            - metaAndAssetCtxs
            - spotMetaAndAssetCtxs
            - activeAssetData
            - predictedFundings
            - spotDeployState
            - perpDeployAuctionStatus
            - spotPairDeployAuctionStatus
            - vaultSummaries
            - vaultDetails
            - leadingVaults
            - delegations
            - delegatorSummary
            - delegatorHistory
            - delegatorRewards
            - validatorL1Votes
            - outcomeMeta
            - settledOutcome
            - outcomeTemplates
            - exchangeStatus
            - liquidatable
            - maxMarketOrderNtls
            - userToMultiSigSigners
            - perpsAtOpenInterestCap
            - marginTable
            - perpDexs
            - webData2
        user:
          "$ref": "#/components/schemas/Address"
        dex:
          type: string
          description: Perpetual DEX name. The empty string selects the first perpetual DEX.
        builder:
          "$ref": "#/components/schemas/Address"
        coin:
          type: string
        startTime:
          "$ref": "#/components/schemas/TimestampMs"
        endTime:
          "$ref": "#/components/schemas/TimestampMs"
        interval:
          type: string
        vaultAddress:
          "$ref": "#/components/schemas/Address"
        outcome:
          type: integer
        includeUsers:
          type: boolean
        includeTriggerOrders:
          type: boolean
      additionalProperties: true
      description: The fields required with `type` are defined by the selected native read.
    NativeInfoResponse: {}
    Address:
      type: string
      pattern: "^0x[a-fA-F0-9]{40}$"
      description: EVM-style account address.
    Cursor:
      type: string
      description: Opaque cursor. Store and return it unmodified; its format may change.
    TimestampMs:
      type: integer
      format: int64
      description: Unix timestamp in milliseconds.
    UserRequest:
      type: object
      required:
        - user
      properties:
        user:
          "$ref": "#/components/schemas/Address"
        startTime:
          "$ref": "#/components/schemas/TimestampMs"
        endTime:
          "$ref": "#/components/schemas/TimestampMs"
        cursor:
          "$ref": "#/components/schemas/Cursor"
        include:
          type: array
          items:
            type: string
    InfoRequest:
      anyOf:
        - "$ref": "#/components/schemas/UserFillsRequest"
        - "$ref": "#/components/schemas/UserFillsByTimeRequest"
        - "$ref": "#/components/schemas/HistoricalOrdersRequest"
        - "$ref": "#/components/schemas/UserFundingRequest"
        - "$ref": "#/components/schemas/UserLedgerRequest"
        - "$ref": "#/components/schemas/DelegationsRequest"
        - "$ref": "#/components/schemas/DelegatorHistoryRequest"
        - "$ref": "#/components/schemas/ClearinghouseStateRequest"
        - "$ref": "#/components/schemas/SpotClearinghouseStateRequest"
        - "$ref": "#/components/schemas/FrontendOpenOrdersRequest"
        - "$ref": "#/components/schemas/InfoTypeRequest"
      discriminator:
        propertyName: type
        mapping:
          userFills: "#/components/schemas/UserFillsRequest"
          userFillsByTime: "#/components/schemas/UserFillsByTimeRequest"
          historicalOrders: "#/components/schemas/HistoricalOrdersRequest"
          userFunding: "#/components/schemas/UserFundingRequest"
          userNonFundingLedgerUpdates: "#/components/schemas/UserLedgerRequest"
          delegations: "#/components/schemas/DelegationsRequest"
          delegatorHistory: "#/components/schemas/DelegatorHistoryRequest"
          clearinghouseState: "#/components/schemas/ClearinghouseStateRequest"
          spotClearinghouseState: "#/components/schemas/SpotClearinghouseStateRequest"
          frontendOpenOrders: "#/components/schemas/FrontendOpenOrdersRequest"
          openOrders: "#/components/schemas/InfoTypeRequest"
          userRateLimit: "#/components/schemas/InfoTypeRequest"
          maxBuilderFee: "#/components/schemas/InfoTypeRequest"
          subAccounts: "#/components/schemas/InfoTypeRequest"
          userVaultEquities: "#/components/schemas/InfoTypeRequest"
          userRole: "#/components/schemas/InfoTypeRequest"
          userFees: "#/components/schemas/InfoTypeRequest"
          userDexAbstraction: "#/components/schemas/InfoTypeRequest"
          allMids: "#/components/schemas/InfoTypeRequest"
          candleSnapshot: "#/components/schemas/InfoTypeRequest"
          l4Snapshots: "#/components/schemas/InfoTypeRequest"
          triggerOrderSnapshot: "#/components/schemas/InfoTypeRequest"
          meta: "#/components/schemas/InfoTypeRequest"
          spotMeta: "#/components/schemas/InfoTypeRequest"
          metaAndAssetCtxs: "#/components/schemas/InfoTypeRequest"
          spotMetaAndAssetCtxs: "#/components/schemas/InfoTypeRequest"
          activeAssetData: "#/components/schemas/InfoTypeRequest"
          predictedFundings: "#/components/schemas/InfoTypeRequest"
          spotDeployState: "#/components/schemas/InfoTypeRequest"
          perpDeployAuctionStatus: "#/components/schemas/InfoTypeRequest"
          spotPairDeployAuctionStatus: "#/components/schemas/InfoTypeRequest"
          vaultSummaries: "#/components/schemas/InfoTypeRequest"
          vaultDetails: "#/components/schemas/InfoTypeRequest"
          leadingVaults: "#/components/schemas/InfoTypeRequest"
          delegatorSummary: "#/components/schemas/InfoTypeRequest"
          delegatorRewards: "#/components/schemas/InfoTypeRequest"
          validatorL1Votes: "#/components/schemas/InfoTypeRequest"
          outcomeMeta: "#/components/schemas/InfoTypeRequest"
          settledOutcome: "#/components/schemas/InfoTypeRequest"
          outcomeTemplates: "#/components/schemas/InfoTypeRequest"
          exchangeStatus: "#/components/schemas/InfoTypeRequest"
          liquidatable: "#/components/schemas/InfoTypeRequest"
          maxMarketOrderNtls: "#/components/schemas/InfoTypeRequest"
          userToMultiSigSigners: "#/components/schemas/InfoTypeRequest"
          perpsAtOpenInterestCap: "#/components/schemas/InfoTypeRequest"
          marginTable: "#/components/schemas/InfoTypeRequest"
          perpDexs: "#/components/schemas/InfoTypeRequest"
          webData2: "#/components/schemas/InfoTypeRequest"
    InfoResponse:
      oneOf:
        - "$ref": "#/components/schemas/UserFillsResponse"
        - "$ref": "#/components/schemas/UserFillsByTimeResponse"
        - "$ref": "#/components/schemas/ClearinghouseStateResponse"
        - "$ref": "#/components/schemas/HistoricalOrdersResponse"
    UserFillsRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: userFills
    UserFillsByTimeRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
            - startTime
            - endTime
          properties:
            type:
              const: userFillsByTime
    HistoricalOrdersRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: historicalOrders
    UserFundingRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: userFunding
    UserLedgerRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: userNonFundingLedgerUpdates
    DelegationsRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: delegations
    DelegatorHistoryRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: delegatorHistory
    ClearinghouseStateRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: clearinghouseState
    SpotClearinghouseStateRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: spotClearinghouseState
    FrontendOpenOrdersRequest:
      allOf:
        - "$ref": "#/components/schemas/UserRequest"
        - type: object
          required:
            - type
          properties:
            type:
              const: frontendOpenOrders
    Fill:
      type: object
      properties:
        coin:
          type: string
        px:
          type: string
        sz:
          type: string
        side:
          type: string
          enum: [A, B]
        time:
          "$ref": "#/components/schemas/TimestampMs"
        tid:
          type: integer
        oid:
          type: integer
        closedPnl:
          type: string
        fee:
          type: string
        feeToken:
          type: string
    UserFillsResponse:
      type: object
      properties:
        fills:
          type: array
          items:
            "$ref": "#/components/schemas/Fill"
    UserFillsByTimeResponse:
      type: object
      properties:
        fills:
          type: array
          items:
            "$ref": "#/components/schemas/Fill"
        nextCursor:
          type: string
    HistoricalOrder:
      type: object
      properties:
        orderId:
          type: string
        coin:
          type: string
        side:
          type: string
          enum: [A, B]
        limitPx:
          type: string
        sz:
          type: string
        status:
          type: string
        timestamp:
          "$ref": "#/components/schemas/TimestampMs"
    HistoricalOrdersResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            "$ref": "#/components/schemas/HistoricalOrder"
    ClearinghouseStateResponse:
      type: object
      properties:
        marginSummary:
          type: object
          properties:
            accountValue:
              type: string
            totalMarginUsed:
              type: string
        assetPositions:
          type: array
          items:
            type: object
            properties:
              position:
                type: object
                properties:
                  coin:
                    type: string
                  szi:
                    type: string
                  entryPx:
                    type: string
                  unrealizedPnl:
                    type: string
    PortfolioState:
      type: object
      properties:
        user:
          "$ref": "#/components/schemas/Address"
        asOf:
          "$ref": "#/components/schemas/TimestampMs"
        perpetual:
          type: object
          additionalProperties: true
        spot:
          type: object
          additionalProperties: true
        margin:
          type: object
          additionalProperties: true
    Agent:
      type: object
      properties:
        address:
          "$ref": "#/components/schemas/Address"
        name:
          type: string
        permissions:
          type: array
          items:
            type: string
    ExtraAgentsResponse:
      type: object
      properties:
        user:
          "$ref": "#/components/schemas/Address"
        agents:
          type: array
          items:
            "$ref": "#/components/schemas/Agent"
    L2BookDiffSnapshotRequest:
      type: object
      required:
        - coins
      properties:
        coins:
          type: array
          minItems: 1
          items:
            type: string
          description: Markets to include in the snapshot.
        nSigFigs:
          type: integer
          enum: [2, 3, 4, 5]
          description: Significant-figure aggregation for price levels.
        mantissa:
          type: integer
          enum: [2, 5]
          description: Mantissa step. Valid only when nSigFigs is 5.
        nLevels:
          type: integer
          enum: [1, 10, 20, 50]
          description: Levels per side. Defaults to 20.
    L2BookLevel:
      type: object
      required:
        - px
        - sz
        - n
      properties:
        px:
          type: string
          description: Price as a decimal string.
        sz:
          type: string
          description: Total size at the price level.
        n:
          type: integer
          description: Number of orders at the price level.
    L2BookDiffSnapshotBook:
      type: object
      required:
        - coin
        - time
        - levels
        - seq
      properties:
        coin:
          type: string
          description: Market symbol.
        time:
          "$ref": "#/components/schemas/TimestampMs"
        levels:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: array
            items:
              "$ref": "#/components/schemas/L2BookLevel"
          description: Two-element tuple of bids and asks.
        seq:
          type: integer
          minimum: 0
          description: Per-market l2BookDiff sequence at the snapshot height.
    L2BookDiffSnapshotResponse:
      type: object
      required:
        - height
        - books
      properties:
        height:
          type: integer
          description: Block height reflected by every returned book.
        books:
          type: array
          items:
            "$ref": "#/components/schemas/L2BookDiffSnapshotBook"
  responses:
    InfoResponse:
      description: Successful native-compatible response.
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/NativeInfoResponse"
          examples:
            openOrders:
              value:
                - coin: BTC
                  limitPx: "29792.0"
                  oid: 91490942
                  side: A
                  sz: "0.0"
                  timestamp: 1681247412573
            frontendOpenOrders:
              value:
                - coin: BTC
                  isPositionTpsl: false
                  isTrigger: false
                  limitPx: "29792.0"
                  oid: 91490942
                  orderType: Limit
                  origSz: "5.0"
                  reduceOnly: false
                  side: A
                  sz: "5.0"
                  timestamp: 1681247412573
                  triggerCondition: N/A
                  triggerPx: "0.0"
            userRateLimit:
              value:
                cumVlm: "2854574.593578"
                nRequestsUsed: 2890
                nRequestsCap: 2864574
            maxBuilderFee:
              value: 1
            subAccounts:
              value:
                - name: Test
                  subAccountUser: "0x035605fc2f24d65300227189025e90a0d947f16c"
                  master: "0x8c967e73e6b15087c42a10d344cff4c96d877f1d"
                  clearinghouseState:
                    marginSummary:
                      accountValue: "29.78001"
                      totalNtlPos: "0.0"
                      totalRawUsd: "29.78001"
                      totalMarginUsed: "0.0"
                    crossMarginSummary:
                      accountValue: "29.78001"
                      totalNtlPos: "0.0"
                      totalRawUsd: "29.78001"
                      totalMarginUsed: "0.0"
                    crossMaintenanceMarginUsed: "0.0"
                    withdrawable: "29.78001"
                    assetPositions: []
                    time: 1733968369395
                  spotState:
                    balances:
                      - coin: USDC
                        token: 0
                        total: "0.22"
                        hold: "0.0"
                        entryNtl: "0.0"
            userVaultEquities:
              value:
                - vaultAddress: "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"
                  equity: "742500.082809"
            userRole:
              value: { role: user }
            userFees:
              value:
                dailyUserVlm:
                  - date: "2025-05-23"
                    userCross: "0.0"
                    userAdd: "0.0"
                    exchange: "2852367.0770729999"
                userCrossRate: "0.000315"
                userAddRate: "0.000105"
                userSpotCrossRate: "0.00049"
                userSpotAddRate: "0.00028"
                activeReferralDiscount: "0.0"
                trial: null
                feeTrialReward: "0.0"
                nextTrialAvailableTimestamp: null
            delegations:
              value:
                - validator: "0x5ac99df645f3414876c816caa18b2d234024b487"
                  amount: "12060.16529862"
                  lockedUntilTimestamp: 1735466781353
            delegatorSummary:
              value:
                delegated: "12060.16529862"
                undelegated: "0.0"
                totalPendingWithdrawal: "0.0"
                nPendingWithdrawals: 0
            userDexAbstraction:
              value: true
  examples:
    UserFillsResponse:
      value:
        fills:
          - coin: BTC
            px: "100000.0"
            sz: "0.01"
            side: B
            time: 1780000000000
            tid: 12345
            oid: 54321
            closedPnl: "0"
            fee: "0.20"
            feeToken: USDC
    UserFillsByTimeResponse:
      value:
        fills:
          - coin: BTC
            px: "100000.0"
            sz: "0.01"
            side: B
            time: 1780000000000
            tid: 12345
        nextCursor: optional-cursor
    HistoricalOrdersResponse:
      value:
        orders:
          - orderId: "54321"
            coin: BTC
            side: B
            limitPx: "100000.0"
            sz: "0.10"
            status: filled
            timestamp: 1780000000000
    ClearinghouseStateResponse:
      value:
        marginSummary:
          accountValue: "1000.00"
          totalMarginUsed: "100.00"
        assetPositions:
          - position:
              coin: BTC
              szi: "0.10"
              entryPx: "99000.0"
              unrealizedPnl: "100.0"
    PortfolioStateResponse:
      value:
        user: "0x1111111111111111111111111111111111111111"
        asOf: 1780000000000
        perpetual:
          accountValue: "1000.00"
          positions: []
        spot:
          balances: []
        margin:
          totalMarginUsed: "100.00"
    ExtraAgentsResponse:
      value:
        user: "0x1111111111111111111111111111111111111111"
        agents:
          - address: "0x4444444444444444444444444444444444444444"
            name: market-maker
            permissions: [trade]
    L2BookDiffSnapshotResponse:
      value:
        height: 123456
        books:
          - coin: BTC
            time: 1780000000000
            levels:
              - - px: "100000.0"
                  sz: "1.25"
                  n: 3
              - - px: "100001.0"
                  sz: "0.80"
                  n: 2
            seq: 42