Add to wallet

{
  "issuance": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "metadata": {
      "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
      "name": "Bloom Coffee Rewards",
      "symbol": "BLOOM",
      "media": "ipfs://bafy.../bloom.png",
      "description": "Rewards for Bloom Coffee customers.",
      "contractURI": "",
      "tokenURI": ""
    },
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}

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

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

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

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

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

curl https://api.loyfin.com/issuances \
  -X POST \
  -H "content-type: application/json" \
  -H "x-loyfin-api-key: $LOYFIN_API_KEY" \
  -d '{
  "issuance": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "metadata": {
      "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
      "name": "Bloom Coffee Rewards",
      "symbol": "BLOOM",
      "media": "ipfs://bafy.../bloom.png",
      "description": "Rewards for Bloom Coffee customers.",
      "contractURI": "",
      "tokenURI": ""
    },
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}'

Store the signed tokenization issuance and show it as Created. The issuer does not need to submit the transaction: Loyfin's official relayer can relay it, or an independent relayer can submit first and earn the relayer fee. When mined, the indexer writes a completed Issuance event object.

• Wrong chainId or verifyingContract makes the signature invalid onchain.
• Expired buckets cannot be issued, and actions cannot execute after their deadline.
• A reused issuer nonce is treated as duplicate or rejected before balances change.

Most loyalty points still live in the brand's database. A common integration is an Add to wallet button inside the brand app. When the customer clicks it, the app calls your brand API; your backend checks auth, checks the spendable points balance, creates an internal conversion row, reserves or deducts the selected offchain points, and uses that row to build the signed issuance.

• Use operationHash to connect the Loyfin action with your internal database row. Use a secret-keyed HMAC or a stored random bytes32 value; do not publish a guessable raw-ID hash.
• Reserve or deduct the customer's spendable offchain points before publishing the signed issuance, so two fast requests cannot tokenize the same balance twice.
• Keep the row pending until confirmation. Loyfin sends account-level webhooks for completed issuance receipts; teams can also poll GET /operations/:id or GET /issuances, or read onchain events directly.
• The public API is the default path for performance and efficiency. Brands can also submit the issue transaction themselves or run their own relayer for a fully self-custodial issuance path.

Loyfin prevents replay of the same issuer nonce, but it cannot know whether two different nonces both came from the same offchain points. The brand backend should use a row lock, serializable transaction, or atomic update that succeeds only when the customer has enough spendable balance.

• Create one internal operation row with a stable ID, operationHash, nonce, wallet address, amount, and status.
• Retry transient Loyfin API failures with the same signed payload instead of creating a fresh nonce for the same offchain deduction.
• If the signed operation expires or is rejected, release the reservation or move it to manual review based on your support policy.