> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get activity

> Get a combined, newest-first feed of a wallet's actions and venue events.

Each item has `type` of `event` (with an `event` object) or `action` (with an `action` object); see [Activity](/api-reference/perps-api/objects#activity). Requires `address` and `providerId` or `providerIds`. `actionStatus` and `actionStatuses` (up to 7) filter only action items; events are never filtered by them. This is a paginated GET feed, not a subscription.


## OpenAPI

````yaml openapi-perps.json GET /v1/activity
openapi: 3.0.0
info:
  title: 'Yield API: Trade (Perps)'
  description: >-
    API Documentation. Errors follow a uniform envelope with `details.code` from
    the public catalog (https://docs.yield.xyz). ValidationPipe failures use
    `validation.message: string[]`.
  version: '1.0'
  contact: {}
servers:
  - url: https://perps.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: Browse and discover perps markets, networks, and providers
  - name: Portfolio
    description: User-specific positions, orders, and balances
  - name: Actions
    description: Generate transactions to open, close, and manage positions
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/activity:
    get:
      tags:
        - Activity
        - Actions
      summary: Get unified perp activity
      description: >-
        Paginated chronological feed of timeline events and user actions for an
        address on one or more providers (newest first). Pass providerId or
        providerIds. Events use occurredAt; actions use createdAt.
      operationId: ActivityController_getActivity_v1
      parameters:
        - name: offset
          required: false
          in: query
          description: Offset for pagination
          schema:
            minimum: 0
            default: 0
            example: 0
            type: number
        - name: limit
          required: false
          in: query
          description: Maximum number of items to return
          schema:
            minimum: 1
            maximum: 500
            default: 100
            example: 100
            type: number
        - name: providerId
          required: false
          in: query
          description: >-
            Single provider identifier. At least one of providerId or
            providerIds must be provided.
          schema:
            example: hyperliquid
            type: string
            enum:
              - hyperliquid
              - hyperliquid-xyz
        - name: providerIds
          required: false
          in: query
          description: >-
            Filter by multiple providers (CSV, repeated query params, or JSON
            array). At least one of providerId or providerIds must be provided.
            When both providerId and providerIds are set, results include all
            listed providers.
          schema:
            example:
              - hyperliquid
              - hyperliquid-xyz
            type: array
            items:
              type: string
              enum:
                - hyperliquid
                - hyperliquid-xyz
        - name: address
          required: true
          in: query
          description: User wallet address
          schema:
            example: '0xb8c8eb8efc68796e766f6ab320db8c165c064949'
            type: string
        - name: actionStatus
          required: false
          in: query
          description: >-
            If provided, filters only action items by their status. Timeline
            events are not affected.
          schema:
            $ref: '#/components/schemas/ActionStatus'
        - name: actionStatuses
          required: false
          in: query
          description: >-
            Filter by multiple action statuses (supports CSV or repeated query
            params)
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ActionStatus'
      responses:
        '200':
          description: Paginated unified activity
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponseDto'
                  - properties:
                      items:
                        type: array
                        items:
                          oneOf:
                            - $ref: '#/components/schemas/ActivityEventItemDto'
                            - $ref: '#/components/schemas/ActivityActionItemDto'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 401
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Invalid API key
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Invalid API key
                      code:
                        type: string
                        example: AUTH_INVALID_API_KEY
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 429
                  timestamp:
                    type: string
                    example: '2026-05-04T12:00:00.000Z'
                  path:
                    type: string
                    example: /v1/actions
                  message:
                    type: string
                    example: Rate limit exceeded
                  details:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Rate limit exceeded
                      code:
                        type: string
                        example: RATE_LIMIT_EXCEEDED
                      error:
                        type: string
                        example: Too Many Requests
                      retryAfter:
                        type: number
                        example: 30
      security:
        - ApiKey: []
components:
  schemas:
    ActionStatus:
      type: string
      enum:
        - CANCELED
        - CREATED
        - WAITING_FOR_NEXT
        - PROCESSING
        - FAILED
        - SUCCESS
        - STALE
      description: Current action status
    PaginatedResponseDto:
      type: object
      properties:
        total:
          type: number
          description: Total number of items available
          example: 150
        offset:
          type: number
          description: Offset of the current page
          example: 0
        limit:
          type: number
          description: Limit of the current page
          example: 100
      required:
        - total
        - offset
        - limit
    ActivityEventItemDto:
      type: object
      properties:
        type:
          example: event
          allOf:
            - $ref: '#/components/schemas/ActivityItemType'
        event:
          $ref: '#/components/schemas/EventDto'
      required:
        - type
        - event
    ActivityActionItemDto:
      type: object
      properties:
        type:
          example: action
          allOf:
            - $ref: '#/components/schemas/ActivityItemType'
        action:
          $ref: '#/components/schemas/ActionDto'
      required:
        - type
        - action
    ActivityItemType:
      type: string
      enum:
        - event
        - action
    EventDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventType:
          allOf:
            - $ref: '#/components/schemas/PerpEventType'
        providerId:
          type: string
          example: hyperliquid
        occurredAt:
          type: string
          format: date-time
        marketId:
          type: string
          nullable: true
        perpActionId:
          type: string
          nullable: true
          format: uuid
          description: Linked action; null for liquidations
        providerOrderId:
          type: string
          nullable: true
          description: Venue order identifier (e.g. Hyperliquid oid)
        explorerUrl:
          type: string
          nullable: true
          description: Block explorer URL for the settlement transaction
          example: >-
            https://app.hyperliquid.xyz/explorer/tx/0x8a3fb2c1d4e5f67890abcdef12345678901234567890abcdef1234567890abcd
        order:
          description: Normalized order details for the venue event
          allOf:
            - $ref: '#/components/schemas/EventOrderDto'
      required:
        - id
        - eventType
        - providerId
        - occurredAt
        - order
    ActionDto:
      type: object
      properties:
        id:
          type: string
          description: Unique action identifier (UUID)
          example: 550e8400-e29b-41d4-a716-446655440000
        providerId:
          type: string
          description: Provider identifier
          example: hyperliquid
        action:
          description: Action type executed
          example: open
          allOf:
            - $ref: '#/components/schemas/PerpActionTypes'
        status:
          description: Current action status
          example: CREATED
          allOf:
            - $ref: '#/components/schemas/ActionStatus'
        summary:
          description: Human-readable breakdown of what this action does
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/ActionSummaryDto'
        signedMetadata:
          type: object
          description: >-
            TLV-encoded, secp256k1-signed metadata.


            Hex string of concatenated TLV fields. Each field: Tag (1 byte) +
            Length (1 byte) + Value (N bytes). Tags > 0x7f use a 3-byte header:
            0x81 prefix + Tag (1 byte) + Length (1 byte).


            Fields in order: STRUCTURE_TYPE (0x01), VERSION (0x02), ACTION_TYPE
            (0x81 0xd0, u8: order=0x00 modify=0x01 cancel=0x02
            updateLeverage=0x03 close=0x04 updateIsolatedMargin=0x05), ASSET_ID
            (0x81 0xd1, uint32 BE), ASSET_TICKER (0x24, UTF-8), NETWORK_TYPE
            (0x81 0xd2), BUILDER_ADDRESS (0x81 0xd3, 20 bytes, optional), MARGIN
            (0x81 0xd4, u64 big-endian, USD value with 6 decimal precision, e.g.
            87500000 = $87.50, optional), LEVERAGE (0x81 0xd5, u32 big-endian,
            optional), SIGNATURE (0x15, DER-encoded secp256k1 over SHA-256 of
            preceding bytes).
          example: 01012b02010181d0010081d1040000000b24034152421547...
        transactions:
          description: Unsigned transactions to sign and submit
          type: array
          items:
            $ref: '#/components/schemas/TransactionDto'
        createdAt:
          type: string
          description: When the action was created
          format: date-time
          example: '2026-02-19T10:23:45.000Z'
        completedAt:
          type: string
          description: When the action completed (null if still in progress)
          format: date-time
          nullable: true
          example: '2026-02-19T10:23:48.000Z'
      required:
        - id
        - providerId
        - action
        - status
        - summary
        - transactions
        - createdAt
        - completedAt
    PerpEventType:
      type: string
      enum:
        - order_filled
        - liquidation
        - stop_loss_triggered
        - take_profit_triggered
    EventOrderDto:
      type: object
      properties:
        orderId:
          type: string
          description: Venue order identifier (e.g. Hyperliquid oid)
          example: '394438950581'
        marketId:
          type: string
          description: Market identifier
          example: hyperliquid-eth-usdc
        asset:
          type: string
          description: Base asset ticker
          example: ETH
        side:
          description: Order side
          example: buy
          allOf:
            - $ref: '#/components/schemas/OrderSide'
        type:
          description: Normalized order type
          example: market
          allOf:
            - $ref: '#/components/schemas/OrderType'
        originalSizeBase:
          type: string
          description: Original order size in base asset units
          example: '0.0063'
        remainingSizeBase:
          type: string
          description: Remaining order size in base asset units
          example: '0.0'
        limitPrice:
          type: number
          description: Limit price
          example: 2395.2
        timeInForce:
          description: Normalized time in force
          example: ioc
          allOf:
            - $ref: '#/components/schemas/EventOrderTimeInForce'
        triggerPrice:
          type: number
          description: Trigger price when present on a trigger order
          example: 2500
        reduceOnly:
          type: boolean
          description: Reduce only flag
          example: false
        isPositionLevel:
          type: boolean
          description: Whether the order is a position-level TP/SL order
          example: false
        clientOrderId:
          type: object
          description: Client-supplied order id when present
          example: null
          nullable: true
        childOrderIds:
          description: Child order identifiers
          example: []
          type: array
          items:
            type: string
        createdAt:
          type: string
          description: Order creation timestamp
          format: date-time
          example: '2026-04-23T07:52:05.187Z'
        closedPnl:
          type: string
          description: >-
            PnL realized when an order closes, net of fees in USDC
            (string-encoded decimal). Absent on open / non-closing fills.
          example: '-12.45'
        fillPrice:
          type: number
          description: >-
            Realized fill price for fill-sourced events (e.g. order_filled,
            stop_loss_triggered). One per partial fill — aggregate across rows
            with the same orderId for an order-level average.
          example: 2500.5
      required:
        - orderId
        - marketId
        - asset
        - side
        - type
        - originalSizeBase
        - remainingSizeBase
        - reduceOnly
        - isPositionLevel
        - clientOrderId
        - childOrderIds
        - createdAt
    PerpActionTypes:
      type: string
      enum:
        - open
        - close
        - updateLeverage
        - stopLoss
        - takeProfit
        - cancelOrder
        - editOrder
        - fund
        - withdraw
        - approveAgent
        - approveBuilderFee
        - updateMargin
        - setTpAndSl
        - setUnifiedAccount
      description: Supported action types
    ActionSummaryDto:
      type: object
      properties:
        type:
          type: string
          description: Human-readable action label
          enum:
            - Open Position
            - Close Position
            - Stop Loss
            - Take Profit
            - Set TP & SL
            - Set Unified Account
            - Cancel Order
            - Edit Order
            - Update Leverage
            - Update Margin
            - Fund Account
            - Withdraw
            - Approve Agent
            - Approve Builder Fee
          example: Open Position
        assetId:
          type: number
          example: 11
        orderType:
          type: string
          enum:
            - market
            - limit
          example: market
        direction:
          type: string
          enum:
            - long
            - short
          example: long
        asset:
          type: string
          example: ETH
        price:
          type: number
          example: 3500
        size:
          type: string
          example: '0.5'
        leverage:
          type: number
          example: 40
        collateral:
          type: string
          example: '87.50'
        fee:
          type: string
          description: Fee rate as decimal string
          example: '0.001'
        orderValue:
          type: number
          description: >-
            Actual position notional value after size quantization (orderPrice ×
            quantizedSize)
          example: 1750.25
        stopLoss:
          type: number
          example: 3200
        takeProfit:
          type: number
          example: 4000
        oldLiquidationPrice:
          type: number
          description: 'Update Margin: liquidation price before this margin change.'
          example: 1850.5
        estimatedLiquidationPrice:
          type: number
          description: Approximation — actual value depends on exchange mechanics
          example: 1920.3
        oldStopLoss:
          type: number
          example: 3000
        oldTakeProfit:
          type: number
          example: 4200
        marginMode:
          type: string
          enum:
            - cross
            - isolated
          example: isolated
        orderId:
          type: string
          example: '12345'
        orderIds:
          example:
            - '12345'
            - '67890'
          type: array
          items:
            type: string
        cancelledOrderTypes:
          type: array
          description: >-
            Cancel order: trigger order types cancelled when they can be
            inferred
          example:
            - tp
            - sl
          items:
            type: string
            enum:
              - tp
              - sl
        amount:
          type: string
          example: '100'
        fromToken:
          $ref: '#/components/schemas/TokenIdentifierDto'
        method:
          type: string
          example: bridge2
        agentAddress:
          type: string
          example: 0x1234...
        agentName:
          type: string
          example: Trading Bot 1
        enabled:
          type: boolean
          description: >-
            Set Unified Account: whether unified account mode is being enabled
            (true) or disabled (false).
          example: true
        closedPrice:
          type: number
          description: >-
            Close position: expected close price at submission (limit price if
            limit close, else mark price)
          example: 1000
        pnl:
          type: string
          description: >-
            Close position: unrealized Pnl on the positon at submission
            (expected PnL if fully closing at mark)
          example: '100'
        margin:
          type: string
          description: >-
            Close position: deposited margin for the position at submission
            (isolated margin only, excludes unrealized PnL)
          example: '450.00'
        entryPrice:
          type: number
          example: 3500
        exitPrice:
          type: number
          example: 3500
      required:
        - type
    TransactionDto:
      type: object
      properties:
        id:
          type: string
          description: Transaction ID for API tracking (UUID)
          example: 550e8400-e29b-41d4-a716-446655440000
        network:
          description: Network identifier
          example: hyperliquid
          allOf:
            - $ref: '#/components/schemas/Networks'
        chainId:
          type: string
          description: Chain ID
          example: '1337'
        type:
          description: Transaction type
          example: OPEN_POSITION
          allOf:
            - $ref: '#/components/schemas/PerpTransactionType'
        status:
          description: Current transaction status
          example: CREATED
          allOf:
            - $ref: '#/components/schemas/PerpTransactionStatus'
        address:
          type: string
          description: User address
          example: 0x123...
        args:
          description: Action arguments
          allOf:
            - $ref: '#/components/schemas/ArgumentsDto'
        signingFormat:
          description: Signing format required
          example: EIP712_TYPED_DATA
          allOf:
            - $ref: '#/components/schemas/SigningFormat'
        signablePayload:
          type: object
          description: Unsigned transaction payload to sign
          example:
            domain:
              name: Hyperliquid
              version: '1'
              chainId: 1337
            types: {}
            message: {}
        rawPayload:
          type: object
          description: >-
            Raw action payload with nonce that this transaction commits to. Use
            it to independently recompute the EIP-712 connectionId and verify
            transaction integrity. Present for L1 transactions; undefined for
            standard EVM transactions where signablePayload is self-describing.
          example:
            type: order
            orders:
              - a: 4
                b: true
                p: '3500.0'
                s: '0.5'
                r: false
                t:
                  limit:
                    tif: Gtc
            grouping: na
            nonce: 1706198400000
        explorerUrls:
          description: >-
            Block explorer URLs derived from timeline fills for this
            transaction’s venue order ids (distinct L1 settlements, sorted).
            Falls back to a single URL from `hash` when no matching timeline
            rows yet.
          example:
            - >-
              https://app.hyperliquid.xyz/explorer/tx/0x8a3fb2c1d4e5f67890abcdef12345678
          type: array
          items:
            type: string
      required:
        - id
        - network
        - chainId
        - type
        - status
        - address
        - explorerUrls
    OrderSide:
      type: string
      enum:
        - buy
        - sell
      description: Order side
    OrderType:
      type: string
      enum:
        - market
        - limit
        - stop_loss
        - take_profit
      description: Order type
    EventOrderTimeInForce:
      type: string
      enum:
        - ioc
        - gtc
        - alo
      description: Normalized time in force
    TokenIdentifierDto:
      type: object
      properties:
        network:
          description: The blockchain network where the token is located
          example: ethereum
          allOf:
            - $ref: '#/components/schemas/Networks'
        address:
          type: string
          description: Token contract address. Leave empty for native tokens like ETH.
          example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
      required:
        - network
    Networks:
      type: string
      enum:
        - ethereum
        - ethereum-goerli
        - ethereum-holesky
        - ethereum-sepolia
        - ethereum-hoodi
        - arbitrum
        - base
        - base-sepolia
        - gnosis
        - optimism
        - polygon
        - polygon-amoy
        - starknet
        - zksync
        - linea
        - unichain
        - plume
        - monad-testnet
        - monad
        - robinhood
        - robinhood-testnet
        - arc-testnet
        - arc
        - avalanche-c
        - avalanche-c-atomic
        - avalanche-p
        - binance
        - celo
        - fantom
        - harmony
        - moonriver
        - okc
        - viction
        - core
        - sonic
        - plasma
        - katana
        - hyperevm
        - tempo
        - pharos
        - agoric
        - akash
        - axelar
        - band-protocol
        - bitsong
        - canto
        - chihuahua
        - comdex
        - coreum
        - cosmos
        - crescent
        - cronos
        - cudos
        - desmos
        - dydx
        - evmos
        - fetch-ai
        - gravity-bridge
        - injective
        - irisnet
        - juno
        - kava
        - ki-network
        - mars-protocol
        - nym
        - okex-chain
        - onomy
        - osmosis
        - persistence
        - quicksilver
        - regen
        - secret
        - sentinel
        - sommelier
        - stafi
        - stargaze
        - stride
        - teritori
        - tgrade
        - umee
        - sei
        - mantra
        - celestia
        - saga
        - zetachain
        - dymension
        - humansai
        - neutron
        - polkadot
        - kusama
        - westend
        - bittensor
        - aptos
        - binancebeacon
        - cardano
        - near
        - solana
        - solana-devnet
        - stellar
        - stellar-testnet
        - sui
        - tezos
        - tron
        - ton
        - ton-testnet
        - hyperliquid
      description: Blockchain network
    PerpTransactionType:
      type: string
      enum:
        - APPROVAL
        - OPEN_POSITION
        - CLOSE_POSITION
        - UPDATE_LEVERAGE
        - STOP_LOSS
        - TAKE_PROFIT
        - CANCEL_ORDER
        - EDIT_ORDER
        - FUND
        - WITHDRAW
        - APPROVE_BUILDER_FEE
        - ENABLE_DEX_ABSTRACTION
        - APPROVE_AGENT
        - UPDATE_MARGIN
        - SET_TP_AND_SL
        - SET_USER_ABSTRACTION
      description: Transaction type
    PerpTransactionStatus:
      type: string
      enum:
        - CREATED
        - QUEUED
        - BROADCASTED
        - CONFIRMED
        - FAILED
        - NOT_FOUND
      description: Current transaction status
    ArgumentsDto:
      type: object
      properties:
        marketId:
          type: string
          description: Market identifier
          example: hyperliquid-eth-usdc
        side:
          description: Position side - long (buy) or short (sell)
          example: long
          allOf:
            - $ref: '#/components/schemas/PositionSide'
        amount:
          type: string
          description: 'Margin/collateral amount in USD (alternative to size). Min: $10'
          example: '100'
        size:
          type: string
          description: 'Position size in USD (alternative to amount). Min: $10'
          example: '1000'
        leverage:
          type: number
          description: Leverage multiplier
          example: 10
        marginMode:
          description: >-
            Margin mode - isolated (dedicated collateral) or cross (shared
            collateral)
          example: isolated
          allOf:
            - $ref: '#/components/schemas/MarginMode'
        limitPrice:
          type: number
          description: >-
            Limit price. If provided, order will be placed as a limit order at
            this price. If not provided, order executes immediately as a market
            order.
          example: 2000
        stopLossPrice:
          type: number
          description: Stop loss trigger price
          example: 1800
        takeProfitPrice:
          type: number
          description: Take profit trigger price
          example: 2200
        orderId:
          type: string
          description: >-
            Order ID (for cancelOrder, or for updating existing
            stopLoss/takeProfit)
          example: '12345'
        orderIds:
          description: Order IDs for batch cancelOrder
          example:
            - '12345'
            - '67890'
          type: array
          items:
            type: string
        assetIndex:
          type: number
          description: Asset index (internal)
          example: 0
        fromToken:
          description: >-
            Source token for cross-chain funding (bridge/swap from another
            chain)
          allOf:
            - $ref: '#/components/schemas/TokenIdentifierDto'
        agentAddress:
          type: string
          description: Agent wallet address to approve (for approveAgent action)
          example: '0x1234567890abcdef1234567890abcdef12345678'
        agentName:
          type: string
          description: >-
            Name for the agent wallet (for approveAgent action). If not
            provided, defaults to "key".
          example: My Trading Bot
        validUntil:
          type: number
          description: >-
            Unix timestamp (seconds) when agent approval expires. If not
            provided, never expires.
          example: 1735689600
        stopLossOrderId:
          type: string
          description: >-
            Existing stop loss order ID (for updating via SET_TP_AND_SL bundled
            action)
          example: '12345'
        takeProfitOrderId:
          type: string
          description: >-
            Existing take profit order ID (for updating via SET_TP_AND_SL
            bundled action)
          example: '12346'
        skipApproval:
          type: boolean
          description: Skip the ERC20 approval transaction.
          example: true
        fundingMethod:
          description: >-
            Funding method: "bridge2" for direct Hyperliquid Bridge2 (Arbitrum
            USDC only), "lifi" for LiFi bridging (any token/network). If not
            provided, defaults to bridge2 for Arbitrum USDC and lifi for others.
          example: bridge2
          allOf:
            - $ref: '#/components/schemas/FundingMethod'
        enabled:
          type: boolean
          description: >-
            Enable or disable Unified Account Mode (setUnifiedAccount action).
            When true, collateral is unified across Hyperliquid venues.
          example: true
    SigningFormat:
      type: string
      enum:
        - EVM_TRANSACTION
        - EIP712_TYPED_DATA
        - SOLANA_TRANSACTION
        - COSMOS_TRANSACTION
      description: Signing format required
    PositionSide:
      type: string
      enum:
        - long
        - short
      description: Position side
    MarginMode:
      type: string
      enum:
        - cross
        - isolated
      description: Margin mode
    FundingMethod:
      type: string
      enum:
        - bridge2
        - lifi
      description: >-
        Funding method: "bridge2" for direct Hyperliquid Bridge2 (Arbitrum USDC
        only), "lifi" for LiFi bridging (any token/network). If not provided,
        defaults to bridge2 for Arbitrum USDC and lifi for others.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.