Docs/Public API/API overview

API overview

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

API URL#

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

API URLsplaintext

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

Upcoming release: the @loyfin/server TypeScript SDK is implemented but not yet published to npm. It will wrap session APIs, produce EIP-712 typed data for your own signer, and verify Loyfin webhook signatures without accepting private keys. Use the JavaScript fetch or curl examples for production integrations today.

SDK — Upcoming releasebash

# Upcoming release — not yet published to npm
# Use the JavaScript fetch or curl examples today.
# npm install @loyfin/server

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#

requires_holder_signatureAwaiting walletpendingCreatedsubmittedSubmittedminedCompletedrejectedRejectedcancelledCancelledexpiredExpired

HTTP endpoints#

POST/issuances

Create a brand-signed issuance checkout session.

Auth: API keyReturns: { ok, duplicate, issuance }

GET/issuances

List completed issuance events.

Auth: publicQuery: cursor, limit, issuer, to, loyaltyId, token, operationHashReturns: Page<Issuance>

GET/issuances/:id

Read issuance checkout state. A claim token is required for claimable sessions.

Auth: publicQuery: claimReturns: { issuance: IssuanceSession }

PATCH/issuances/:id

Attach the recipient wallet signature.

Auth: Opaque claim tokenReturns: { ok, issuance }

POST/redemptions

Create a brand-signed redemption checkout session.

Auth: API keyReturns: { ok, duplicate, redemption }

GET/redemptions

List completed burn events.

Auth: publicQuery: cursor, limit, issuer, from, loyaltyId, token, operationHashReturns: Page<Redemption>

GET/redemptions/:id

Read redemption checkout state. A claim token is required for claimable sessions.

Auth: publicQuery: claimReturns: { redemption: RedemptionSession }

PATCH/redemptions/:id

Attach the holder wallet signature.

Auth: Opaque claim tokenReturns: { ok, redemption }

GET/operations

List signed issuance/redemption actions.

Auth: publicQuery: cursor, limit, kind, status, issuer, loyaltyId, operationHashReturns: Page<SignedOperation>

GET/operations/:id

Read one signed operation.

Auth: publicReturns: { operation: SignedOperation }

GET/tokens

List indexed loyalty programs.

Auth: publicQuery: cursor, limit, chainId, issuer, loyaltyId, qReturns: Page<LoyaltyToken>

GET/tokens/:id

Read one indexed loyalty program.

Auth: publicReturns: { token: LoyaltyToken }

GET/issuers

List issuer-level aggregates.

Auth: publicQuery: cursor, limit, chainId, qReturns: Page<Issuer>

GET/issuers/:address

Read one issuer aggregate.

Auth: publicQuery: chainIdReturns: { issuer: Issuer }

GET/transfers

List completed transfer events.

Auth: publicQuery: cursor, limit, from, to, token, issuerReturns: Page<Transfer>

GET/balances/:address

List program-level balances for a wallet.

Auth: publicQuery: cursor, limit, chainId, token, tokens, issuerReturns: Page<ProgramBalance>

GET/balances/:address/batches

List expiry-bucket balances for a wallet.

Auth: publicQuery: cursor, limit, chainId, token, tokens, issuerReturns: Page<BatchBalance>

POST/auth/register, /auth/login

Create or authenticate a Loyfin account.

Auth: publicReturns: Account/session response

GET/PATCH/users/me, /users/me/settings

Read or update the authenticated account.

Auth: Bearer token or session cookieReturns: Account response

GET/POST/users/me/api-key, /users/me/api-key/rotate

Inspect or rotate the account API key.

Auth: Bearer token or session cookieReturns: API-key metadata; new secret shown once

GET/POST/PATCH/DELETE/users/me/webhooks/*

Manage up to five account webhook endpoints, rotate secrets, and inspect deliveries.

Auth: Bearer token or session cookieReturns: Webhook settings and deliveries

GET/openapi.json

OpenAPI 3.1 import document.

Auth: publicReturns: OpenAPI

GET/status

Service state, environment, database flag, webhook metadata.

Auth: publicReturns: { ok, service, version, environment, ... }

GET/health

Basic uptime check.

Auth: publicReturns: { ok, service, version }