Retrieve transaction history for Bitcoin rewards distributed through your platform. Transactions are returned in descending order (most recent first) and are paginated.
Basic request
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
{
"data": [
{
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "COMPLETED",
"type": "OUTGOING",
"source": {
"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
"currency": "USD"
},
"destination": {
"accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456",
"currency": "BTC"
},
"sentAmount": {
"amount": 100,
"currency": {
"code": "USD",
"symbol": "$",
"decimals": 2
}
},
"receivedAmount": {
"amount": 810,
"currency": {
"code": "BTC",
"symbol": "₿",
"decimals": 8
}
},
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"platformCustomerId": "user_789",
"description": "Weekly reward payout",
"exchangeRate": 8.1,
"settledAt": "2025-10-03T15:01:45Z",
"createdAt": "2025-10-03T15:00:00Z"
}
],
"hasMore": true,
"nextCursor": "eyJpZCI6IlRyYW5zYWN0aW9uOjAxOTU0MmY1LWIzZTctMWQwMi0wMDAwLTAwMDAwMDAwMDAyNSJ9",
"totalCount": 142
}
Common filtering patterns
Rewards for a specific customer
Get all Bitcoin rewards sent to a customer:
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=user_789' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
Rewards by date range
Get all rewards distributed in a specific period:
# October 2025 rewards
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
Dates must be in ISO 8601 format (e.g., 2025-10-03T15:00:00Z).
Failed rewards
Track rewards that failed to complete:
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=FAILED&type=OUTGOING' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
PENDING - Reward initiated, awaiting processingPROCESSING - Bitcoin purchase and transfer in progressCOMPLETED - Reward successfully deliveredFAILED - Reward failed (invalid wallet address, insufficient balance, etc.)
Get all rewards paid from your platform’s USD internal account:
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?senderAccountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965&type=OUTGOING' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
Combining filters
Narrow down results by combining multiple filters:
# All completed rewards for a customer in October
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=user_789&status=COMPLETED&startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
async function getAllRewardsForCustomer(platformCustomerId) {
const allRewards = [];
let cursor = null;
let hasMore = true;
while (hasMore) {
const url = cursor
? `https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=${platformCustomerId}&limit=100&cursor=${cursor}`
: `https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=${platformCustomerId}&limit=100`;
const response = await fetch(url, {
headers: { Authorization: `Basic ${credentials}` },
});
const { data, hasMore: more, nextCursor } = await response.json();
allRewards.push(...data);
hasMore = more;
cursor = nextCursor;
}
return allRewards;
}
The maximum limit is 100 transactions per request. Default is 20.
Get a single transaction
Retrieve details for a specific reward transaction:
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions/Transaction:019542f5-b3e7-1d02-0000-000000000025' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
Common use cases
Calculate total rewards distributed
async function calculateMonthlyRewards(month) {
const startDate = new Date(month);
const endDate = new Date(startDate);
endDate.setMonth(endDate.getMonth() + 1);
let totalUSD = 0;
let totalBTC = 0;
let cursor = null;
do {
const url = `/transactions?status=COMPLETED&startDate=${startDate.toISOString()}&endDate=${endDate.toISOString()}&cursor=${cursor || ''}`;
const { data, nextCursor } = await fetch(url).then(r => r.json());
data.forEach(tx => {
totalUSD += tx.sentAmount.amount;
totalBTC += tx.receivedAmount.amount;
});
cursor = nextCursor;
} while (cursor);
return {
totalUSD: totalUSD / 100, // Convert cents to dollars
totalBTC: totalBTC / 100000000, // Convert sats to BTC
};
}
Track customer reward history
async function getCustomerRewardsSummary(platformCustomerId) {
const response = await fetch(
`/transactions?platformCustomerId=${platformCustomerId}&status=COMPLETED`,
{ headers: { Authorization: `Basic ${credentials}` } }
);
const { data, totalCount } = await response.json();
const totalSatsReceived = data.reduce(
(sum, tx) => sum + tx.receivedAmount.amount,
0
);
return {
rewardCount: totalCount,
totalSatsReceived,
lastRewardAt: data[0]?.settledAt,
};
}
Monitor failed rewards
async function getFailedRewards(startDate) {
const response = await fetch(
`/transactions?status=FAILED&type=OUTGOING&startDate=${startDate}`,
{ headers: { Authorization: `Basic ${credentials}` } }
);
const { data } = await response.json();
return data.map(tx => ({
transactionId: tx.id,
customerId: tx.platformCustomerId,
amount: tx.sentAmount.amount / 100,
failedAt: tx.createdAt,
description: tx.description,
}));
}
Best practices
Use pagination when fetching transaction history to avoid timeouts and memory issues.
Filter by platformCustomerId for easier reconciliation with your internal user IDs.
Cache completed transaction data since it won’t change after settlement.
Always filter by type=OUTGOING when tracking rewards to exclude incoming transactions.
Next steps
