> ## Documentation Index > Fetch the complete documentation index at: https://docs.compasslabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Aggregated Hyperliquid activity for a user > Return positions, fills, open orders, and (optionally) builder approval state for an end-user in one normalized payload. Each section is fetched in parallel from the Hyperliquid `info` API. If a single upstream call fails the corresponding section returns ``null`` and an entry is added to ``partial_errors``; if every section fails the endpoint responds with 502. Pass ``builder`` to additionally include the user's current approved max fee rate for that builder (used by dashboards to decide whether to prompt the user to sign an `approveBuilderFee` action). ## OpenAPI ````yaml /v2/combined_spec.json get /v2/global_markets_perps/activity openapi: 3.1.0 info: title: Compass API description: Compass Labs DeFi API version: 0.0.1 servers: - url: https://api.compasslabs.ai description: Production server security: - ApiKeyAuth: [] paths: /v2/global_markets_perps/activity: get: tags: - Global Markets Perps summary: Aggregated Hyperliquid activity for a user description: >- Return positions, fills, open orders, and (optionally) builder approval state for an end-user in one normalized payload. Each section is fetched in parallel from the Hyperliquid `info` API. If a single upstream call fails the corresponding section returns ``null`` and an entry is added to ``partial_errors``; if every section fails the endpoint responds with 502. Pass ``builder`` to additionally include the user's current approved max fee rate for that builder (used by dashboards to decide whether to prompt the user to sign an `approveBuilderFee` action). operationId: v2_global_markets_perps_activity parameters: - name: owner in: query required: true schema: type: string title: Owner default: '0x06A9aF046187895AcFc7258450B15397CAc67400' description: End-user EOA whose activity should be fetched. - name: builder in: query required: false schema: anyOf: - type: string - type: 'null' title: Builder default: null description: >- Optional builder address. When provided, the response includes the current builder-fee approval state for this (owner, builder) pair. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GlobalMarketsPerpsActivityResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: python label: Python (SDK) source: |- from compass_api_sdk import CompassAPI with CompassAPI( api_key_auth="", ) as compass_api: res = compass_api.global_markets_perps.global_markets_perps_activity(owner="0x06A9aF046187895AcFc7258450B15397CAc67400") # Handle response print(res) - lang: typescript label: Typescript (SDK) source: |- import { CompassApiSDK } from "@compass-labs/api-sdk"; const compassApiSDK = new CompassApiSDK({ apiKeyAuth: "", }); async function run() { const result = await compassApiSDK.globalMarketsPerps.globalMarketsPerpsActivity({ owner: "0x06A9aF046187895AcFc7258450B15397CAc67400", }); console.log(result); } run(); components: schemas: GlobalMarketsPerpsActivityResponse: properties: owner: type: string title: Owner description: Owner address that was queried (checksummed) positions: anyOf: - items: $ref: '#/components/schemas/GlobalMarketsPerpsPosition' type: array - type: 'null' title: Positions description: Open positions (null if the upstream call failed) account_value: anyOf: - type: string - type: 'null' title: Account Value description: Total account value in USDC (null if positions failed) withdrawable: anyOf: - type: string - type: 'null' title: Withdrawable description: Withdrawable USDC balance (null if positions failed) fills: anyOf: - items: $ref: '#/components/schemas/GlobalMarketsPerpsFill' type: array - type: 'null' title: Fills description: Recent fills (null if the upstream call failed) open_orders: anyOf: - items: $ref: '#/components/schemas/GlobalMarketsPerpsOpenOrder' type: array - type: 'null' title: Open Orders description: Resting orders (null if the upstream call failed) builder_approval: anyOf: - $ref: '#/components/schemas/GlobalMarketsPerpsBuilderApproval' - type: 'null' description: >- Builder approval state — only present when the `builder` query parameter was supplied (null on upstream failure). partial_errors: items: $ref: '#/components/schemas/GlobalMarketsPerpsActivityPartialError' type: array title: Partial Errors description: One entry per section that failed to load. type: object required: - owner - positions - account_value - withdrawable - fills - open_orders title: GlobalMarketsPerpsActivityResponse description: |- Aggregated HL activity for a single end-user. Any section may be ``null`` if its upstream HL call failed — see ``partial_errors`` for details. ``positions``/``fills``/``open_orders`` are always either a populated list or ``null``; an empty list means the user has no activity of that type, not a failure. example: account_value: '1058.32' builder_approval: approved: true builder: '0x42e1A5b3F1a17d9B2bC0c5d3f3aFf0d27e1c3Fa0' max_fee_tenth_bps: 50 fills: - asset: AAPL builder_fee: '0.1062' closed_pnl: '0' fee: '0.5310' order_id: 9182734102 price: '212.40' side: buy size: '5.00' time_ms: 1747010983250 open_orders: - asset: GOLD limit_price: '2450.00' order_id: 9182734201 reduce_only: false side: sell size: '0.500' time_ms: 1747011100000 owner: '0x1F31bAad9e2adC1Dc8B0FF8B0c2cF7D0e7d1A8c9' partial_errors: [] positions: - asset: AAPL asset_id: 12 entry_price: '212.40' funding_accrued: '-0.12' leverage: '3' liquidation_price: '180.12' margin_used: '354.00' mark_price: '213.88' side: long size: '5.00' unrealized_pnl: '7.40' withdrawable: '704.32' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError GlobalMarketsPerpsPosition: properties: asset: type: string title: Asset description: Asset ticker symbol asset_id: type: integer title: Asset Id description: Hyperliquid asset index side: type: string enum: - long - short title: Side description: 'Position side: ''long'' or ''short''' size: type: string title: Size description: Position size in contracts entry_price: type: string title: Entry Price description: Average entry price mark_price: type: string title: Mark Price description: Current mark price liquidation_price: anyOf: - type: string - type: 'null' title: Liquidation Price description: Estimated liquidation price unrealized_pnl: type: string title: Unrealized Pnl description: Unrealized PnL in USD leverage: type: string title: Leverage description: Current leverage margin_used: type: string title: Margin Used description: Margin used for this position in USD funding_accrued: type: string title: Funding Accrued description: Cumulative funding payments (negative = paid) type: object required: - asset - asset_id - side - size - entry_price - mark_price - unrealized_pnl - leverage - margin_used - funding_accrued title: GlobalMarketsPerpsPosition description: A single open perpetual futures position. GlobalMarketsPerpsFill: properties: asset: type: string title: Asset description: Asset ticker symbol (xyz prefix stripped) side: type: string enum: - buy - sell title: Side description: Order side price: type: string title: Price description: Fill price size: type: string title: Size description: Fill size in contracts fee: type: string title: Fee description: Total fee paid (USDC) builder_fee: anyOf: - type: string - type: 'null' title: Builder Fee description: Portion of fee routed to the builder address (USDC) closed_pnl: anyOf: - type: string - type: 'null' title: Closed Pnl description: Realized PnL closed by this fill (USDC) order_id: type: integer title: Order Id description: HL order id (oid) this fill belongs to time_ms: type: integer title: Time Ms description: Fill timestamp (ms since epoch) type: object required: - asset - side - price - size - fee - order_id - time_ms title: GlobalMarketsPerpsFill description: A single fill (executed trade) from HL `userFills`. GlobalMarketsPerpsOpenOrder: properties: asset: type: string title: Asset description: Asset ticker symbol (xyz prefix stripped) side: type: string enum: - buy - sell title: Side description: Order side limit_price: type: string title: Limit Price description: Limit price size: type: string title: Size description: Order size in contracts order_id: type: integer title: Order Id description: HL order id (oid) time_ms: type: integer title: Time Ms description: Order timestamp (ms since epoch) reduce_only: type: boolean title: Reduce Only description: True if order can only reduce position type: object required: - asset - side - limit_price - size - order_id - time_ms - reduce_only title: GlobalMarketsPerpsOpenOrder description: A single resting order from HL `openOrders`. GlobalMarketsPerpsBuilderApproval: properties: builder: type: string title: Builder description: Builder address that was queried max_fee_tenth_bps: type: integer title: Max Fee Tenth Bps description: >- Maximum fee rate the user has approved for this builder, in tenths of basis points (10 = 1bp = 0.01%). Zero means the user has not approved. approved: type: boolean title: Approved description: Convenience flag — true when max_fee_tenth_bps > 0 type: object required: - builder - max_fee_tenth_bps - approved title: GlobalMarketsPerpsBuilderApproval description: Current builder-fee approval state for a (user, builder) pair. GlobalMarketsPerpsActivityPartialError: properties: section: type: string enum: - positions - fills - open_orders - builder_approval title: Section message: type: string title: Message type: object required: - section - message title: GlobalMarketsPerpsActivityPartialError description: One section of /activity failed to load. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Compass API Key. Get your key [here](https://www.compasslabs.ai/dashboard). ````