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

# Merchant Ledger

> Retrieve the complete financial history for a specific merchant, including atomic balance snapshots for every transaction.

### Headers

<ParamField header="x-api-key" type="string" required>
  Your test or live SDK Secret Key (`sk_test_...` or `sk_live_...`).
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier for the merchant (e.g., `mch_xyz789`).
</ParamField>

### Query Parameters

<ParamField query="limit" type="number">
  Number of transaction records to return (default `50`, max `100`).
</ParamField>

### Response Fields

<ResponseField name="merchant_id" type="string">
  Unique merchant identifier.
</ResponseField>

<ResponseField name="merchant_name" type="string">
  Merchant display name.
</ResponseField>

<ResponseField name="total_count" type="number">
  Total number of transaction records found.
</ResponseField>

<ResponseField name="transactions" type="array">
  <Expandable title="Transaction Item">
    <ResponseField name="id" type="string">
      Unique transaction log ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of ledger entry (e.g., `PAYMENT`, `DEPOSIT`, `WITHDRAWAL`).
    </ResponseField>

    <ResponseField name="amount" type="string">
      Transaction amount in USDC.
    </ResponseField>

    <ResponseField name="balance_before" type="string">
      Merchant USDC balance before this transaction.
    </ResponseField>

    <ResponseField name="balance_after" type="string">
      Merchant USDC balance after this transaction.
    </ResponseField>

    <ResponseField name="payment_id" type="string">
      Associated payment ID.
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of transaction (`COMPLETED`, `PENDING`, `FAILED`).
    </ResponseField>

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

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Example

```json theme={null}
{
  "merchant_id": "mch_xyz789",
  "merchant_name": "Urban Eats",
  "total_count": 1,
  "transactions": [
    {
      "id": "tx_abc123",
      "type": "PAYMENT",
      "amount": "5.00",
      "balance_before": "100.00",
      "balance_after": "105.00",
      "payment_id": "pay_987654",
      "status": "COMPLETED",
      "description": "NFC Payment Received",
      "created_at": "2026-04-03T12:00:00Z"
    }
  ]
}
```