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

# List orders

> Returns your orders, newest first, placed by any of your API keys.



## OpenAPI

````yaml /openapi.yaml get /v1/orders
openapi: 3.1.0
info:
  title: Trading API
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  version: '1'
  summary: Trade perpetual futures on Hyperliquid with plain HTTP requests.
  description: >
    The Trading API places market orders on Hyperliquid perpetual futures and
    reports your

    positions, fills and balance. You never sign anything, manage nonces or look
    up asset

    indexes: send a market, a side and a value in US dollars.


    Every request authenticates with an API key created on the account page:

    `Authorization: Bearer tapi_…`.
servers:
  - url: https://tradingapi.dev
    description: Production. Orders trade real money on Hyperliquid mainnet.
security:
  - apiKey: []
tags:
  - name: Markets
    description: The markets you can trade, with their rules and current prices.
  - name: Orders
    description: Place, preview, list and look up orders.
  - name: Positions
    description: Your open positions, and closing them.
  - name: Account
    description: Your balance, the calling key, fills and withdrawals.
paths:
  /v1/orders:
    get:
      tags:
        - Orders
      summary: List orders
      description: Returns your orders, newest first, placed by any of your API keys.
      operationId: listOrders
      parameters:
        - name: market
          in: query
          required: false
          description: Only orders in this market.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Only orders with this status. Repeat the parameter to match several.
          schema:
            $ref: '#/components/schemas/OrderStatus'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: A page of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    OrderStatus:
      type: string
      enum:
        - pending
        - filled
        - canceled
        - rejected
      description: >
        `pending`: recorded, and possibly sent; the outcome is not known yet.

        `filled`: the whole size filled.

        `canceled`: filled partly or not at all; the rest found no price within
        the limit.

        `rejected`: refused; nothing filled.

        More statuses will be added. Treat a status you don't recognise as not
        finished.
    OrderList:
      type: object
      required:
        - object
        - data
        - next_cursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        next_cursor:
          type:
            - string
            - 'null'
    Order:
      type: object
      required:
        - object
        - id
        - client_order_id
        - market
        - side
        - type
        - status
        - status_reason
        - requested_value
        - requested_percent
        - reduce_only
        - size
        - price
        - price_limit
        - time_in_force
        - filled_size
        - average_fill_price
        - filled_value
        - fee
        - position_effect
        - summary
        - notes
        - metadata
        - created_at
        - updated_at
        - completed_at
      properties:
        object:
          type: string
          const: order
        id:
          type: string
          description: Our ID for the order.
        client_order_id:
          $ref: '#/components/schemas/ClientOrderId'
        market:
          type: string
        side:
          $ref: '#/components/schemas/Side'
        type:
          $ref: '#/components/schemas/OrderType'
        status:
          $ref: '#/components/schemas/OrderStatus'
        status_reason:
          $ref: '#/components/schemas/StatusReason'
        requested_value:
          type:
            - string
            - 'null'
          description: >-
            The `value` you sent. `null` for a close by percent or of the whole
            position.
        requested_percent:
          type:
            - string
            - 'null'
          description: The `percent` of a close. `null` otherwise.
        reduce_only:
          type: boolean
        size:
          type:
            - string
            - 'null'
          description: >-
            The size sent to the market, in the market's units. `null` until the
            order is sized.
        price:
          type:
            - string
            - 'null'
          description: Your limit price as used. `null` for market orders.
        price_limit:
          type:
            - string
            - 'null'
          description: >-
            The worst price the order could fill at. For market orders, 0.5%
            from the price when it was placed.
        time_in_force:
          type: string
          enum:
            - ioc
          description: Always `ioc` (immediate or cancel) for now.
        filled_size:
          $ref: '#/components/schemas/Decimal'
        average_fill_price:
          type:
            - string
            - 'null'
        filled_value:
          type:
            - string
            - 'null'
          description: The USD value that filled.
        fee:
          type:
            - string
            - 'null'
          description: >-
            Total fees paid, in USD, exact to 6 decimals. Can arrive shortly
            after the order finishes.
        position_effect:
          $ref: '#/components/schemas/PositionEffect'
        summary:
          type: string
          description: >-
            What happened, in plain English. For people and language models;
            branch on fields, not on this text.
        notes:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        metadata:
          $ref: '#/components/schemas/Metadata'
        timeline:
          type: array
          description: Present only with `expand[]=timeline`.
          items:
            $ref: '#/components/schemas/TimelineEntry'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the order reached a final status.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    ClientOrderId:
      type: string
      pattern: ^[A-Za-z0-9._:-]{1,64}$
      description: >-
        Your ID for the order, 1 to 64 characters of letters, digits, `.`, `_`,
        `:` and `-`. Unique per account, forever.
    Side:
      type: string
      enum:
        - buy
        - sell
    OrderType:
      type: string
      enum:
        - market
        - limit
      description: >
        `market` fills now at the best available prices, within 0.5% of the
        current price.

        `limit` fills now at your `price` or better; whatever cannot fill at
        once is canceled.
    StatusReason:
      type:
        - object
        - 'null'
      required:
        - code
        - message
      description: Why an order is `canceled` or `rejected`. `null` otherwise.
      properties:
        code:
          type: string
          enum:
            - no_liquidity_in_limit
            - ioc_remainder
            - insufficient_balance
            - order_below_minimum
            - order_above_maximum
            - reduce_only_would_increase
            - no_position
            - market_unavailable
            - deadline_passed
            - refused_by_safeguards
            - not_sent
            - rejected_by_market
            - awaiting_market
        message:
          type: string
          description: What happened, in a sentence, with the numbers involved.
    Decimal:
      type: string
      description: >-
        A decimal number as a string, for example `"250.00"`. Requests also
        accept a JSON number.
      pattern: ^-?[0-9]+(\.[0-9]+)?$
    PositionEffect:
      type:
        - string
        - 'null'
      enum:
        - open
        - increase
        - reduce
        - close
        - flip
        - null
      description: What the order did to your position. `null` when nothing filled.
    Note:
      type: object
      required:
        - code
        - message
      description: >
        Something worth knowing about a response that did not stop it.
        `available_low`,

        `partial_fill_likely` and `trading_approval_expiring` appear on previews
        only.
      properties:
        code:
          type: string
          enum:
            - size_rounded
            - price_rounded
            - position_flipped
            - position_closed
            - available_low
            - partial_fill_likely
            - trading_approval_expiring
        message:
          type: string
    Metadata:
      type: object
      description: >-
        Up to 20 keys of your own, returned with the order and never
        interpreted. Keys up to 40 characters of letters, digits, `_`, `.` and
        `-`; string values up to 500 characters.
      maxProperties: 20
      additionalProperties:
        type: string
        maxLength: 500
    TimelineEntry:
      type: object
      required:
        - at
        - event
        - message
      properties:
        at:
          $ref: '#/components/schemas/Timestamp'
        event:
          type: string
          enum:
            - received
            - admitted
            - leverage_set
            - sent
            - filled
            - partially_filled
            - canceled
            - rejected
            - fees_recorded
        message:
          type: string
    Timestamp:
      type: string
      format: date-time
      description: >-
        RFC 3339 in UTC with milliseconds, for example
        `2026-09-27T14:30:00.123Z`.
    Error:
      type: object
      required:
        - type
        - code
        - message
        - param
        - hint
        - details
        - errors
        - retryable
        - doc_url
      properties:
        type:
          type: string
          enum:
            - invalid_request
            - authentication
            - permission
            - not_found
            - conflict
            - unprocessable
            - rate_limited
            - unavailable
            - internal
          description: The kind of error. It determines the HTTP status.
        code:
          type: string
          description: >-
            A stable identifier for the error. Branch on this. New codes may be
            added.
        message:
          type: string
          description: What was wrong, with the values involved.
        param:
          type:
            - string
            - 'null'
          description: The request field at fault, as a JSON path, or `null`.
        hint:
          type:
            - string
            - 'null'
          description: One concrete way to fix the request.
        details:
          type: object
          description: The numbers and values the message refers to, as fields.
          additionalProperties: true
        errors:
          type: array
          description: Every field error, when `code` is `invalid_fields`. Empty otherwise.
          items:
            $ref: '#/components/schemas/Error'
        retryable:
          type: boolean
          description: Whether the same request can succeed later, unchanged.
        retry_after:
          $ref: '#/components/schemas/Timestamp'
          description: When a retry can succeed, if known.
        doc_url:
          type: string
          format: uri
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: How many items to return, from 1 to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: The `next_cursor` from the previous page.
      schema:
        type: string
    Expand:
      name: expand[]
      in: query
      required: false
      description: Extra detail to include. `timeline` adds the order's history.
      schema:
        type: string
        enum:
          - timeline
  responses:
    InvalidRequest:
      description: >-
        The request is malformed or breaks a rule. Nothing was recorded; fix it
        and send it again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_fields:
              summary: Several fields at once
              value:
                error:
                  type: invalid_request
                  code: invalid_fields
                  message: 3 fields are invalid.
                  param: null
                  hint: Fix each field listed in errors.
                  details: {}
                  errors:
                    - type: invalid_request
                      code: invalid_value
                      message: >-
                        side is "long". Orders use "buy" or "sell"; "long"
                        describes a position.
                      param: side
                      hint: 'To open a long, send "side": "buy".'
                      details: {}
                      errors: []
                      retryable: false
                      doc_url: >-
                        https://docs.tradingapi.dev/api-reference/errors#invalid_value
                    - type: invalid_request
                      code: unknown_field
                      message: amount is not a field of this request.
                      param: amount
                      hint: Did you mean value? It is the order's size in USD.
                      details: {}
                      errors: []
                      retryable: false
                      doc_url: >-
                        https://docs.tradingapi.dev/api-reference/errors#unknown_field
                    - type: invalid_request
                      code: missing_field
                      message: value is required.
                      param: value
                      hint: >-
                        Send how much to buy or sell in USD, for example
                        "value": "25.00".
                      details: {}
                      errors: []
                      retryable: false
                      doc_url: >-
                        https://docs.tradingapi.dev/api-reference/errors#missing_field
                  retryable: false
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#invalid_fields
            order_below_minimum:
              summary: Under the minimum after rounding
              value:
                error:
                  type: invalid_request
                  code: order_below_minimum
                  message: >-
                    A value of $10.00 buys 0.00011 BTC after rounding down to
                    BTC's 0.00001 size step, which is worth $9.29 at the price
                    limit of $84,430. The minimum is $10.00.
                  param: value
                  hint: Send a value of at least $10.14.
                  details:
                    value: '10.00'
                    value_after_rounding: '9.29'
                    min_value: '10.00'
                    smallest_passing_value: '10.14'
                  errors: []
                  retryable: false
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#order_below_minimum
    Unauthorized:
      description: No valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_api_key:
              value:
                error:
                  type: authentication
                  code: invalid_api_key
                  message: This API key is not valid. It may have been revoked.
                  param: null
                  hint: >-
                    Send a current key as Authorization: Bearer tapi_…. Keys are
                    created and revoked on the account page.
                  details: {}
                  errors: []
                  retryable: false
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#invalid_api_key
    RateLimited:
      description: >-
        The key made too many requests. Each key may make 10 requests at once,
        then 5 a second. Nothing was done; retry after `Retry-After` seconds.
      headers:
        Retry-After:
          description: The seconds to wait before retrying, always `1`.
          schema:
            type: string
            enum:
              - '1'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate_limited:
              value:
                error:
                  type: rate_limited
                  code: rate_limited
                  message: This key made too many requests; retry in 1 s.
                  param: null
                  hint: >-
                    Slow down: each key may make 10 requests at once, then 5 a
                    second.
                  details: {}
                  errors: []
                  retryable: true
                  retry_after: '2026-09-28T14:05:12.000Z'
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#rate_limited
    Unavailable:
      description: A service we depend on failed. Retry the same request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unavailable:
              value:
                error:
                  type: unavailable
                  code: unavailable
                  message: The exchange could not be reached.
                  param: null
                  hint: >-
                    Retry the same request with the same client_order_id; an
                    order may already have been recorded.
                  details: {}
                  errors: []
                  retryable: true
                  doc_url: https://docs.tradingapi.dev/api-reference/errors#unavailable
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: tapi_…
      description: >-
        An API key from the account page, sent as `Authorization: Bearer
        tapi_…`.

````