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

# History API

> API endpoints for querying user transaction and activity history

## Overview

The History API allows third-party partners to query the transaction and activity history of the authenticated user.
It supports both **cards** and **account** resources, with multiple features for summaries, transactions, balances, and filtered account activity.

<Info>
  All endpoints require authentication via the `Authorization: Bearer <api_key>` header.
  The user is inferred from the API key; you do **not** pass a `userId` in the URL.
</Info>

## Authentication

All requests must include an API key in the Authorization header:

```bash theme={null}
Authorization: Bearer your-api-key-here
```

<Warning>
  Unauthorized requests (missing or invalid API key) will return a `401
      Unauthorized` response.
</Warning>

***

## Get User History

Retrieves the transaction and activity history for the authenticated user.
You can query either **cards** or **account** data, and choose which feature you want via query parameters.

<Endpoint>
  <Method>GET</Method>
  <Path>/api/history</Path>
</Endpoint>

### Query Parameters

| Parameter      | Type   | Required | Description                                                                            |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `resource`     | string | Yes      | Resource type to query. Must be one of: `cards`, `account`                             |
| `feature`      | string | Yes      | Feature to retrieve (varies by resource, see tables below)                             |
| `currentPage`  | number | No       | Current page number for pagination. Default: `0`                                       |
| `pageSize`     | number | No       | Number of items per page. Default: `10`. Maximum: `100`                                |
| `startDate`    | string | No       | Start date for filtering history (ISO 8601 format, e.g. `2024-01-01T00:00:00Z`)        |
| `endDate`      | string | No       | End date for filtering history (ISO 8601 format)                                       |
| `filterByText` | string | No       | Text filter for searching card transactions (e.g. merchant name, description)          |
| `asOf`         | string | No       | Snapshot date for certain features (ISO 8601 format). Used mainly with `cards-summary` |

### Resource and Feature Combinations

#### Account resource

When `resource=account`, the following `feature` values are supported:

| Feature              | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `account`            | Full activity (all supported transaction types)       |
| `account-onramp`     | Deposits — adding funds (on-ramp)                     |
| `account-offramp`    | Withdrawals — cashing out (off-ramp)                  |
| `account-swap`       | Converts — token swaps and bridges                    |
| `account-crypto`     | Crypto transfers — sends and receives                 |
| `account-portifolio` | Portfolio activity — transfers, converts, and bridges |

These features all return the same **Activity** shape, but filtered by transaction type internally.

#### Cards resource

When `resource=cards`, the following `feature` values are supported:

| Feature              | Description                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `cards-transactions` | Paginated list of card transactions, including card metadata (last four digits, nickname, etc.) |
| `cards-summary`      | Snapshot of the user's cards (status, spending limits, etc.) at a point in time (`asOf`)        |
| `cards-balance`      | History of collateral movements and running card balance                                        |

***

## Responses

The response shape depends on the combination of `resource` and `feature`.
Below are the main structures you will encounter.

### Account History Response (`resource=account`)

For `resource=account`, you receive a list of account history entries and pagination info.

<ResponseField name="message" type="string">
  Status message (if present)
</ResponseField>

<ResponseField name="nodes" type="array">
  Array of account history entries. Each entry typically includes:

  <ResponseField name="id" type="string">
    Entry ID
  </ResponseField>

  <ResponseField name="transactionDate" type="string">
    Date and time of the transaction (ISO 8601)
  </ResponseField>

  <ResponseField name="transactionType" type="string">
    Raw transaction type: `buy` (deposit), `sell` (withdrawal), `swap-bridge` (convert), `transfer-token` (send)
  </ResponseField>

  <ResponseField name="description" type="string">
    Human-readable description of the transaction
  </ResponseField>

  <ResponseField name="status" type="string">
    Current status of the transaction
  </ResponseField>

  <ResponseField name="amount" type="string">
    Amount involved in the operation
  </ResponseField>

  <ResponseField name="assetSent" type="string">
    Asset sent (if applicable)
  </ResponseField>

  <ResponseField name="amountSent" type="string">
    Amount sent (if applicable)
  </ResponseField>

  <ResponseField name="assetReceived" type="string">
    Asset received (if applicable)
  </ResponseField>

  <ResponseField name="amountReceived" type="string">
    Amount received (if applicable)
  </ResponseField>

  <ResponseField name="runningBalance" type="string">
    Running balance after this transaction
  </ResponseField>

  <ResponseField name="executedAt" type="string">
    Execution timestamp (ISO 8601, nullable)
  </ResponseField>

  <ResponseField name="transactionPurpose" type="string">
    Purpose of the transaction
  </ResponseField>

  <ResponseField name="userDescription" type="string">
    Optional user-provided description
  </ResponseField>
