payram-analytics

name

payram-analytics

description

Query PayRam dashboard data directly via REST APIs using JWT Bearer authentication. Search payments by tx hash or email, get daily volume breakdowns, check unswept balances, view sweep history, and pull on-ramp metrics. No MCP server needed — the agent calls PayRam APIs directly with a Bearer token. Use when querying payment data, generating reports, monitoring deposits, checking sweep status, or answering questions like "how much did I receive yesterday" or "find payment with tx hash 0xabc".

PayRam Analytics — Direct API Access

Need authentication first? See payram-auth to get your Bearer token.

This skill teaches you to call PayRam dashboard APIs directly — no MCP server required. Just a BASE_URL and a Bearer token.

Prerequisites

Before using these APIs, you need:

1. BASE_URL — Your PayRam server URL (e.g., https://bedpayments.com:8443)
2. ACCESS_TOKEN — JWT Bearer token (see payram-auth)
3. PROJECT_ID — Auto-discovered (see below)

Every request below uses this header:

Authorization: Bearer <ACCESS_TOKEN>

Token expired? If you get a 401, refresh using POST /api/v1/refresh — see payram-auth for the full refresh flow.

Auto-Discover PROJECT_ID

Do not ask the user for a project ID. Discover it automatically:

GET {BASE_URL}/api/v1/external-platform/details
Authorization: Bearer <ACCESS_TOKEN>

Returns an array of platforms. Use id from the first entry. Most merchants have a single platform.

---

Common Questions & Which API to Call

Question	API to call
"How much did I receive today/yesterday?"	Daily Volume
"Find a payment by tx hash"	Payment Search with query
"Show me all payments this week"	Payment Search with dateFrom/dateTo
"How many payments are open vs closed?"	Payment Summary
"What funds haven't been swept yet?"	Unswept Balances
"Show sweep history"	Sweep Transactions
"What's my on-ramp volume?"	On-Ramp Metrics
"Show dashboard charts"	Analytics Graph Data

---

Payment Summary (Counts)

Get a quick overview of payment statuses.

POST {BASE_URL}/api/v1/external-platform/{PROJECT_ID}/payment/summary
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{}

Response:

{
  "totalCount": 1450,
  "closedCount": 1320,
  "openCount": 85,
  "cancelledCount": 45
}

Permission required: read_payment_request

---

Search Payments

The most versatile endpoint — search by tx hash, email, customer ID, date range, status, network, and currency.

POST {BASE_URL}/api/v1/external-platform/{PROJECT_ID}/payment/search
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "query": "0xabc123...",
  "paymentStatus": ["Filled", "Partial filled"],
  "currency": ["USDC", "USDT"],
  "network": ["ethereum", "base"],
  "dateFrom": "2026-03-01T00:00:00Z",
  "dateTo": "2026-03-21T23:59:59Z",
  "sortBy": "createdAt",
  "sortDirection": "DESC",
  "limit": 25,
  "offset": 0
}

All filter fields are optional. Send {} to get the latest payments with defaults.

Filter Reference

Field	Type	Description
query	string	Free-text search: tx hash, customer ID, email, reference ID
paymentStatus	string[]	Filled, Partial filled, Pending, Cancelled
webhookStatus	string[]	Success, Failed, Pending
currency	string[]	BTC, ETH, USDC, USDT, MATIC, TRX
network	string[]	bitcoin, ethereum, polygon, base, tron
dateFrom	string	ISO 8601 start date
dateTo	string	ISO 8601 end date
createdBy	string[]	user or system
externalPlatformIds	uint[]	Filter by platform/project IDs
sortBy	string	Field to sort by (e.g., createdAt, amountInUSD)
sortDirection	string	ASC or DESC
limit	int	Results per page (default varies)
offset	int	Pagination offset

Response

{
  "data": [
    {
      "projectName": "My Store",
      "referenceId": "ref_abc123",
      "txHash": "0xabc123...",
      "fromAddress": "0xsender...",
      "toAddress": "0xreceiver...",
      "paymentStatus": "Filled",
      "currency": "USDC",
      "network": "base",
      "amountInUSD": 49.99,
      "amount": 49.99,
      "filledAmountInUSD": 49.99,
      "filledAmount": 49.99,
      "customerId": "user_456",
      "email": "[e-mail]",
      "webhookStatus": "Success",
      "createdBy": "user",
      "createdAt": "2026-03-20T14:30:00Z",
      "trxTimestamp": "2026-03-20T14:32:15Z"
    }
  ],
  "totalCount": 1450
}

