Docs/API reference/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.

Preview the upcoming SDK

Not yet publishedbash

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

SDK preview: issuancetypescript

import { Loyfin, issuanceTypedData } from "@loyfin/server";

const loyfin = new Loyfin({ apiKey: process.env.LOYFIN_API_KEY });

const typedData = issuanceTypedData(issuance);
const signature = await issuerSigner.signTypedData(typedData);

const { issuance: session, duplicate } = await loyfin.issuances.create({
  issuance,
  signature,
  to: verifiedWallet
});

// Show session.checkoutUrl when the recipient still needs to sign.

SDK preview: redemptiontypescript

import { Loyfin, redemptionTypedData } from "@loyfin/server";

const loyfin = new Loyfin({ apiKey: process.env.LOYFIN_API_KEY });

const typedData = redemptionTypedData(redemption);
const signature = await issuerSigner.signTypedData(typedData);

const { redemption: session, duplicate } = await loyfin.redemptions.create({
  redemption,
  signature,
  from: verifiedWallet
});

// Show session.checkoutUrl when the holder still needs to sign.

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_wallet_authorizationAwaiting wallet authorizationpendingCreatedsubmittedSubmittedminedCompletedrejectedRejectedcancelledCancelledexpiredExpired

HTTP endpoints#

POST/issuances

Create a brand-signed issuance checkout session.

Auth: API key or issuer JWT/sessionReturns: { ok, duplicate, issuance }

GET/issuances

List completed issuance events.

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

GET/issuances/:id

Read issuance checkout state. A claim token is required for wallet-authorized 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 key or issuer JWT/sessionReturns: { ok, duplicate, redemption }

GET/redemptions

List completed burn events.

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

GET/redemptions/:id

Read redemption checkout state. A claim token is required for wallet-authorized 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, chainId, 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, chainId, 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/session

Create or link an issuer account and provision its user-owned issuer wallet.

Auth: Privy access tokenReturns: Account and issuer wallet

GET/users/me/issuer-wallet

Read the account’s issuer wallet.

Auth: Privy access tokenReturns: Wallet ID and address

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

Read or update the authenticated account.

Auth: Privy access tokenReturns: Account response

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

Inspect or rotate the account API key.

Auth: Privy access tokenReturns: 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: Privy access tokenReturns: 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 }