List Transactions

Retrieve a paginated list of transactions with optional filtering.

Query Parameters

limit

integer

default:"20"

Number of transactions to return per page. Maximum recommended: 100.

offset

integer

default:"0"

Number of transactions to skip for pagination.

Filter Parameters

Apply filters using the format field_operator=value:

status_eq

string

Filter by exact status match.Example: status_eq=APPLIED

currency_eq

string

Filter by exact currency match.Example: currency_eq=USD

currency_in

string

Filter by multiple currencies (comma-separated).Example: currency_in=USD,EUR,GBP

amount_gte

number

Filter transactions with amount greater than or equal to value.Example: amount_gte=1000

amount_lte

number

Filter transactions with amount less than or equal to value.Example: amount_lte=5000

created_at_between

string

Filter by date range (pipe-separated ISO 8601 timestamps).Example: created_at_between=2024-01-01T00:00:00Z|2024-12-31T23:59:59Z

source_eq

string

Filter by source balance ID.Example: source_eq=bln_src123

destination_eq

string

Filter by destination balance ID.Example: destination_eq=bln_dst456

reference_eq

string

Filter by transaction reference.Example: reference_eq=order-12345

Filter Operators

Supported operators for query parameters:

eq - Equals
ne - Not equals
gt - Greater than
gte - Greater than or equal to
lt - Less than
lte - Less than or equal to
in - In list (comma-separated values)
between - Between two values (pipe-separated)
contains - Contains substring (for text fields)

Response

Returns an array of transaction objects.

[].transaction_id

string

Unique transaction identifier.

[].source

string

Source balance ID.

[].destination

string

Destination balance ID.

[].reference

string

Transaction reference.

[].amount

number

Amount in major currency units.

[].precise_amount

string

Exact amount in minor units.

[].currency

string

Currency code.

[].status

string

Transaction status.

[].created_at

string

ISO 8601 creation timestamp.

See Get Transaction for complete field documentation.

[
  {
    "transaction_id": "txn_a1b2c3d4e5f6",
    "source": "bln_src123",
    "destination": "bln_dst456",
    "reference": "order-12345",
    "amount": 100.50,
    "precise_amount": "10050",
    "precision": 100,
    "currency": "USD",
    "description": "Payment for order #12345",
    "status": "APPLIED",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "transaction_id": "txn_b7c8d9e0f1g2",
    "source": "bln_src123",
    "destination": "bln_dst789",
    "reference": "order-12346",
    "amount": 250.00,
    "precise_amount": "25000",
    "precision": 100,
    "currency": "USD",
    "description": "Payment for order #12346",
    "status": "APPLIED",
    "created_at": "2024-01-15T11:00:00Z"
  }
]

curl -X GET "https://api.blnkfinance.com/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination

Basic Pagination

Use limit and offset for pagination:

# Page 1 (first 20)
GET /transactions?limit=20&offset=0

# Page 2 (next 20)
GET /transactions?limit=20&offset=20

# Page 3 (next 20)
GET /transactions?limit=20&offset=40

Pagination Example

async function getAllTransactions() {
  const allTransactions = [];
  let offset = 0;
  const limit = 100;
  
  while (true) {
    const transactions = await fetch(
      `/transactions?limit=${limit}&offset=${offset}`
    ).then(r => r.json());
    
    if (transactions.length === 0) break;
    
    allTransactions.push(...transactions);
    offset += limit;
  }
  
  return allTransactions;
}

Advanced Filtering

For complex filtering requirements, use the Filter Transactions endpoint with POST request body.

Filter vs List Comparison

Use GET /transactions (this endpoint) when:

Simple filters (1-3 conditions)
Query parameters are sufficient
Building shareable URLs

Use POST /transactions/filter when:

Complex filters (multiple conditions)
Combining AND/OR logic
Need result counts
Sorting and grouping required

Common Filter Examples

By Status

# Only applied transactions
GET /transactions?status_eq=APPLIED

# Exclude rejected
GET /transactions?status_ne=REJECTED

By Amount Range

# Transactions $100-$1000
GET /transactions?amount_gte=100&amount_lte=1000

# Large transactions only
GET /transactions?amount_gte=10000

By Date Range

# January 2024 transactions
GET /transactions?created_at_between=2024-01-01T00:00:00Z|2024-01-31T23:59:59Z

# Last 24 hours (example)
GET /transactions?created_at_gte=2024-01-15T10:00:00Z

By Balance

# All debits from specific balance
GET /transactions?source_eq=bln_src123

# All credits to specific balance
GET /transactions?destination_eq=bln_dst456

# All transactions involving balance (requires Filter endpoint)
POST /transactions/filter

Multiple Currencies