Permission required: read_payment_request

Common Recipes

Find payment by tx hash:

{"query": "0xabc123def456..."}

Find payment by customer email:

{"query": "[e-mail]"}

All completed payments today:

{
  "paymentStatus": ["Filled"],
  "dateFrom": "2026-03-21T00:00:00Z",
  "dateTo": "2026-03-21T23:59:59Z"
}

All USDC payments on Base this week:

{
  "currency": ["USDC"],
  "network": ["base"],
  "dateFrom": "2026-03-15T00:00:00Z",
  "dateTo": "2026-03-21T23:59:59Z"
}

---

Get Daily Volume (via Payment Search)

To calculate daily volume with breakdowns, use Payment Search with date filters and aggregate the results.

Step 1: Fetch today's completed payments

POST {BASE_URL}/api/v1/external-platform/{PROJECT_ID}/payment/search
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "paymentStatus": ["Filled", "Partial filled"],
  "dateFrom": "2026-03-21T00:00:00Z",
  "dateTo": "2026-03-21T23:59:59Z",
  "limit": 500,
  "offset": 0
}

Step 2: Aggregate client-side

Group the returned data[] array by network and currency to build the breakdown:

Total today: $12,450.00

By Network:
  ethereum  $5,200.00  (3 payments)
  base      $4,100.00  (7 payments)
  bitcoin   $2,150.00  (1 payment)
  tron      $1,000.00  (2 payments)

By Currency:
  USDC      $8,300.00
  BTC       $2,150.00
  USDT      $1,000.00
  ETH       $1,000.00

Tip: For "yesterday vs today" comparison, run two searches with different date ranges and compare totals.

---

Unswept Balances

Check how much crypto is sitting in deposit addresses that hasn't been swept to your cold wallet yet.

GET {BASE_URL}/api/v1/addresses/balance
Authorization: Bearer <ACCESS_TOKEN>

Response:

[
  {
    "blockchainCode": "ETH",
    "blockchainFamily": "ethereum",
    "blockchainID": 1,
    "currencyCode": "USDC",
    "currencyID": 2,
    "amount": "1523.45",
    "count": 12
  },
  {
    "blockchainCode": "BASE",
    "blockchainFamily": "ethereum",
    "blockchainID": 5,
    "currencyCode": "USDC",
    "currencyID": 2,
    "amount": "890.00",
    "count": 8
  },
  {
    "blockchainCode": "BTC",
    "blockchainFamily": "bitcoin",
    "blockchainID": 3,
    "currencyCode": "BTC",
    "currencyID": 1,
    "amount": "0.05200000",
    "count": 3
  }
]

Each entry = one blockchain + currency combination. count = number of deposit addresses holding funds. amount = total unswept balance in that currency.

Permission required: read_addresses_summary

---

Sweep Transaction History

View past sweep operations — how much was swept, fees charged, and when.

List All Sweeps

GET {BASE_URL}/api/v1/sweep-transactions?limit=20&offset=0
Authorization: Bearer <ACCESS_TOKEN>

Response:

{
  "sweepTransactionInfo": [
    {
      "numberOfUTXOs": 5,
      "total": "0.15000000",
      "payramFees": "0.00150000",
      "feePercentage": "1.00"
    }
  ]
}

Get Sweep Details

GET {BASE_URL}/api/v1/sweep-transactions/{sweepId}
Authorization: Bearer <ACCESS_TOKEN>

Response:

{
  "payramFeeAddress": "0xfee...",
  "blockchainType": "ETH",
  "sweepTransactions": [...]
}

Permission required: read_sweep_transaction

---

On-Ramp Metrics

If you use on-ramp integrations (fiat-to-crypto), get aggregate metrics:

Metrics Summary

GET {BASE_URL}/api/v1/onramper-payments/metrics?startDate=2026-03-01&endDate=2026-03-21
Authorization: Bearer <ACCESS_TOKEN>

Response:

{
  "totalOnrampValue": "45230.50",
  "totalFeeExpense": "452.30",
  "onrampContributionPercent": "15.2",
  "uniqueOnrampUsers": 89
}

Permission required: read_onramper_payments_metrics

On-Ramp Payment List

GET {BASE_URL}/api/v1/onramper-payments?startDate=2026-03-20&endDate=2026-03-21&limit=50&offset=0
Authorization: Bearer <ACCESS_TOKEN>

Query Parameters:

