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

# Get Lighter trades JSON Schema

> Get Lighter trades JSON Schema contract. Includes route metadata, request parameters, response statuses, examples, and JSON fields for implementation.

Source OpenAPI: 0xArchive API 1.8.0; 227 paths; 217 component schemas.

Get historical trades (fills) for a coin within a time range. Served fill history begins January 17, 2025; exact starts vary by market. **Pagination:** Use the `cursor` parameter with the value from the previous response's `next_cursor` for efficient pagination.

## Route Metadata

| Field | Value |
| - | - |
| Method | `GET` |
| Path | `/v1/lighter/trades/{symbol}` |
| operationId | `getLighterTrades` |
| Tag | Lighter - Trades |
| Family | Lighter |
| Deprecated or legacy | no |

## Human endpoint reference

Open [`GET /v1/lighter/trades/{symbol}`](/api-reference/lighter--trades/get-lighter-trades) for authentication, parameters, responses, and examples.

## Request Parameters

### Path Parameters

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getLighterTrades path parameters",
  "type": "object",
  "required": [
    "symbol"
  ],
  "properties": {
    "symbol": {
      "description": "Trading pair symbol (e.g., ETH, BTC)",
      "type": "string",
      "example": "ETH",
      "x-parameter-location": "path"
    }
  }
}
```

### Query Parameters

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getLighterTrades query parameters",
  "type": "object",
  "properties": {
    "start": {
      "description": "Start timestamp in Unix milliseconds. Defaults to 24h ago.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "end": {
      "description": "End timestamp in Unix milliseconds. Defaults to now.",
      "type": "integer",
      "format": "int64",
      "x-parameter-location": "query"
    },
    "cursor": {
      "description": "Cursor for pagination",
      "type": "string",
      "x-parameter-location": "query"
    },
    "limit": {
      "description": "Maximum number of results (default: 100, max: 1000)",
      "type": "integer",
      "default": 100,
      "maximum": 1000,
      "x-parameter-location": "query"
    }
  }
}
```

## Response Contracts

### Status 200