</ResponseField>

<ResponseField name="pageInfo" type="object">
  Pagination information:

  <ResponseField name="hasNextPage" type="boolean">
    Whether there is another page of results
  </ResponseField>

  <ResponseField name="currentPage" type="number">
    Current page index (starting from 0)
  </ResponseField>

  <ResponseField name="pageSize" type="number">
    Number of items per page
  </ResponseField>

  <ResponseField name="numberOfPages" type="number">
    Total number of pages available
  </ResponseField>

  <ResponseField name="totalCount" type="number">
    Total number of records matching the query
  </ResponseField>
</ResponseField>

#### Example Request (Account History)

```bash theme={null}
curl -X GET "https://history-api.lootrush.com/api/history?resource=account&feature=account&currentPage=0&pageSize=10" \
  -H "Authorization: Bearer your-api-key-here"
```

#### Example Response (simplified)

```json theme={null}
{
  "nodes": [
    {
      "id": "hist-123",
      "transactionDate": "2024-01-15T10:30:00Z",
      "transactionType": "buy",
      "description": "Deposit via credit card",
      "status": "completed",
      "assetSent": "USD",
      "amountSent": "100.00",
      "assetReceived": "USDC",
      "amountReceived": "99.50",
      "amount": "99.50",
      "runningBalance": "250.00",
      "executedAt": "2024-01-15T10:30:10Z",
      "transactionPurpose": "onramp",
      "userDescription": null
    }
  ],
  "pageInfo": {
    "hasNextPage": false,
    "currentPage": 0,
    "pageSize": 10,
    "numberOfPages": 1,
    "totalCount": 1
  }
}
```

### Cards Transactions Response (`resource=cards`, `feature=cards-transactions`)

For `cards-transactions`, you receive card transactions enriched with card metadata.

<ResponseField name="userCardTransactions" type="array">
  Array of items with transaction and card information:

  <ResponseField name="transaction" type="object">
    Card transaction details (amount, merchant, status, currency, etc.)
  </ResponseField>

  <ResponseField name="card" type="object">
    Card metadata:

    <ResponseField name="name" type="string">
      Cardholder name
    </ResponseField>

    <ResponseField name="nickname" type="string">
      Card nickname
    </ResponseField>

    <ResponseField name="lastFourDigits" type="string">
      Last four digits of the card
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information:

  <ResponseField name="hasNextPage" type="boolean" />

  <ResponseField name="currentPage" type="number" />

  <ResponseField name="pageSize" type="number" />

  <ResponseField name="numberOfPages" type="number" />

  <ResponseField name="totalCount" type="number" />
</ResponseField>

#### Example Request (Cards Transactions)

```bash theme={null}
curl -X GET "https://history-api.lootrush.com/api/history?resource=cards&feature=cards-transactions&currentPage=0&pageSize=10&filterByText=Amazon" \
  -H "Authorization: Bearer your-api-key-here"
```

#### Example Response (simplified)

