--- title: "List transactions" method: GET path: "/transactions" tags: ["Transactions"] --- # List transactions `GET /transactions` Retrieve a paginated list of transactions with optional filtering. The transactions can be filtered by customer ID, platform customer ID, UMA address, date range, status, and transaction type. ## Query parameters - `customerId` string - `platformCustomerId` string - `accountIdentifier` string - `senderAccountIdentifier` string - `receiverAccountIdentifier` string - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED' — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired | - `type` 'INCOMING' | 'OUTGOING' — Type of transaction (incoming payment or outgoing payment) - `reference` string - `startDate` string, date-time - `endDate` string, date-time - `limit` integer - `cursor` string - `sortOrder` 'asc' | 'desc' ## Response `200` Successful operation - TransactionListResponse - `data` TransactionOneOf[], required — List of transactions matching the criteria - union - IncomingTransaction - `id` string, required — Unique identifier for the transaction - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired | - `type` 'INCOMING', required — Type of transaction (incoming payment or outgoing payment) - `destination` union, required - AccountTransactionDestination — Destination account details - `destinationType` 'ACCOUNT', required - `accountId` string, required — Destination account identifier - UmaAddressTransactionDestination — UMA address destination details - `destinationType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the recipient - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming) - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming) - `settledAt` string, date-time — When the payment was or will be settled - `createdAt` string, date-time — When the transaction was created - `updatedAt` string, date-time — When the transaction was last updated - `agentId` string — If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions. - `description` string — Optional memo or description for the payment - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform. - `source` union - AccountTransactionSource — Source account details - `sourceType` 'ACCOUNT', required - `accountId` string, required — Source account identifier - UmaAddressTransactionSource — UMA address source details - `sourceType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the sender - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — The customer on whose behalf the transaction was initiated. - `currency` string, required — Currency code for the funding source - `receivedAmount` CurrencyAmount, required - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `fees` integer — The total fees available from the receive quote in the smallest unit of the receiving currency (eg. cents). - `reconciliationInstructions` ReconciliationInstructions - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available. - `transactionHash` string — Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available. - `rateDetails` IncomingRateDetails — Details about the rate and fees for an incoming transaction. Note: `gridApiFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged. - `gridApiMultiplier` number, double, required — The underlying multiplier from the mSATS to the receiving currency, including variable fees. - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount. - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. - `failureReason` 'LNURLP_FAILED' | 'PAY_REQUEST_FAILED' | 'PAYMENT_APPROVAL_WEBHOOK_ERROR' | 'PAYMENT_APPROVAL_TIMED_OUT' | 'OFFRAMP_FAILED' | 'MISSING_MANDATORY_PAYEE_DATA' | 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' — Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. - OutgoingTransaction - `id` string, required — Unique identifier for the transaction - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `EXPIRED` | Quote wasn't executed before expiry window | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | Payout successfully reached the destination | | `FAILED` | Something went wrong — accompanied by a `failureReason` | - `type` 'OUTGOING', required — Type of transaction (incoming payment or outgoing payment) - `destination` union, required - AccountTransactionDestination — Destination account details - `destinationType` 'ACCOUNT', required - `accountId` string, required — Destination account identifier - UmaAddressTransactionDestination — UMA address destination details - `destinationType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the recipient - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming) - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming) - `settledAt` string, date-time — When the payment was or will be settled - `createdAt` string, date-time — When the transaction was created - `updatedAt` string, date-time — When the transaction was last updated - `agentId` string — If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions. - `description` string — Optional memo or description for the payment - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform. - `source` union, required - AccountTransactionSource — Source account details - `sourceType` 'ACCOUNT', required - `accountId` string, required — Source account identifier - UmaAddressTransactionSource — UMA address source details - `sourceType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the sender - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — The customer on whose behalf the transaction was initiated. - `currency` string, required — Currency code for the funding source - `sentAmount` CurrencyAmount, required - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `receivedAmount` CurrencyAmount - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - `currency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `exchangeRate` number — Number of sending currency units per receiving currency unit. - `fees` integer — The fees associated with the quote in the smallest unit of the sending currency (eg. cents). - `reconciliationInstructions` ReconciliationInstructions - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available. - `transactionHash` string — Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available. - `quoteId` string — The ID of the quote that was used to trigger this payment - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. - `instructionsNotes` string — Additional human-readable instructions for making the payment - `isPlatformAccount` boolean — Indicates whether the account is a platform account or a customer account. - `accountOrWalletInfo` union, required - PaymentUsdAccountInfo - … - PaymentBrlAccountInfo - … - PaymentMxnAccountInfo - … - PaymentDkkAccountInfo - … - PaymentEurAccountInfo - … - PaymentInrAccountInfo - … - PaymentNgnAccountInfo - … - PaymentCadAccountInfo - … - PaymentGbpAccountInfo - … - PaymentHkdAccountInfo - … - PaymentIdrAccountInfo - … - PaymentMyrAccountInfo - … - PaymentPhpAccountInfo - … - PaymentSgdAccountInfo - … - PaymentThbAccountInfo - … - PaymentVndAccountInfo - … - PaymentAedAccountInfo - … - PaymentKesAccountInfo - … - PaymentMwkAccountInfo - … - PaymentRwfAccountInfo - … - PaymentTzsAccountInfo - … - PaymentUgxAccountInfo - … - PaymentXofAccountInfo - … - PaymentZarAccountInfo - … - PaymentZmwAccountInfo - … - PaymentBwpAccountInfo - … - PaymentXafAccountInfo - … - PaymentBdtAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber - … - PaymentArsAccountInfo - … - PaymentCopAccountInfo - … - PaymentEgpAccountInfo - … - PaymentGhsAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber - … - PaymentGtqAccountInfo - … - PaymentHtgAccountInfo - … - PaymentJmdAccountInfo - … - PaymentPkrAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: bankName, phoneNumber - … - PaymentSlvAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: bankAccountType, accountNumber - MOBILE_MONEY: phoneNumber - … - PaymentSparkWalletInfo - … - PaymentLightningInvoiceInfo - … - PaymentSolanaWalletInfo - … - PaymentTronWalletInfo - … - PaymentPolygonWalletInfo - … - PaymentBaseWalletInfo - … - PaymentEthereumWalletInfo - … - PaymentEmbeddedWalletInfo - … - `refund` Refund - `reference` string, required — The unique reference ID of the refund - `initiatedAt` string, date-time, required — When the refund was initiated - `settledAt` string, date-time — When the refund was settled - `status` 'PENDING' | 'COMPLETED' | 'FAILED', required — Current status of the refund - `reason` 'TRANSACTION_FAILED' | 'USER_CANCELLATION' | 'TIMEOUT' — Reason for the refund - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged. - `counterpartyMultiplier` number, double, required — The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution. - `counterpartyFixedFee` integer, required — The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents). - `gridApiMultiplier` number, double, required — The underlying multiplier from the sending currency to mSATS, including variable fees. - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount. - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate. - `failureReason` 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' | 'LIGHTNING_PAYMENT_FAILED' | 'FUNDING_AMOUNT_MISMATCH' | 'COUNTERPARTY_POST_TX_FAILED' — Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. - `hasMore` boolean, required — Indicates if more results are available beyond this page - `nextCursor` string — Cursor to retrieve the next page of results (only present if hasMore is true) - `totalCount` integer — Total number of transactions matching the criteria (excluding pagination) ## Other responses - `400` — Bad request - Invalid parameters - `401` — Unauthorized - `500` — Internal service error ## Changes - **2026-05-28** `d0bce562bffd` — 14 breaking, 5 warning, 9 info - the response property `data/items/oneOf[subschema #1: Incoming Transaction]/allOf[subschema #2]/reconciliationInstructions/reference` became optional for the status `200` - the response property `data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo/oneOf[subschema #28: BDT Account]/allOf[#/components/schemas/BdtAccountInfo]/allOf[#/components/schemas/BdtAccountInfoBase]/accountNumber` became optional for the status `200` - the response property `data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo/oneOf[subschema #28: BDT Account]/allOf[#/components/schemas/BdtAccountInfo]/allOf[#/components/schemas/BdtAccountInfoBase]/branchCode` became optional for the status `200` - the response property `data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo/oneOf[subschema #28: BDT Account]/allOf[#/components/schemas/BdtAccountInfo]/allOf[#/components/schemas/BdtAccountInfoBase]/phoneNumber` became optional for the status `200` - …24 more - …earlier changes not shown [Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/transactions/get.md) --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/d0bce562bffd/schema)