History API

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.

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.

Authentication

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

Authorization: Bearer your-api-key-here

Unauthorized requests (missing or invalid API key) will return a 401 Unauthorized response.

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.

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`. For `resource=account`, a page must start within the first 1000 records — see Paging through account history
`pageSize`	number	No	Number of items per page. Default: `10`. Maximum: `200`
`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`
`status`	string	No	Card status filter, for `cards-summary` only. One of `all`, `active`, `inactive`, `locked`, `canceled`. If you omit it, you get only the cards still visible to the cardholder — canceled ones are left out. Use `all` for every card regardless of status

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.

string

Status message (if present)

array

Array of account history entries. Each entry typically includes:

string

Entry ID

string

Date and time of the transaction (ISO 8601)

string

Raw transaction type: buy (deposit), sell (withdrawal), swap-bridge (convert), transfer-token (send)

string

Human-readable description of the transaction. If a note was added to the transaction afterwards, it is appended after -, the same way the statement export shows it. The note alone is also in additionalDescription.

string

Current status of the transaction

string

Amount involved in the operation

string

Asset sent (if applicable)

string

Amount sent (if applicable)

string

Asset received (if applicable)

string

Amount received (if applicable)

string

Running balance after this transaction. A swap started on or after 2026-09-09 is a single entry carrying the whole swap’s net change and the balance once it completed; swaps started earlier appear as two entries (the outgoing and the incoming leg).

string

When the transaction settled (ISO 8601). This is the statement export’s “Executed At” and can be later than the creation date: a payment created on one day and settled on another carries the settlement day here. Use it, not the creation date, to decide which day a transaction belongs to.

string

For deposits and withdrawals, when the fiat side was processed (ISO 8601, nullable). It can differ from executedAt by minutes or more.

string

Purpose of the transaction, such as PAYROLL_AND_TEAM_EXPENSES. Empty when none was given.

string

Memo entered when the transaction was created (nullable)

string

Note added to the transaction afterwards (nullable). Also appended to description.

object

Pagination information:

boolean

Whether there is another page of results

number

Current page index (starting from 0)

number

Number of items per page

number

Total number of pages available

number

Total number of records matching the query. Exact whenever totalCountIsEstimate is false

boolean

Whether totalCount is an upper-bound estimate rather than an exact count. See Paging through account history

Example Request (Account History)

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)

{
  "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.

array

Array of items with transaction and card information:

object

Card transaction details (amount, merchant, status, currency, etc.)

object

Card metadata:

string

Cardholder name

string

Card nickname

string

Last four digits of the card

object

Pagination information:

boolean

number

Example Request (Cards Transactions)

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)

{
  "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.

array

Array of card snapshots with fields such as:

string

Card ID

string

Card nickname

string

Last four digits of the card

string

Card status

number

Spending limit associated with the card

string

Interval for the spending limit (e.g., monthly)

object

Same structure as other paginated responses.

Example Request (Cards Summary)

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"

By default the snapshot covers only the cards still visible to the cardholder — the active, inactive and locked ones. Add status=all for every card the account has ever had, or status=canceled for the canceled ones alone.

curl -X GET "https://history-api.lootrush.com/api/history?resource=cards&feature=cards-summary&currentPage=0&pageSize=100&status=all" \
  -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.

array

Array of balance movement records:

number

Amount of the movement

number

Balance after the movement

number

Balance before the movement

string

Description of the movement

string

Timestamp of the movement (ISO 8601)

string

Movement type

object

Same structure as other paginated responses.

Error Responses

string

Error message describing what went wrong

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.

Each user can perform up to 2 requests every 2 seconds. Exceeding this limit will result in a 429 Rate limit exceeded error.

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

Paging through account history

resource=account combines settled on-chain operations with trades still pending. The two are paginated separately and merged per request, which puts two limits on how you read the endpoint. A page must start within the first 1000 records — currentPage * pageSize must be below 1000. A deeper page returns 400 rather than a partial result:

{
  "error": "This endpoint can page through at most 1000 records per query. Narrow the range with startDate/endDate and page within it."
}

To read a longer history, split it into date ranges with startDate/endDate and page within each range. Check totalCountIsEstimate before reconciling counts. For result sets small enough to be counted in one pass, totalCount is exact and stable and totalCountIsEstimate is false. For larger ones it’s an upper bound that may shift slightly between calls.

Only reconcile record counts against a totalCount reported with totalCountIsEstimate: false. Narrowing the query with startDate/endDate is the reliable way to get one.

Iterate with hasNextPage. It never points at a page the API would reject, so following it won’t walk you into a 400. When it turns false, either the history ended or you reached the 1000-record limit. To tell the two apart, compare what you read against totalCount: if totalCount is higher, you stopped at the limit and there’s more history behind a narrower startDate/endDate.

Best Practices

Use pagination: Always provide currentPage and pageSize to avoid fetching excessively large responses.
Filter by date: Use startDate, endDate, and asOf to restrict the time window of data as much as possible. For account history this is also how you read past the 1000-record paging limit.
Iterate with hasNextPage: Stop when it turns false rather than computing a page count from totalCount, which may be an estimate. Then compare what you read against totalCount to check whether you reached the end of the history or the 1000-record paging limit.
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.
Leverage text search: For card transactions, use filterByText to search by merchant or description instead of post-processing large datasets.
Handle rate limits: Implement exponential backoff and respect 429 responses to keep your integration stable.

Support

Happy to help if you get stuck:

Email: [email protected]
Dashboard: LootRush Dashboard

Getting started

API guides

MCP Server

Overview

Authentication

Get User History

Query Parameters

Resource and Feature Combinations

Account resource

Cards resource

Responses

Account History Response (`resource=account`)

Example Request (Account History)

Example Response (simplified)

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

Example Request (Cards Transactions)

Example Response (simplified)

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

Example Request (Cards Summary)

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

Error Responses

Rate Limits

Paging through account history

Best Practices

Support

​Overview

​Authentication

​Get User History

​Query Parameters

​Resource and Feature Combinations

​Account resource

​Cards resource

​Responses

​Account History Response (resource=account)

​Example Request (Account History)

​Example Response (simplified)

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

​Example Request (Cards Transactions)

​Example Response (simplified)

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

​Example Request (Cards Summary)

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

​Error Responses

​Rate Limits

​Paging through account history

​Best Practices

​Support

Overview

Authentication

Get User History

Query Parameters

Resource and Feature Combinations

Account resource

Cards resource

Responses

Account History Response (`resource=account`)

Example Request (Account History)

Example Response (simplified)

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

Example Request (Cards Transactions)

Example Response (simplified)

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

Example Request (Cards Summary)

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

Error Responses

Rate Limits

Paging through account history

Best Practices

Support