Docs/Public API/API overview

API overview

The partner-facing HTTP surface for storing signed actions and reading public loyalty activity.

Base URL#

Examples use production-style URLs. Local development defaults to port 8788.

Base URLsplaintext
Production: https://api.loyfin.com
Local:      http://127.0.0.1:8788

Pagination#

List endpoints use cursor pagination. Send limit from 1 to 100 and pass page.nextCursor as cursor for the next page.

Page responsejson
{
  "items": [],
  "page": {
    "limit": 25,
    "nextCursor": null,
    "hasMore": false
  }
}

Status values#

pendingCreatedsubmittedSubmittedminedCompletedrejectedRejectedcancelledCancelled

Public endpoints#

POST/issuances

Store a brand-signed issuance.

Returns: { ok, duplicate, operation }
GET/issuances

List completed issuance events.

Query: cursor, limit, issuer, to, loyaltyId, token, operationHashReturns: Page<Issuance>
POST/redemptions

Store a brand-signed redemption.

Returns: { ok, duplicate, operation }
GET/redemptions

List completed redemption events.

Query: cursor, limit, issuer, from, loyaltyId, token, operationHashReturns: Page<Redemption>
GET/operations

List signed issuance/redemption actions.

Query: cursor, limit, kind, status, issuer, loyaltyId, operationHashReturns: Page<SignedOperation>
GET/operations/:id

Read one signed operation.

Returns: { operation: SignedOperation }
GET/tokens

List indexed loyalty programs.

Query: cursor, limit, chainId, issuer, loyaltyId, qReturns: Page<LoyaltyToken>
GET/tokens/:id

Read one indexed loyalty program.

Returns: { token: LoyaltyToken }
GET/issuers

List issuer-level aggregates.

Query: cursor, limit, chainId, qReturns: Page<Issuer>
GET/issuers/:address

Read one issuer aggregate.

Query: chainIdReturns: { issuer: Issuer }
GET/transfers

List completed transfer events.

Query: cursor, limit, from, to, token, issuerReturns: Page<Transfer>
GET/openapi.json

OpenAPI 3.1 import document.

Returns: OpenAPI
GET/status

Service state, environment, database flag, webhook metadata.

Returns: { ok, service, version, environment, ... }
GET/health

Basic uptime check.

Returns: { ok, service, version }