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, the same origin as the dashboard (e.g., https://pay.example.com; no :8080/: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

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

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": "customer@example.com",
      "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": "customer@example.com" }

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, 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"
    }
  ]
}

Get Sweep Details

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

Response:

{
  "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:

Response:

{
  "data": [
    {
      "dateOfPayment": "2026-03-20",
      "project": "My Store",
      "referenceID": "ref_onramp_123",
      "userEmail": "buyer@example.com",
      "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:

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