Reporting

Learn how to use the Metrics API with detailed examples. This guide covers common patterns, step-by-step workflows, and code samples for tracking transaction volume, activity patterns, and user growth.

Prerequisite: Before diving into examples, make sure you’ve read the Metrics documentation to understand core concepts like metric templates, saved metrics, and breakdowns.

Quickstart

1. List Templates

List available templates to see what you can measure:

curl -X GET "https://sandbox.hifibridge.com/v2/reporting/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": [
    {
      "template": "GROSS_VOLUME",
      "displayName": "Gross Volume",
      "description": "Total combined USD-equivalent value of completed Onramp and Offramp transactions",
      "breakdownOptions": ["transactionType", "userId"]
    },
    {
      "template": "TRANSACTION_COUNT",
      "displayName": "Transaction Count",
      "description": "Aggregated count of transactions grouped by status and type over time",
      "breakdownOptions": ["transactionType", "transactionStatus", "userId"]
    },
    {
      "template": "NEW_USERS",
      "displayName": "New Users",
      "description": "Count of new unique end-users onboarded within the time period",
      "breakdownOptions": null
    }
  ]
}

2. Preview Metrics

Preview results by providing a template with parameters. Saving is optional—preview lets you query metrics without persisting anything.

curl -X POST "https://sandbox.hifibridge.com/v2/reporting/metrics/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "GROSS_VOLUME",
    "params": {
      "createdAfter": "2025-11-12T18:01:29.891Z",
      "createdBefore": "2025-12-12T18:01:29.891Z",
      "calculationInterval": "day",
      "transactionTypes": [
        "transfer",
        "onramp",
        "offramp"
      ],
      "transactionStatuses": [
        "COMPLETED"
      ]
    }
  }'

Response:

View Response

{
  "status": "success",
  "data": [
    {
      "periodStart": "2025-12-12",
      "grossVolume": 0
    },
    {
      "periodStart": "2025-12-11",
      "grossVolume": 10
    }
  ],
  "metadata": {
    "template": "GROSS_VOLUME",
    "recordCount": 31,
    "projectedRowCount": null,
    "filledCount": 26,
    "calculationInterval": "day",
    "dateRange": {
      "start": "2025-11-12T18:01:29.891Z",
      "end": "2025-12-12T18:01:29.891Z"
    },
    "filters": {
      "createdAfter": {
        "applied": "subset",
        "specified": true,
        "values": "2025-11-12T18:01:29.891Z"
      },
      "createdBefore": {
        "applied": "subset",
        "specified": true,
        "values": "2025-12-12T18:01:29.891Z"
      },
      "calculationInterval": {
        "applied": "subset",
        "specified": true,
        "values": "day"
      },
      "transactionTypes": {
        "applied": "subset",
        "specified": true,
        "count": 3,
        "values": ["transfer", "onramp", "offramp"]
      },
      "transactionStatuses": {
        "applied": "subset",
        "specified": true,
        "count": 1,
        "values": ["COMPLETED"]
      },
      "userIds": {
        "applied": "all",
        "specified": false,
        "count": 227,
        "note": "227 total (list omitted for brevity)"
      }
    },
    "breakdowns": null
  }
}

3. Save Metric

Create a saved metric to persist the configuration or build custom metrics for specific users:

curl -X POST "https://sandbox.hifibridge.com/v2/reporting/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "GROSS_VOLUME",
    "name": "Daily Volume by Direction",
    "params": {
      "createdAfter": "2025-01-01",
      "createdBefore": "2025-01-31",
      "calculationInterval": "day",
      "breakdowns": ["transactionType"]
    }
  }'

Response:

{
  "status": "success",
  "data": {
    "id": "mtr_abc123",
    "name": "Daily Volume by Direction",
    "template": "GROSS_VOLUME"
  }
}

4. Query Results

Retrieve data from your saved metric:

curl -X GET "https://sandbox.hifibridge.com/v2/reporting/metrics/mtr_abc123/results" \
  -H "Authorization: Bearer YOUR_API_KEY"

