{"templateId":"markdown","versions":[{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/api-docs/tutorials/get-ledger-balances-and-transactions","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/tutorials/get-ledger-balances-and-transactions","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Get ledger balances and transactions","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"get-ledger-balances-and-transactions","__idx":0},"children":["Get ledger balances and transactions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial, you'll use two ledger API operations to monitor your account balance and retrieve a detailed record of activity in your prefunded account:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get available balances"]}," — retrieve the current available and reserved balances for your account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get ledger transactions"]}," — retrieve a paginated list of ledger transactions within a date-time range for reconciliation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll also learn how to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Paginate through large result sets using offset-based pagination."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Filter by payment ID to find all ledger entries associated with a specific payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Export results as CSV for use in reconciliation workflows."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For background on how ledger operations (RESERVE, DEBIT, CREDIT, RELEASE) affect your balance, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/ledger-transactions"},"children":["Ledger transactions"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To follow this tutorial, you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access to the Ripple Payments Direct 2.0 API UAT environment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A valid OAuth2 access token. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/request-an-access-token"},"children":["Request an access token"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["At least one completed or in-flight payment (to observe meaningful ledger entries)."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-get-available-balances","__idx":2},"children":["Step 1: Get available balances"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get available balances"]}," operation to see how much is currently available in your prefunded account, and how much is reserved for in-flight payments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint","__idx":3},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/balances"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"optional-query-parameter","__idx":4},"children":["Optional query parameter"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter results to a single currency (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},"). If omitted, all currencies are returned."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--all-currencies","__idx":5},"children":["Example request — all currencies"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/balances\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--usd-only","__idx":6},"children":["Example request — USD only"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/balances?currency=USD\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response","__idx":7},"children":["Example response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"timestamp\": \"2025-03-15T10:30:00.000000Z\",\n  \"balances\": [\n    {\n      \"fundingType\": \"FUNDED\",\n      \"currency\": \"USD\",\n      \"availableBalance\": 50000.00,\n      \"reservedBalance\": 2500.00\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"understanding-the-balance-fields","__idx":8},"children":["Understanding the balance fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableBalance"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funds that are currently spendable. This is the balance you can use to initiate new payments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reservedBalance"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funds currently held aside for in-flight payments. You cannot use this balance to initiate new payments until the reservation is released or consumed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The time at which the balance snapshot was taken."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Balance and payment creation"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a payment creation request fails with error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_067"]}," (Insufficient balance), compare ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableBalance"]}," against the payment amount. The reserved balance is not available for new payments."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-get-ledger-transactions","__idx":9},"children":["Step 2: Get ledger transactions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get ledger transactions"]}," operation to retrieve a paginated list of ledger entries within a date-time range. Each entry shows the operation performed, its effect on your available balance, and the source that created it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint-1","__idx":10},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/ledger-transactions"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-query-parameters","__idx":11},"children":["Required query parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 4217 currency code."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start-dttm"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Start of the date-time range (inclusive, UTC)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-03-15T00:00:00Z"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end-dttm"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["End of the date-time range (exclusive, UTC)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-03-16T00:00:00Z"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of records per page. Minimum: 1, maximum: 50."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["25"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":12},"children":["Example request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/ledger-transactions?\\\ncurrency=USD\\\n&start-dttm=2025-03-15T00:00:00Z\\\n&end-dttm=2025-03-16T00:00:00Z\\\n&page-size=25\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\" \\\n  -H \"Accept: application/json\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response-1","__idx":13},"children":["Example response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"offset\": \"0\",\n  \"pageSize\": \"25\",\n  \"pageElements\": \"10\",\n  \"total\": \"10\",\n  \"statementTransactions\": [\n    {\n      \"tenant\": \"acme-corp\",\n      \"amount\": \"14.00\",\n      \"currency\": \"USD\",\n      \"operation\": \"DEBIT\",\n      \"txnSource\": \"PAYMENTS\",\n      \"status\": \"SUCCESS\",\n      \"createdDttm\": \"2025-03-15T10:25:12.000000Z\",\n      \"updatedDttm\": \"2025-03-15T10:25:12.000000Z\",\n      \"availableBalanceBefore\": \"50014.00\",\n      \"availableBalanceAfter\": \"50014.00\"\n    },\n    {\n      \"tenant\": \"acme-corp\",\n      \"amount\": \"10000.00\",\n      \"currency\": \"USD\",\n      \"operation\": \"DEBIT\",\n      \"txnSource\": \"PAYMENTS\",\n      \"status\": \"SUCCESS\",\n      \"createdDttm\": \"2025-03-15T10:25:10.000000Z\",\n      \"updatedDttm\": \"2025-03-15T10:25:10.000000Z\",\n      \"availableBalanceBefore\": \"50014.00\",\n      \"availableBalanceAfter\": \"50014.00\"\n    },\n    {\n      \"tenant\": \"acme-corp\",\n      \"amount\": \"10014.00\",\n      \"currency\": \"USD\",\n      \"operation\": \"RESERVE\",\n      \"txnSource\": \"PAYMENTS\",\n      \"status\": \"SUCCESS\",\n      \"createdDttm\": \"2025-03-15T10:23:45.000000Z\",\n      \"updatedDttm\": \"2025-03-15T10:23:45.000000Z\",\n      \"availableBalanceBefore\": \"60014.00\",\n      \"availableBalanceAfter\": \"50000.00\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"understanding-ledger-operations","__idx":14},"children":["Understanding ledger operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operation"]}," field tells you what action was applied to your account. The sequence of RESERVE → DEBIT is the typical pattern for a completed payment."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation"},"children":["Operation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Effect on availableBalance"},"children":["Effect on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableBalance"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it occurs"},"children":["When it occurs"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Increases"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funds are added to your account (for example, a top-up)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESERVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Decreases"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funds are set aside when a payment enters the validation or transferring state."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEBIT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No change (typically)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reserved funds are consumed when a payment completes. The available balance already decreased at RESERVE time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RELEASE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Increases"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reserved funds are returned when a payment fails or is cancelled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VOID_BALANCE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Implementation-specific"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Administrative correction. Contact Ripple technical support for details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OVERRIDE_BALANCE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Implementation-specific"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Administrative correction. Contact Ripple technical support for details."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Why DEBIT doesn't change the available balance"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a payment starts, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESERVE"]}," operation moves funds out of available balance and into a reserved state. When the payment completes, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEBIT"]}," finalizes the outflow from the reserved amount. But since available balance already decreased at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESERVE"]}," time, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableBalanceBefore"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableBalanceAfter"]}," are typically equal for a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEBIT"]}," entry. If a payment fails, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RELEASE"]}," entry returns the reserved funds to available balance."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-paginate-through-results","__idx":15},"children":["Step 3: Paginate through results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," value in the response is greater than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageElements"]},", there are more records to retrieve. Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," parameter to fetch subsequent pages."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pattern:"]}," Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," to a multiple of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}," to advance through pages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-fetch-the-second-page","__idx":16},"children":["Example: Fetch the second page"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/ledger-transactions?\\\ncurrency=USD\\\n&start-dttm=2025-03-15T00:00:00Z\\\n&end-dttm=2025-03-16T00:00:00Z\\\n&page-size=25\\\n&offset=25\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Continue incrementing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]}," until ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageElements"]}," in the response is less than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]},", which indicates you have reached the last page."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Fix your time range before paginating"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not change ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start-dttm"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end-dttm"]}," between pages of the same query. Changing the time range mid-pagination can cause you to miss or duplicate records."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-filter-by-payment-id","__idx":17},"children":["Step 4: Filter by payment ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To find all ledger entries associated with a specific payment, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txnReference"]}," parameter. For payments, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txnReference"]}," value is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]}," returned when the payment was created."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is useful for auditing a specific payment's balance impact (the RESERVE, DEBIT, and any RELEASE entries for that payment)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-look-up-ledger-entries-for-a-specific-payment","__idx":18},"children":["Example: Look up ledger entries for a specific payment"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/ledger-transactions?\\\ncurrency=USD\\\n&start-dttm=2025-03-15T00:00:00Z\\\n&end-dttm=2025-03-16T00:00:00Z\\\n&page-size=25\\\n&txnReference=aa74f2f4-5996-4f0c-9d8a-7a5e1d51c502\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response-2","__idx":19},"children":["Example response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"offset\": \"0\",\n  \"pageSize\": \"25\",\n  \"pageElements\": \"2\",\n  \"total\": \"2\",\n  \"statementTransactions\": [\n    {\n      \"tenant\": \"acme-corp\",\n      \"amount\": \"10014.00\",\n      \"currency\": \"USD\",\n      \"operation\": \"DEBIT\",\n      \"txnSource\": \"PAYMENTS\",\n      \"status\": \"SUCCESS\",\n      \"createdDttm\": \"2025-03-15T10:25:10.000000Z\",\n      \"updatedDttm\": \"2025-03-15T10:25:10.000000Z\",\n      \"availableBalanceBefore\": \"50014.00\",\n      \"availableBalanceAfter\": \"50014.00\"\n    },\n    {\n      \"tenant\": \"acme-corp\",\n      \"amount\": \"10014.00\",\n      \"currency\": \"USD\",\n      \"operation\": \"RESERVE\",\n      \"txnSource\": \"PAYMENTS\",\n      \"status\": \"SUCCESS\",\n      \"createdDttm\": \"2025-03-15T10:23:45.000000Z\",\n      \"updatedDttm\": \"2025-03-15T10:23:45.000000Z\",\n      \"availableBalanceBefore\": \"60014.00\",\n      \"availableBalanceAfter\": \"50000.00\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This shows the complete ledger impact of the payment: funds were reserved when the payment was created, and debited when it completed."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-export-as-csv","__idx":20},"children":["Step 5: Export as CSV"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For reconciliation workflows, you can request the response as a CSV file by setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept: text/csv"]}," header. If this header is omitted, the API returns JSON by default."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-download-a-csv-statement","__idx":21},"children":["Example: Download a CSV statement"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/ledger-transactions?\\\ncurrency=USD\\\n&start-dttm=2025-03-01T00:00:00Z\\\n&end-dttm=2025-04-01T00:00:00Z\\\n&page-size=50\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\" \\\n  -H \"Accept: text/csv\" \\\n  -o ledger-march-2025.csv\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"csv-format","__idx":22},"children":["CSV format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CSV response includes the same fields as the JSON response, as column headers:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csv","header":{"controls":{"copy":{}}},"source":"tenant,amount,currency,operation,txnSource,status,createdDttm,updatedDttm,availableBalanceBefore,availableBalanceAfter\nacme-corp,10014.00,USD,DEBIT,PAYMENTS,SUCCESS,2025-03-15T10:25:10Z,2025-03-15T10:25:10Z,50014.00,50014.00\nacme-corp,10014.00,USD,RESERVE,PAYMENTS,SUCCESS,2025-03-15T10:23:45Z,2025-03-15T10:23:45Z,60014.00,50000.00\n","lang":"csv"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Pagination applies to CSV too"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["CSV responses are also paginated. For large date ranges, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}," parameter to retrieve subsequent pages and concatenate the results, omitting the header row from all pages after the first."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sorting-results","__idx":23},"children":["Sorting results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort-key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort-direction"]}," to control the order of results. The default sort order is determined by the API if these parameters are omitted."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.test.ripple.com/v2/ledger-transactions?\\\ncurrency=USD\\\n&start-dttm=2025-03-15T00:00:00Z\\\n&end-dttm=2025-03-16T00:00:00Z\\\n&page-size=25\\\n&sort-key=CREATED_AT\\\n&sort-direction=DESC\" \\\n  -H \"Authorization: Bearer <YOUR_TOKEN>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort-key"]}," values:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sorts by"},"children":["Sorts by"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATED_AT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction creation timestamp"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STATEMENT_OPERATION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operation type (CREDIT, DEBIT, etc.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STATEMENT_SOURCE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction source (PAYMENTS, BANK, etc.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STATEMENT_STATUS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ledger transaction status"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STATEMENT_TXN_REFERENCE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction reference"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STATEMENT_UPDATED_AT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Last update timestamp"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":24},"children":["Error handling"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_251"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request parameter missing."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A required parameter (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start-dttm"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end-dttm"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page-size"]},") is missing. Add the missing parameter and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYS_301"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal server error."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff. Contact Ripple technical support if the issue persists."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CFG_201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid configuration."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unable to retrieve balances due to a configuration issue. Contact Ripple technical support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_001"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your token is invalid or expired. Generate a new access token and retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary-and-next-steps","__idx":25},"children":["Summary and next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial, you:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieved your current available and reserved balances using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/balances"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fetched a paginated list of ledger transactions for a date range using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/ledger-transactions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Filtered transactions by payment ID using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txnReference"]}," parameter."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exported results as CSV for reconciliation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next steps:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To understand how ledger operations map to payment lifecycle events, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/ledger-transactions"},"children":["Ledger transactions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To create payments that will appear as ledger entries, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/create-a-payment"},"children":["Create a payment"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For balance-related error codes, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/error-codes/api-errors"},"children":["API error codes"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For monitoring payment state changes that drive ledger activity, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/best-practices/polling"},"children":["Polling"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/best-practices/notification-webhooks"},"children":["Notification webhooks"]},"."]}]}]},"headings":[{"value":"Get ledger balances and transactions","id":"get-ledger-balances-and-transactions","depth":1},{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"Step 1: Get available balances","id":"step-1-get-available-balances","depth":2},{"value":"Endpoint","id":"endpoint","depth":3},{"value":"Optional query parameter","id":"optional-query-parameter","depth":3},{"value":"Example request — all currencies","id":"example-request--all-currencies","depth":3},{"value":"Example request — USD only","id":"example-request--usd-only","depth":3},{"value":"Example response","id":"example-response","depth":3},{"value":"Understanding the balance fields","id":"understanding-the-balance-fields","depth":3},{"value":"Step 2: Get ledger transactions","id":"step-2-get-ledger-transactions","depth":2},{"value":"Endpoint","id":"endpoint-1","depth":3},{"value":"Required query parameters","id":"required-query-parameters","depth":3},{"value":"Example request","id":"example-request","depth":3},{"value":"Example response","id":"example-response-1","depth":3},{"value":"Understanding ledger operations","id":"understanding-ledger-operations","depth":3},{"value":"Step 3: Paginate through results","id":"step-3-paginate-through-results","depth":2},{"value":"Example: Fetch the second page","id":"example-fetch-the-second-page","depth":3},{"value":"Step 4: Filter by payment ID","id":"step-4-filter-by-payment-id","depth":2},{"value":"Example: Look up ledger entries for a specific payment","id":"example-look-up-ledger-entries-for-a-specific-payment","depth":3},{"value":"Example response","id":"example-response-2","depth":3},{"value":"Step 5: Export as CSV","id":"step-5-export-as-csv","depth":2},{"value":"Example: Download a CSV statement","id":"example-download-a-csv-statement","depth":3},{"value":"CSV format","id":"csv-format","depth":3},{"value":"Sorting results","id":"sorting-results","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Summary and next steps","id":"summary-and-next-steps","depth":2}],"frontmatter":{"title":"Get ledger balances and transactions","toc":{"enable":true,"maxDepth":2},"seo":{"title":"Get ledger balances and transactions"}},"lastModified":"2026-03-31T03:43:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/tutorials/get-ledger-balances-and-transactions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}