> For the complete documentation index, see [llms.txt](https://docs.kima.network/kima-network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kima.network/kima-network/the-kima-sdk/upgrading/v1.5.md).

# 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:

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

## Kima Transaction Widget

Install the latest version of the [React Widget](https://www.npmjs.com/package/@kimafinance/kima-transaction-widget).

```bash
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](https://github.com/kima-finance/kima-transaction-backend/tree/main) repo and and pull the latest version.

```bash
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):

```typescript
// 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.