Docs/API reference/Redemptions API

Redemptions API

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

POST /redemptions#

Create a redemption session with an API key or signed-in issuer session.

Request bodyjson
{
  "redemption": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "250",
    "expiresAt": "0",
    "deadline": "1790965800",
    "nonce": "0x7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab",
  "from": "0x2222222222222222222222222222222222222222"
}
JavaScript fetchjavascript
// Run on your backend. Sign the redemption as shown in Signing.
// verifiedWallet must be proved and linked to the account receiving points.
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,
    from: verifiedWallet
  })
});

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

const { redemption: session, duplicate } = await response.json();
Responsejson
{
  "ok": true,
  "duplicate": false,
  "redemption": {
    "id": "22222222-2222-4222-8222-222222222222",
    "operationId": "129",
    "kind": "redemption",
    "status": "requires_wallet_authorization",
    "chainId": "8453",
    "issuer": "0x1111111111111111111111111111111111111111",
    "walletAddress": "0x2222222222222222222222222222222222222222",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "250",
    "expiresAt": "0",
    "deadline": "1790965800",
    "nonce": "0x7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b",
    "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, chainId, issuer, from, loyaltyId, token, and operationHash.

Objects#

POST /redemptions accepts a Loyfin API key for server integrations or the Privy access token of a signed-in issuer. When you supply redemption.issuer, include its valid EIP-712 signature. An API key with signing enabled can instead omit both fields to use the assigned wallet. If customer wallet authorization 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.