Add from wallet

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

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.

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

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"
}'

Loyfin burns the signed tokenized amount from the customer's selected bucket. The issuer only needs to publish the signed redemption; Loyfin's official relayer or an independent relayer can submit it. Your brand system should credit, restore, or fulfill the offchain result only after the redemption is completed.

• Customer has insufficient balance in the selected expiry bucket.
• The bucket is expired.
• The action deadline has passed.
• The signature, nonce, chain, or verifying contract does not match.

Add from wallet usually starts inside the brand app: the customer is logged in, connects a wallet, proves ownership with a brand-scoped wallet signature, chooses tokenized value to add back, and the app calls your brand API. Your backend verifies the wallet/account mapping, creates an internal redemption row, signs the redemption, and stores it through Loyfin or submits it onchain directly. The brand database remains the system of record for customer balance, support, and account state.

• Use operationHash to connect the signed redemption, indexed Loyfin activity, and your internal redemption row.
• A pasted address is not enough for Add from wallet. The customer should prove wallet ownership before the brand credits an offchain account.
• After POST /redemptions returns successfully, keep the brand operation pending until the burn is confirmed.
• On confirmation, apply the brand-side result: credit or restore the offchain points/value, update the account record, and show the customer the completed add-from-wallet receipt.
• The helper API is the default path for performance and efficiency. Confirmation can come from account-level webhooks, polling GET /operations or GET /redemptions, or direct onchain event reads. Brands can also submit the redeem transaction themselves instead of relying on the helper API.

Loyfin indexes completed burns in redemptions. For a wallet-linked account, a brand can query completed rows by wallet and token address, then process only receipts that are not already marked completed in the brand database.

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

• Store a processed key such as chainId + txHash + logIndex, plus operationHash when available.
• Verify the receipt belongs to the brand's expected issuer/token before adding offchain value.
• Sum only unprocessed rows for the wallet mapped to the logged-in brand account, then mark them processed in the same brand-side transaction that credits the points.