# USD, EUR, or GBP
GET /transactions?currency_in=USD,EUR,GBP

Combined Filters

# Applied USD transactions over $100 from specific source
GET /transactions?status_eq=APPLIED&currency_eq=USD&amount_gte=100&source_eq=bln_src123

Error Responses

error

string

Error message.

errors

array

Array of validation errors for invalid filters.

Common Errors

400 Bad Request - Invalid Filter

{
  "errors": ["invalid operator 'invalid_op' for field 'amount'"]
}

400 Bad Request - Invalid Date Format

{
  "errors": ["invalid date format for 'created_at_between'"]
}

Performance Considerations

Use appropriate page sizes
- Small pages (20-50): Better for UI pagination
- Large pages (100+): Better for batch processing
- Very large pages (>1000): May cause timeouts
Add filters to reduce result sets
- Filter by date range to limit scans
- Filter by status to skip rejected transactions
- Use specific balance IDs when possible
Consider caching
- Cache recent pages for frequently accessed data
- Invalidate cache when new transactions are created
Use POST /transactions/filter for complex queries
- Better performance for multi-field filters
- Supports result counting
- Allows sorting and grouping

Use Cases

Transaction History UI

function TransactionList({ balanceId }) {
  const [page, setPage] = useState(0);
  const limit = 20;
  
  const { data } = useQuery(['transactions', page], () =>
    fetch(`/transactions?source_eq=${balanceId}&limit=${limit}&offset=${page * limit}`)
      .then(r => r.json())
  );
  
  return (
    <div>
      {data?.map(txn => <TransactionRow key={txn.transaction_id} {...txn} />)}
      <Pagination page={page} onChange={setPage} />
    </div>
  );
}

Export Transactions

def export_transactions_csv(start_date, end_date):
    offset = 0
    limit = 1000
    
    with open('transactions.csv', 'w') as f:
        writer = csv.writer(f)
        writer.writerow(['ID', 'Date', 'Amount', 'Currency', 'Status'])
        
        while True:
            params = {
                'limit': limit,
                'offset': offset,
                'created_at_between': f'{start_date}|{end_date}'
            }
            
            txns = requests.get('/transactions', params=params).json()
            if not txns:
                break
                
            for txn in txns:
                writer.writerow([
                    txn['transaction_id'],
                    txn['created_at'],
                    txn['amount'],
                    txn['currency'],
                    txn['status']
                ])
            
            offset += limit

Monitor Recent Activity

setInterval(async () => {
  const recent = await fetch(
    '/transactions?limit=10&offset=0&status_eq=APPLIED'
  ).then(r => r.json());
  
  // Check for new transactions since last check
  const newTransactions = recent.filter(txn => 
    new Date(txn.created_at) > lastCheckTime
  );
  
  if (newTransactions.length > 0) {
    console.log(`${newTransactions.length} new transactions`);
  }
}, 60000); // Check every minute

Filter Transactions - Advanced filtering with POST
Get Transaction - Retrieve single transaction
Get by Reference - Lookup by reference

Overview

Ledgers

Balances

Balance Monitors

Transactions

Identities

Accounts

Reconciliation

Search

Webhooks

API Keys

Metadata

Backup

List Transactions

Query Parameters

Filter Parameters

Filter Operators

Response

Advanced Filtering

Filter vs List Comparison

Common Filter Examples

By Status

By Amount Range

By Date Range

By Balance

Multiple Currencies

Combined Filters

Error Responses

Common Errors

Performance Considerations

Use Cases

Transaction History UI

Export Transactions

Monitor Recent Activity

Build docs developers (and LLMs) love

Overview

Ledgers

Balances

Balance Monitors

Transactions

Identities

Accounts

Reconciliation

Search

Webhooks

API Keys

Metadata

Backup

​Query Parameters

​Filter Parameters

​Filter Operators

​Response

​Pagination

​Basic Pagination

​Pagination Example

​Advanced Filtering

​Filter vs List Comparison

​Common Filter Examples

​By Status

​By Amount Range

​By Date Range

​By Balance

​Multiple Currencies

​Combined Filters

​Error Responses

​Common Errors

​Performance Considerations

​Use Cases

​Transaction History UI

​Export Transactions

​Monitor Recent Activity

​Related Endpoints

Build docs developers (and LLMs) love

Query Parameters

Filter Parameters

Filter Operators

Response

Pagination

Basic Pagination

Pagination Example

Advanced Filtering

Filter vs List Comparison

Common Filter Examples

By Status

By Amount Range

By Date Range

By Balance

Multiple Currencies

Combined Filters

Error Responses

Common Errors

Performance Considerations

Use Cases

Transaction History UI

Export Transactions

Monitor Recent Activity

Related Endpoints