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

# List Trades

> Lists trades for the authenticated partner, with optional filters.

## Overview

Lists trade rows for the authenticated partner. All filters are optional; omit them to list everything. Results are ordered by `created_at` descending.

Only trades that the indexer has written are returned. Trades that have just been submitted but not yet confirmed on-chain do not appear until the indexer processes them.

## Headers

<ParamField header="x-api-key" type="string" required>
  A valid `PARTNER` scope key.
</ParamField>

## Query Parameters

<ParamField query="grail_user_id" type="string">
  Filter to a single user. If the user doesn't exist, returns an empty list (not a 404).
</ParamField>

<ParamField query="side" type="string">
  Filter by side: `"buy"` or `"sell"`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `"confirmed"` or `"failed"`.
</ParamField>

## Response

<ResponseField name="trades" type="array">
  Array of trade objects — same shape as [Get Trade](/api-reference/trades/get-trade).
</ResponseField>

## Errors

| HTTP | `error`        | When                           |
| ---- | -------------- | ------------------------------ |
| 401  | `unauthorized` | Missing or invalid `x-api-key` |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://grail-stack-dev.onrender.com/v1/trades?side=buy&status=confirmed" \
    -H "x-api-key: grail_partner_<hex>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "trades": [
      {
        "trade_id": "trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9",
        "side": "buy",
        "status": "confirmed",
        "usdc_amount": 100,
        "gold_amount": 0.020528,
        "price_per_troy_oz": 4872.84,
        "fee_bps": 50,
        "fee_usd": 0.50,
        "submitted_tx_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp...base58",
        "created_at": "2026-04-17T10:18:30.000Z",
        "updated_at": "2026-04-17T10:18:30.000Z"
      }
    ]
  }
  ```
</ResponseExample>