```json theme={null}
{
  "userCardTransactions": [
    {
      "transaction": {
        "id": "txn-123",
        "amount": 42.5,
        "merchantName": "Amazon",
        "createdAt": "2024-01-15T10:30:00Z",
        "type": "purchase",
        "status": "completed",
        "currency": "USD"
      },
      "card": {
        "name": "Alice Doe",
        "nickname": "Main Card",
        "lastFourDigits": "4242"
      }
    }
  ],
  "pagination": {
    "hasNextPage": false,
    "currentPage": 0,
    "pageSize": 10,
    "numberOfPages": 1,
    "totalCount": 1
  }
}
```

### Cards Summary Response (`resource=cards`, `feature=cards-summary`)

For `cards-summary`, you receive a snapshot of the user's cards and related limits.

<ResponseField name="userCardsSnapshot" type="array">
  Array of card snapshots with fields such as:

  <ResponseField name="id" type="string">
    Card ID
  </ResponseField>

  <ResponseField name="nickname" type="string">
    Card nickname
  </ResponseField>

  <ResponseField name="lastFourDigits" type="string">
    Last four digits of the card
  </ResponseField>

  <ResponseField name="status" type="string">
    Card status
  </ResponseField>

  <ResponseField name="spendingLimit" type="number">
    Spending limit associated with the card
  </ResponseField>

  <ResponseField name="spendingInterval" type="string">
    Interval for the spending limit (e.g., monthly)
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Same structure as other paginated responses.
</ResponseField>

#### Example Request (Cards Summary)

```bash theme={null}
curl -X GET "https://history-api.lootrush.com/api/history?resource=cards&feature=cards-summary&currentPage=0&pageSize=10&asOf=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer your-api-key-here"
```

### Cards Balance Response (`resource=cards`, `feature=cards-balance`)

For `cards-balance`, you receive card collateral movements and running balance over time.

<ResponseField name="cardIssuerUserCollateralMovement" type="array">
  Array of balance movement records:

  <ResponseField name="amount" type="number">
    Amount of the movement
  </ResponseField>

  <ResponseField name="runningBalance" type="number">
    Balance after the movement
  </ResponseField>

  <ResponseField name="previousBalance" type="number">
    Balance before the movement
  </ResponseField>

  <ResponseField name="description" type="string">
    Description of the movement
  </ResponseField>

  <ResponseField name="createdAt" type="string">
    Timestamp of the movement (ISO 8601)
  </ResponseField>

  <ResponseField name="type" type="string">
    Movement type
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Same structure as other paginated responses.
</ResponseField>

***

## Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

| Status Code | Error Message                         | Description                                                              |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------ |
| `400`       | `Invalid feature` or validation error | The combination of `resource`/`feature` or other query params is invalid |
| `401`       | `Unauthorized: API key is required`   | The `Authorization` header is missing or not in the expected format      |
| `401`       | `Unauthorized: Invalid API key`       | The provided API key is invalid                                          |
| `429`       | `Rate limit exceeded`                 | Too many requests for the same user in a short period                    |
| `500`       | `API key validation failed: ...`      | Internal error while validating the API key                              |

***

## Rate Limits

The History API is rate-limited per user to protect the service and ensure fair usage.

<Warning>
  Each user can perform up to **2 requests every 2 seconds**. Exceeding this
  limit will result in a `429 Rate limit exceeded` error.
</Warning>

When you receive `429` responses, implement retry logic with exponential backoff to avoid hammering the API.

***

## Best Practices

1. **Use pagination**: Always provide `currentPage` and `pageSize` to avoid fetching excessively large responses.
2. **Filter by date**: Use `startDate`, `endDate`, and `asOf` to restrict the time window of data as much as possible.
3. **Choose the right feature**: Use `account-onramp`, `account-offramp`, `account-swap`, `account-crypto`, or `account-portifolio` to narrow the type of account history you need.
4. **Leverage text search**: For card transactions, use `filterByText` to search by merchant or description instead of post-processing large datasets.
5. **Handle rate limits**: Implement exponential backoff and respect `429` responses to keep your integration stable.

***

## Support

For API support, please contact:

* Email: [support@lootrush.com](mailto:support@lootrush.com)
* Dashboard: [LootRush Dashboard](https://www.lootrush.com/tokens/s/dashboard)