Configuration Examples

Date Range

Every metric requires a date range:

{
  "createdAfter": "2025-01-01",
  "createdBefore": "2025-01-31"
}

Dates use ISO 8601 format (YYYY-MM-DD). Available parameters vary by template—check the template response for supported params.

Calculation Interval

Choose how to aggregate data over time:

• day — Daily totals
• week — Weekly totals (starts Monday)
• month — Monthly totals

Example: Daily aggregation returns one row per day in your date range.

{
  "calculationInterval": "day"
}

Filters

Narrow results to specific subsets:

Filter by users:

{
  "userIds": ["usr_abc123", "usr_def456"]
}

Filter by transaction type:

{
  "transactionTypes": ["onramp", "offramp", "transfer"]
}

Filter by transaction status:

{
  "transactionStatuses": ["COMPLETED", "FAILED", "PENDING"]
}

Available filters depend on the template. Get filter options:

curl -X GET "https://sandbox.hifibridge.com/v2/reporting/params/userIds/options" \
  -H "Authorization: Bearer YOUR_API_KEY"

Breakdowns

Split metrics by dimensions for comparison:

• transactionType — Separate rows for each direction (onramp, offramp, transfer)
• transactionStatus — Separate rows for each status (COMPLETED, FAILED, PENDING, etc.)
• userId — Separate rows for each user

Without breakdowns, you get one row per time period. With breakdowns, you get multiple rows per period—one for each unique combination of breakdown values.

{
  "breakdowns": ["transactionType"]
}

Check each template’s breakdownOptions field. NEW_USERS doesn’t support breakdowns.

Common Patterns

Track Volume by Type

Track daily volume split by transaction type (onramp vs offramp):

curl -X POST "https://sandbox.hifibridge.com/v2/reporting/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "GROSS_VOLUME",
    "name": "Daily Volume Split",
    "params": {
      "createdAfter": "2025-01-01",
      "createdBefore": "2025-01-31",
      "calculationInterval": "day",
      "breakdowns": ["transactionType"]
    }
  }'

Returns separate volume numbers for onramps and offramps each day.

Monitor User Activity

Track weekly transaction counts for specific users, broken down by success/failure:

curl -X POST "https://sandbox.hifibridge.com/v2/reporting/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "TRANSACTION_COUNT",
    "name": "VIP User Activity",
    "params": {
      "createdAfter": "2025-01-01",
      "createdBefore": "2025-01-31",
      "calculationInterval": "week",
      "userIds": ["usr_abc123", "usr_def456"],
      "breakdowns": ["userId", "transactionStatus"]
    }
  }'

Shows weekly transaction counts for specific users, broken down by success/failure.

Measure User Acquisition

Track monthly new user growth:

curl -X POST "https://sandbox.hifibridge.com/v2/reporting/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "NEW_USERS",
    "name": "Monthly Growth",
    "params": {
      "createdAfter": "2025-01-01",
      "createdBefore": "2025-12-31",
      "calculationInterval": "month"
    }
  }'

Returns new user count for each month.

Managing Saved Metrics

List Metrics

List all your saved metrics:

curl -X GET "https://sandbox.hifibridge.com/v2/reporting/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY"

View Details

Get details for a specific metric:

curl -X GET "https://sandbox.hifibridge.com/v2/reporting/metrics/mtr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Metric

Update a saved metric’s configuration:

curl -X POST "https://sandbox.hifibridge.com/v2/reporting/metrics/mtr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "params": {
      "createdAfter": "2025-02-01",
      "createdBefore": "2025-02-28"
    }
  }'

Delete Metric

Delete a saved metric:

curl -X DELETE "https://sandbox.hifibridge.com/v2/reporting/metrics/mtr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Related Resources

• Metrics Overview — Core concepts and overview
• API Reference: Metrics — Complete endpoint specs
• Transactions — Understanding transaction types and statuses
• Users — User management