USDC Payment History — GET /api/payments/history

The payment history endpoint returns a paginated list of all payment sessions on the FlareHQ ledger, ordered from most recent to oldest. It is intended for building dashboards, generating settlement reports, and reconciling USDC volumes. Unlike the verify endpoint which targets a single payment by reference, this endpoint returns aggregate metrics alongside the transaction list, making it easy to calculate total processed volume and outstanding balances in a single request.

Endpoint

GET https://flarehq.xyz/api/payments/history

Request

Headers

Header	Value
`Authorization`	`Bearer fhq_sec_...` — required (merchant API key)

Query Parameters

number

default:"20"

Maximum number of payment records to return in a single response. Accepted range: 1 – 100. Use in combination with offset to paginate through large result sets.

number

default:"0"

Number of records to skip before returning results. Use this with limit for cursor-style pagination. For example, to fetch the second page of 20 results, set offset=20&limit=20.

string

Filter results to payments in a specific state. Accepted values:

Value	Description
`PENDING`	Session created but payer has not completed checkout
`SUCCESS`	Payment confirmed and settled on-chain
`FAILED`	Payment attempt did not succeed
`EXPIRED`	Session passed its 120-minute window without settlement

Omit this parameter to return payments in all states.

string

ISO 8601 date-time string. Only payments created at or after this timestamp are returned. Example: 2025-01-01T00:00:00Z.

string

ISO 8601 date-time string. Only payments created before or at this timestamp are returned. Example: 2025-01-31T23:59:59Z. Use together with from to define a reporting window.

Response

boolean

true when the request completed without error.

object

Aggregate statistics computed across the returned ledger snapshot.

Show metrics fields

number

Total count of payment records in the current response slice.

number

Sum of all payment amounts in the current response, in USDC (4 decimal precision). Example: 1250.5000.

number

Estimated gas cost savings in USD attributable to FlareHQ’s batch-settlement architecture, calculated at $0.05 per settled transaction.

string

Always "USDC".

string

Settlement chain identifier, e.g. "Arc-L1".

array

Ordered list of payment records (newest first). Each element represents a single payment session.

Show transaction object fields

string

Unique identifier for this payment record.

string

Unique arc_ref_... payment reference. Use this to call GET /api/payments/verify/ for the full detail record.

number

Payment amount in USDC.

string

Currency code, e.g. "USDC".

string

Settlement chain, e.g. "Arc Testnet v1.0".

string

Email address or wallet address of the payer. Agent-originated payments show "autonomous-agent@bot.network".

string

Merchant display name associated with the payment.

string

Settlement state: PENDING, SUCCESS, FAILED, or EXPIRED.

string

ISO 8601 timestamp of when the payment record was created on the ledger.

number

Total number of matching records across all pages (accounting for any status, from, or to filters). Use this value with limit and offset to calculate total page count.

boolean

true if there are additional records beyond the current page — i.e. offset + limit < total. Use this flag to drive “Load more” or infinite-scroll pagination in your UI.

Examples

curl "https://flarehq.xyz/api/payments/history" \
  -H "Authorization: Bearer fhq_sec_test_..."

curl "https://flarehq.xyz/api/payments/history?limit=50&offset=50&status=SUCCESS&from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z" \
  -H "Authorization: Bearer fhq_sec_test_..."

async function getPaymentHistory({ page = 0, pageSize = 20, status } = {}) {
  const params = new URLSearchParams({
    limit: String(pageSize),
    offset: String(page * pageSize),
    ...(status && { status }),
  });

  const res = await fetch(
    `https://flarehq.xyz/api/payments/history?${params}`,
    {
      headers: { Authorization: 'Bearer fhq_sec_test_...' },
    }
  );
  return res.json();
}

const { success, transactions, metrics, hasMore } =
  await getPaymentHistory({ status: 'SUCCESS' });

console.log(`Volume processed: ${metrics.totalVolumeProcessed} USDC`);
console.log(`Showing ${transactions.length} payments. More pages: ${hasMore}`);

import requests

headers = {"Authorization": "Bearer fhq_sec_test_..."}
params = {
    "limit": 50,
    "offset": 0,
    "status": "SUCCESS",
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-31T23:59:59Z",
}

resp = requests.get(
    "https://flarehq.xyz/api/payments/history",
    headers=headers,
    params=params,
)
data = resp.json()

for tx in data["transactions"]:
    print(tx["reference"], tx["amount"], tx["status"])

Response — Success

{
  "success": true,
  "metrics": {
    "totalTransactions": 3,
    "totalVolumeProcessed": 86.5,
    "estimatedGasSavedUSD": 0.15,
    "settlementCurrency": "USDC",
    "primaryChain": "Arc-L1"
  },
  "transactions": [
    {
      "id": "cm3x9f2a0000108l47bqg9d1e",
      "reference": "arc_ref_k7x2m9lp4d8f1q2z",
      "amount": 25.0,
      "currency": "USDC",
      "chain": "Arc Testnet v1.0",
      "senderEmail": "customer@example.com",
      "merchant": "Acme Store",
      "status": "SUCCESS",
      "timestamp": "2025-01-15T10:35:42.000Z"
    },
    {
      "id": "cm3x8e1b0000208l37apf8c0d",
      "reference": "arc_ref_m3n8p2qr5s1t6u7v",
      "amount": 50.0,
      "currency": "USDC",
      "chain": "Arc Testnet v1.0",
      "senderEmail": "buyer@example.com",
      "merchant": "Acme Store",
      "status": "SUCCESS",
      "timestamp": "2025-01-14T16:12:05.000Z"
    },
    {
      "id": "cm3x7d0c0000308l27aoe7b9c",
      "reference": "arc_ref_b9c4d5ef6g7h8i9j",
      "amount": 11.5,
      "currency": "USDC",
      "chain": "Arc Testnet v1.0",
      "senderEmail": "pending@checkout",
      "merchant": "Acme Store",
      "status": "EXPIRED",
      "timestamp": "2025-01-13T09:00:00.000Z"
    }
  ],
  "total": 3,
  "hasMore": false
}

Error Response

{
  "success": false,
  "error": "Internal Server Error"
}

Notes

The history endpoint fetches up to the latest 50 records in a single pass when no limit is specified. Pass an explicit limit and offset to implement paginated views. Use hasMore and total to drive pagination UI controls.

Combine from and to filters with status=SUCCESS to generate accurate settlement reports for a given accounting period. The metrics.totalVolumeProcessed field in the response is pre-computed for you, so you do not need to sum the amount field of each transaction manually.

PENDING sessions that have passed their 120-minute expiry window may still appear as PENDING in the raw results. If you need accurate EXPIRED counts, compare each PENDING record’s timestamp against the current time plus 120 minutes and treat those as expired on your end.

Overview

Payments

Escrow

Streaming

x402

Agents

USDC Payment History — GET /api/payments/history

Endpoint

Request

Headers

Query Parameters

Response

Examples

Response — Success

Error Response

Notes

​Endpoint

​Request

​Headers

​Query Parameters

​Response

​Examples

​Response — Success

​Error Response

​Notes

Endpoint

Request

Headers

Query Parameters

Response

Examples

Response — Success

Error Response

Notes