Param	Type	Description
startDate	string	ISO date
endDate	string	ISO date
externalPlatformIDs	number[]	Platform filter
blockchainCodes	string[]	Blockchain filter
currencyCodes	string[]	Currency filter
limit	number	Pagination limit
offset	number	Pagination offset
sortBy	string	Sort field
order	string	ASC or DESC

Response:

{
  "data": [
    {
      "dateOfPayment": "2026-03-20",
      "project": "My Store",
      "referenceID": "ref_onramp_123",
      "userEmail": "[e-mail]",
      "token": "USDC",
      "network": "base",
      "amountInUSD": "100.00",
      "amountToken": "100.00",
      "txnHash": "0xdef456...",
      "blockNumber": 12345678
    }
  ],
  "totalCount": 89,
  "limit": 50,
  "offset": 0
}

Permission required: read_onramper_payments

---

Analytics Charts

The dashboard uses a config-driven analytics system. First discover available chart groups, then fetch data.

Step 1: Discover Available Groups

GET {BASE_URL}/api/v1/external-platform/{PROJECT_ID}/analytics/groups
Authorization: Bearer <ACCESS_TOKEN>

Returns the list of analytics groups and their graphs (charts). Each group has an ID and contains graphs with IDs.

Step 2: Fetch Graph Data

POST {BASE_URL}/api/v1/external-platform/{PROJECT_ID}/analytics/groups/{groupId}/graph/{graphId}/data
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "date_filter": "last_30_days"
}

Common date filters: today, yesterday, last_7_days, last_14_days, last_30_days, this_month, last_month

For custom ranges:

{
  "date_filter": "custom",
  "custom_start_date": "2026-03-01T00:00:00Z",
  "custom_end_date": "2026-03-21T23:59:59Z"
}

Permission required: read_analytics

---

Deposits

List Deposits

GET {BASE_URL}/api/v1/deposits?limit=20&offset=0
Authorization: Bearer <ACCESS_TOKEN>

Permission required: read_deposits

Missed Deposits

GET {BASE_URL}/api/v1/missed-deposit
Authorization: Bearer <ACCESS_TOKEN>

Returns deposits that were detected but couldn't be matched to a payment request.

---

Referral Analytics

If you have referral campaigns configured:

Endpoint	Method	Description
/api/v1/external-platform/{pid}/referral/campaigns	GET	List campaigns
/api/v1/external-platform/{pid}/referral/campaigns/{cid}/rewards/total	GET	Total rewards for campaign
/api/v1/external-platform/{pid}/referral/referrers/{refId}	GET	Referrer profile
/api/v1/external-platform/{pid}/referral/referrers/{refId}/referee/total	GET	Count of referred users
/api/v1/external-platform/{pid}/referral/referrers/{refId}/rewards/total	GET	Total rewards earned
/api/v1/external-platform/{pid}/referral/referrers/{refId}/rewards	GET	Reward event history
/api/v1/external-platform/{pid}/referral/referrers/{refId}/withdrawals	GET	Withdrawal history
/api/v1/external-platform/{pid}/referral/payouts	GET	Payout batches

Permission required: read_referral

---

Recommended Workflow for Agents

When a user asks about their PayRam data, follow this sequence:

1. Ensure you have auth — check for BASE_URL and ACCESS_TOKEN (or REFRESH_TOKEN). If you have a refresh token but no access token, call POST /api/v1/refresh first. See payram-auth.

2. Discover PROJECT_ID — call GET /api/v1/external-platform/details and use the id from the first platform. Do not ask the user for this.

3. Identify the question type — use the Common Questions table above.

4. Make the API call — use curl, fetch, or any HTTP client with Authorization: Bearer <token>.

5. Handle 401 — if you get a 401, refresh the token using POST /api/v1/refresh and retry.

6. Format the response — present data in a readable format (tables, summaries, breakdowns).

Example Agent Conversation

User: "How much did I receive yesterday on Base?"

Agent:

1. Calls Payment Search with dateFrom = yesterday 00:00, dateTo = yesterday 23:59, network = ["base"], paymentStatus = ["Filled"]
2. Sums amountInUSD from all results
3. Groups by currency for breakdown
4. Responds: "You received $4,100.00 on Base yesterday — $3,500 in USDC and $600 in ETH across 7 payments."

---

Related Skills

Skill	Purpose
payram-auth	Get your Bearer token (login, refresh, browser extraction)
payram-setup	Deploy and configure a PayRam server
payram-payment-integration	Integrate payments into your app
payram-webhook-integration	Receive payment events in real time