---
title: "List the merchant's transactions (newest first)"
method: GET
path: "/transactions/list"
tags: ["Transactions"]
---

# List the merchant's transactions (newest first)

`GET /transactions/list`

## Request

- Base URL: `https://api.griffnode.com/v1`
- URL: `https://api.griffnode.com/v1/transactions/list`
- Auth: HTTP bearer

## Query parameters

- `limit` integer
- `offset` integer
- `status` 'pending' | 'awaiting_confirmation' | 'completed' | 'partial' | 'expired' | 'failed': Public transaction status (internal sub-states are mapped to these).
- `crypto` 'BTC' | 'LTC' | 'DOGE' | 'DASH' | 'ETH' | 'USDT' | 'USDC' | 'EURC' | 'DAI' | 'WBTC' | 'SHIB' | 'PEPE' | 'LINK' | 'UNI' | 'AAVE' | 'MKR': Supported coin/token symbol. /cryptos/list is authoritative at runtime.

## Response `200`

A page of transactions.

- object
  - `success` unknown, required
  - `data` object, required
    - `transactions` Transaction[], required
      - `transaction_id` string, required
      - `status` 'pending' | 'awaiting_confirmation' | 'completed' | 'partial' | 'expired' | 'failed', required: Public transaction status (internal sub-states are mapped to these).
      - `exception` 'paid_late' | 'needs_review': Present only when the payment waits for the merchant's decision. paid_late: coins arrived within 6h after the window closed (status stays expired; complete it with Mark as paid in the dashboard, which also sends payment.completed). needs_review: ETH/ERC-20 deposit address balance dropped while open, payment unknown (status pending).
      - `type` 'basic' | 'detailed'
      - `crypto` 'BTC' | 'LTC' | 'DOGE' | 'DASH' | 'ETH' | 'USDT' | 'USDC' | 'EURC' | 'DAI' | 'WBTC' | 'SHIB' | 'PEPE' | 'LINK' | 'UNI' | 'AAVE' | 'MKR', required: Supported coin/token symbol. /cryptos/list is authoritative at runtime.
      - `deposit_address` string
      - `amount_crypto` number
      - `amount_fiat` number, required
      - `amount_usd` number, required
      - `amount_paid` number
      - `amount_remaining` number
      - `currency_fiat` 'USD' | 'PLN' | 'EUR' | 'GBP', required
      - `fiat_to_usd_rate` number
      - `exchange_rate` number: USD per unit of crypto, locked at creation.
      - `confirmations_required` integer
      - `payment_url` string, uri
      - `order_id` string, nullable
      - `customer_email` string, nullable
      - `items` LineItem[], nullable
        - `name` string, required
        - `quantity` integer
        - `price` number, required
      - `payments` PaymentSplit[]: On-chain payments detected toward this transaction.
        - `txid` string: On-chain transaction hash (blockchain id, NOT the GriffNode transaction_id).
        - `amount_crypto` number
        - `confirmations` integer
        - `status` string
        - `detected_at` string, date-time
        - `confirmed_at` string, date-time, nullable
      - `metadata` Metadata, nullable: Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total).
      - `success_url` string, nullable
      - `cancel_url` string, nullable
      - `created_at` string, date-time, required
      - `updated_at` string, date-time
      - `expires_at` string, date-time, required
    - `pagination` Pagination, required
      - `limit` integer, required
      - `offset` integer, required
      - `total` integer, required

## Other responses

- `401`: Missing or invalid API key (UNAUTHORIZED).
- `403`: Key lacks permission — e.g. a publishable key on a secret-only endpoint, or plan too low (FORBIDDEN, USE_PAY_ENDPOINT, PLAN_UPGRADE_REQUIRED, NO_ACTIVE_PLAN).

---

[API](https://skmtc.dev/griffnode/apis/griffnode-api.md) · [All operations](https://skmtc.dev/griffnode/apis/griffnode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/griffnode/apis/griffnode-api/revisions/1fed3c10d31b?raw)