Docs/Public API/Redemptions API

Redemptions API

Store signed Add from wallet actions and read completed burn events.

POST /redemptions#

Create a redemption session with a Loyfin API key.

Request bodyjson

{
  "redemption": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "250",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}

TypeScript SDK — Upcoming releasetypescript

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
});

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

JavaScript fetchjavascript

const response = await fetch("https://api.loyfin.com/redemptions", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-loyfin-api-key": process.env.LOYFIN_API_KEY
  },
  body: JSON.stringify({
    redemption,
    signature,
    signatureScheme: "dual"
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { redemption: session, duplicate } = await response.json();

curlbash

curl https://api.loyfin.com/redemptions \
  -X POST \
  -H "content-type: application/json" \
  -H "x-loyfin-api-key: $LOYFIN_API_KEY" \
  -d '{
  "redemption": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "250",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}'

Responsejson

{
  "ok": true,
  "duplicate": false,
  "redemption": {
    "id": "22222222-2222-4222-8222-222222222222",
    "operationId": "129",
    "kind": "redemption",
    "status": "requires_holder_signature",
    "chainId": "8453",
    "issuer": "0x1111111111111111111111111111111111111111",
    "from": null,
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "250",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "checkoutUrl": "https://loyfin.com/redemptions/22222222-2222-4222-8222-222222222222?claim=..."
  }
}

GET /redemptions#

List completed burn events for Add from wallet reconciliation.

List completed redemptionsbash

curl "https://api.loyfin.com/redemptions?issuer=0x1111111111111111111111111111111111111111&limit=25"

Find burns by wallet and tokenbash

curl "https://api.loyfin.com/redemptions?from=0x2222222222222222222222222222222222222222&token=0x4444444444444444444444444444444444444444&chainId=8453&limit=100"

Filters: cursor, limit, issuer, from, loyaltyId, token, and operationHash.

Objects#

POST /redemptions requires a Loyfin API key and returns a redemption session. If the holder signature is missing, the response includes a checkout URL that carries an opaque claim token. The UUID alone is not a bearer secret; the query-string claim token is. Keep the complete URL out of logs, analytics, support tickets, and referrer data. GET /redemptions returns completed Redemption event objects.