v.1.5.x

Major Features

• Bank transfers as an origin rail (e.g. SEPA → on-ramp to crypto).

• Unified “FIAT rails” handling (BANK and CC) in the submit flow.

• On-chain stable token swaps via a new /submit/swap endpoint.

• Safer, stricter “options” contract between frontend, backend and the blockchain for FIAT rails.

🚨 Breaking Changes

UPGRADING TO v1.5.x IS REQUIRED FOR ALL KIMA SDK USERS. Older payloads will fail once 1.5 validators/submit rules are enforced.

1) “FIAT rails” normalization & required IDs

• Origin rails BANK and CC are now treated as FIAT internally when we submit to Kima Chain.

• Backend normalizes:

  • originChain: 'CC' | 'BANK' → 'FIAT'

  • originAddress → empty string ('') for FIAT rails.

2) New /submit/swap endpoint + signed approval (light mode)

• Swaps are submitted through POST /submit/swap with:

• amountIn, amountOut, fee (all bigint strings),

• decimals (number),

• the same options mechanism (incl. FIAT rules above when origin is BANK/CC).

3) Options field is stringified JSON and stricter

• Backend must submit options as a JSON string. (Objects are not accepted by the API.)

• For crypto → crypto:

  • include feeId (from fee estimator),

  • include the signed user approval.

• For FIAT rails:

  • MUST include a non-empty transactionIdSeed (UUIDv4),

  • MUST include the derived transactionIdSignature,

  • MUST NOT include the crypto approval signature (it’s removed for FIAT).

  • MUST include the paymentMethod value in the options field:

    options: { paymentMethod: 'sepaEur' | 'creditCard' | 'swiftUsd' }

Kima Transaction Widget

Install the latest version of the React Widget.

npm install @kimafinance/kima-transaction-widget

Notes

• No new required props for 1.5.x specifically, but if you want to pass a custom Solana RPC, the widget provider accepts solRPC (optional).

• Existing network filters remain backend-driven (no re-introducing removed props).

Backend

Navigate to the kima-transaction-backend repo and and pull the latest version.

git pull

A) Transfers (POST /submit/transfer)

• If origin is FIAT (BANK/CC):

• Accept a fiatTransactionIdSeed in the body (or options.transactionIdSeed).

• Call your existing helper to generate FIAT options (it must preserve the seed and add transactionIdSignature).

• Ensure originChain is normalized to 'FIAT' and originAddress is empty before calling the Kima submit API.

Minimal example (server side):

// body: { ..., originChain: 'BANK', fiatTransactionIdSeed: '<uuid-v4>', options: '{"feeId":"...","paymentMethod":"sepaEur"}' }
let options = JSON.parse(req.body.options);

if (["FIAT", "CC", "BANK"].includes(req.body.originChain)) {
  const seed = req.body.fiatTransactionIdSeed || options.transactionIdSeed; // allow either field

  if (!seed) {
    return res
      .status(400)
      .json({ error: "transactionIdSeed is required for FIAT rails" });
  }

  // Your helper must RETURN both the signature AND retain the seed
  const { options: fiatOpts } = await generateFiatOptions(seed);

  // Merge in but KEEP the seed inside options too
  options = { ...options, ...fiatOpts, transactionIdSeed: seed };
  delete options.signature; // never send crypto approval signature for FIAT
}

const payload = {
  originAddress: ["CC", "BANK"].includes(req.body.originChain)
    ? ""
    : req.body.originAddress,
  originChain: ["CC", "BANK"].includes(req.body.originChain)
    ? "FIAT"
    : req.body.originChain,
  // ...rest
  options: JSON.stringify(options),
};

// submitKimaTransferTransaction(payload)

Common FIAT options keys you’ll be sending:

• feeId — required (from the fee estimator)

• paymentMethod — e.g. "sepaEur" for BANK and "creditCard" for CC

• chargeFeeAtTarget — boolean (optional)

• transactionIdSeed — required

• transactionIdSignature — required (derived from the seed server-side)

B) Swaps (POST /submit/swap)

• Uses amountIn / amountOut (bigint strings).

• FIAT rules apply when origin is BANK/CC (transactionIdSeed + signature, origin normalized to FIAT, empty address).

C) Fees (no endpoint change, but expectations do)

• As in 1.4, you must call the fee estimator before submit.

• 1.5 continues to use feeId in the subsequent submit request (transfer or swap).

D) Helper endpoints (optional)

• GET /submit/transactionId?transactionIdSeed=<uuid> — returns encoded transactionId (for CC flows). (Your FIAT helper already calls the underlying logic that also produces transactionIdSignature.)

Migration Checklist

• Upgrade widget to latest @kimafinance/kima-transaction-widget.

• Backend:

  • Ensure /submit/transfer preserves transactionIdSeed in options and adds transactionIdSignature for FIAT.

  • Normalize originChain (CC/BANK → FIAT) and blank originAddress for FIAT.

  • Remove crypto approval signature from options for FIAT.

  • Implement /submit/swap with dex, slippage, amountIn/Out.

  • Always call the fee estimator first and pass the returned feeId into options.

  • Update any client code to supply a UUIDv4 transactionIdSeed for BANK/CC flows.