List of trades with cursor for next page

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getLighterTrades response 200",
  "description": "API response containing an array of Lighter trades. History responses serve canonical rows only and clamp `end` to `finalized_through`; `/recent` responses serve preliminary rows and report `preliminary_row_count`.",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "description": "Lighter trade (fill) record. Canonical rows (`source: \"bucket\"`) come from the daily reconcile of the deployment's published trade history (the Lighter Foundation export for Lighter mainnet, the venue trade export for Lighter on Robinhood Chain) and carry full enrichment. The `/recent` endpoint serves preliminary real-time rows (`source: \"ws\"`) without fee/tx_hash/order_id/realized_pnl and the other bucket-only enrichment fields until the daily reconcile finalizes them.",
        "type": "object",
        "required": [
          "coin",
          "crossed",
          "price",
          "side",
          "size",
          "source",
          "symbol",
          "timestamp",
          "trade_id"
        ],
        "properties": {
          "account_index": {
            "description": "Lighter numeric account index this row belongs to (serialized as a string)",
            "type": "string",
            "example": "513030"
          },
          "allocated_margin_after": {
            "description": "Isolated-margin allocation after the fill (0 for cross)",
            "type": "number",
            "nullable": true,
            "example": 0
          },
          "allocated_margin_before": {
            "description": "Isolated-margin allocation before the fill (0 for cross)",
            "type": "number",
            "nullable": true,
            "example": 0
          },
          "client_id": {
            "description": "Client-assigned order ID. Canonical rows only.",
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "example": 46758119273906
          },
          "coin": {
            "description": "Trading pair symbol (deprecated, use symbol instead)",
            "type": "string",
            "deprecated": true,
            "example": "BTC"
          },
          "counterparty_address": {
            "description": "Counterparty's Lighter account index (serialized as a string). Canonical rows only.",
            "type": "string",
            "nullable": true,
            "example": "710765"
          },
          "crossed": {
            "description": "True if this account was the taker (crossed the spread), false if maker",
            "type": "boolean",
            "example": false
          },
          "entry_quote_before": {
            "description": "This account's position entry quote value before the fill",
            "type": "number",
            "nullable": true,
            "example": 61179.114686
          },
          "fee": {
            "description": "This account's fee for the fill. Canonical rows only.",
            "type": "string",
            "nullable": true,
            "example": "0.000028"
          },
          "fee_account_id": {
            "description": "Account credited with the fee. Canonical rows only.",
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "example": 0
          },
          "initial_margin_fraction_before": {
            "description": "This account's initial margin fraction before the fill",
            "type": "number",
            "nullable": true,
            "example": 0.02
          },
          "integrator_fee": {
            "description": "Integrator fee charged on the fill. Canonical rows only.",
            "type": "number",
            "nullable": true,
            "example": 0
          },
          "is_maker": {
            "description": "True if this account was the maker. Canonical rows only.",
            "type": "boolean",
            "nullable": true,
            "example": true
          },
          "l2_block_height": {
            "description": "Lighter L2 block height containing the trade. Canonical rows only.",
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "example": 300075269
          },
          "order_id": {
            "description": "Order ID of this account's order. Canonical rows only.",
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "example": 844421856609148
          },
          "position_sign_changed": {
            "description": "True if the fill flipped this account's position between long and short",
            "type": "boolean",
            "nullable": true,
            "example": false
          },
          "position_size_after": {
            "description": "Signed position size after the fill (derived: position_size_before plus/minus size by side)",
            "type": "number",
            "nullable": true,
            "example": -0.94627
          },
          "position_size_before": {
            "description": "This account's signed position size before the fill (long positive, short negative)",
            "type": "number",
            "nullable": true,
            "example": -0.94632
          },
          "price": {
            "description": "Execution price",
            "type": "string",
            "example": "64708.5"
          },
          "realized_pnl": {
            "description": "Matching-engine realized PnL for this fill. Canonical rows only.",
            "type": "number",
            "nullable": true,
            "example": -0.00295
          },
          "side": {
            "description": "Trade side of the account this row belongs to: 'B' (buy) or 'A' (sell/ask)",
            "type": "string",
            "enum": [
              "A",
              "B"
            ],
            "example": "B"
          },
          "size": {
            "description": "Trade size in base units",
            "type": "string",
            "example": "0.00005"
          },
          "source": {
            "description": "Row provenance: 'bucket' = canonical (finalized by the daily reconcile of the deployment's published trade history), 'ws' = preliminary real-time capture",
            "type": "string",
            "enum": [
              "bucket",
              "ws"
            ],
            "example": "bucket"
          },
          "symbol": {
            "description": "Trading pair symbol",
            "type": "string",
            "example": "BTC"
          },
          "timestamp": {
            "description": "Execution timestamp (UTC)",
            "type": "string",
            "format": "date-time",
            "example": "2026-07-26T14:47:59.174Z"
          },
          "trade_id": {
            "description": "Unique Lighter trade ID. Each trade produces two rows (one per counterparty) sharing this ID.",
            "type": "integer",
            "format": "int64",
            "example": 26121110211
          },
          "trade_type": {
            "description": "Upstream trade type. Canonical rows only.",
            "type": "string",
            "nullable": true,
            "example": "trade"
          },
          "transaction_time_us": {
            "description": "Intra-block transaction time in microseconds. Canonical rows only.",
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "example": 1785077279174437
          },
          "tx_hash": {
            "description": "Lighter settlement transaction hash (fixed-width hex). Canonical rows only.",
            "type": "string",
            "nullable": true,
            "example": "000000197b6fd6e90000019f9ee5a9c6000000000000000000000000000000000000000000000000"
          },
          "usdc_amount": {
            "description": "Notional value of the fill in USDC. Canonical rows only.",
            "type": "number",
            "nullable": true,
            "example": 3.235425
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "clamped_to": {
          "description": "Effective end after clamping to `finalized_through`. History endpoint only.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        },
        "count": {
          "description": "Number of records returned",
          "type": "integer"
        },
        "finalized_through": {
          "description": "Timestamp through which canonical (bucket-reconciled) data is available.",
          "type": "string",
          "format": "date-time"
        },
        "next_cursor": {
          "description": "Cursor for pagination. Use this value as the `cursor` parameter to fetch the next page. History endpoint only.",
          "type": "string",
          "nullable": true
        },
        "preliminary_row_count": {
          "description": "Number of preliminary (`source: \"ws\"`) rows in this response. `/recent` endpoint only.",
          "type": "integer",
          "nullable": true
        },
        "request_id": {
          "description": "Unique request ID for support",
          "type": "string",
          "format": "uuid"
        },
        "requested_end": {
          "description": "The `end` the caller requested, echoed when it was clamped. History endpoint only.",
          "type": "string",
          "format": "date-time",
          "nullable": true
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": true
    }
  }
}
```

### Status 400

Invalid request

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getLighterTrades response 400",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 400,
  "error": "Failed to deserialize query string: limit: invalid digit found in string",
  "error_code": "invalid_query_params",
  "param": "limit",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
  "success": false
}
```

### Status 401

Authentication required

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getLighterTrades response 401",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 401,
  "error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
  "error_code": "unauthorized",
  "request_id": "71ed4b6f-63ef-4ae1-a123-07ffa47c1c14",
  "success": false
}
```

### Status 429

Rate limit exceeded

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "getLighterTrades response 429",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "param": {
      "description": "The parameter at fault, when the error is about one parameter.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    },
    "success": {
      "description": "Always false on an error.",
      "type": "boolean",
      "example": false
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 429,
  "error": "Rate limit exceeded"
}
```


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