Institutional Client Reward API Reference

📡 This document provides the API reference for the Daily Rewards endpoint, which institutional clients can use to query daily reward breakdowns for their party IDs.

Base URL

https://cbtc-data-api.bitsafe.finance

Response Format

All API responses follow a consistent structure: ### ✅ Success Response

{
  "success": true,
  "data": <response_data>
}

### ❌ Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

---

Daily Rewards

Query daily rewards for specified parties using the transfer_rewards helper table.

🔗 Endpoint: POST /api/v1/analytics/daily-rewards Content-Type: application/json

Request Body

Field	Type	Required	Description
parties	string[]	Yes	List of your party IDs
start_date	string (YYYY-MM-DD)	Yes	Start date for the query range
end_date	string (YYYY-MM-DD)	Yes	End date for the query range

Response

{
  "success": true,
  "data": {
    "daily_rewards": [
      {
        "date": "2025-01-15",
        "transfer_creation_count": 50,
        "accepted_transfer_count": 42,
        "total_reward": "51.849",
        "client_reward": "20.7396"
      }
    ],
    "total_accepted_transfer_count": 150,
    "total_reward": "1234.5678",
    "total_client_reward": "493.8271"
  }
}

Response Fields

Field	Type	Description
daily_rewards	array	Array of daily reward entries
daily_rewards[].date	string	The date (YYYY-MM-DD format)
daily_rewards[].transfer_creation_count	integer	Number of transfer offers created on this day
daily_rewards[].accepted_transfer_count	integer	Number of accepted transfer offers on this day
daily_rewards[].total_reward	string	Total CC reward for this day from transfer_rewards table
daily_rewards[].client_reward	string	Client share: (total_reward x 0.8) x 0.5 (DA cost deducted, then 50%)
total_accepted_transfer_count	integer	Total number of accepted transfers across all days
total_reward	string	Sum of all daily total_reward values
total_client_reward	string	Sum of all daily client_reward values

Status Codes

Code	Meaning
200 OK	Request successful
500 Internal Server Error	Database query failed or internal error

---

Examples

Yaak

In Yaak, use POST api_url/api/v1/analytics/daily-rewards with the following JSON body:

{
  "parties": ["party1::1220abc...", "party2::1220def..."],
  "start_date": "2026-01-01",
  "end_date": "2026-01-31"
}

curl

curl -X POST https://cbtc-data-api.bitsafe.finance/api/v1/analytics/daily-rewards \
  -H "Content-Type: application/json" \
  -d '{
    "parties": ["party1::1220abc...", "party2::1220def..."],
    "start_date": "2026-01-01",
    "end_date": "2026-01-31"
  }'

---

📝 Notes

• Client reward calculated as: (rewards x 0.8 - costs) x 0.5

• Returns empty results if no parties are provided

• Only days with accepted transfers are included in daily_rewards

• Rewards are paid out on accepted transfers only

• API queries for senders only