> ## 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.

# List actions

> List a wallet's actions on one or more providers, newest first, filtered by status, type or market.

Requires `address` and at least one of `providerId` or `providerIds`. `status` filters by one value; `statuses` accepts up to 7 values as CSV or repeated parameters (when `statuses` is set, `status` is ignored). `type` filters by [action type](/api-reference/perps-api/objects#action-types). `limit` defaults to 100 (maximum 500).


## OpenAPI

````yaml openapi-perps.json GET /v1/actions
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/actions:
    get:
      tags:
        - Actions
        - Actions
      summary: Get user actions
      description: >-
        Retrieve all actions performed by a user on a specific provider, with
        optional filtering by status and action type. Returns a paginated list
        ordered by most recent first.
      operationId: ActionsController_getActions_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: status
          required: false
          in: query
          description: Filter by action status
          schema:
            $ref: '#/components/schemas/ActionStatus'
        - name: statuses
          required: false
          in: query
          description: >-
            Filter by multiple action statuses (supports CSV or repeated query
            params)
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ActionStatus'
        - name: type
          required: false
          in: query
          description: Filter by action type
          schema:
            $ref: '#/components/schemas/PerpActionTypes'
        - name: marketId
          required: false
          in: query
          description: Filter by market (e.g. hyperliquid-eth-usdc)
          schema:
            example: hyperliquid-eth-usdc
            type: string
      responses:
        '200':
          description: Paginated list of user actions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponseDto'
                  - properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ActionDto'
        '400':
          description: >-
            See https://docs.yield.xyz for `details.code` values. ValidationPipe
            failures use `validation.message: string[]` in place of `details`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - statusCode
                  - timestamp
                  - path
                  - message
                properties:
                  statusCode:
                    type: number
                  timestamp:
                    type: string
                    format: date-time
                  path:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Public error code — see https://docs.yield.xyz for the
                          full list.
                      error:
                        type: string
                        description: HTTP status text (e.g. "Bad Request").
                      message:
                        type: string
                        description: Domain message when present.
                      reason:
                        type: string
                        description: Provider reason when present.
                      retryAfter:
                        type: number
                        description: >-
                          Seconds to wait before retrying (rate-limit responses
                          only).
                  validation:
                    type: object
                    description: Present on ValidationPipe failures instead of `details`.
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        description: Class-validator constraint messages.
        '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
    PerpActionTypes:
      type: string
      enum:
        - open
        - close
        - updateLeverage
        - stopLoss
        - takeProfit
        - cancelOrder
        - editOrder
        - fund
        - withdraw
        - approveAgent
        - approveBuilderFee
        - updateMargin
        - setTpAndSl
        - setUnifiedAccount
      description: Supported action types
    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
    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
    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
    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.