Quickstart

This page takes you from install to a first goal and a first pay-and-save. The SDK works on Stellar testnet only.

Install

npm install @loktin/sdk@next @stellar/stellar-sdk

@stellar/stellar-sdk is a peer dependency. The SDK needs version 17.2.1 or a later 17.x.

Create the instance

Create one SDK instance for testnet with the user's address and a signer. The signer's signTransaction comes from the user's wallet. The SDK never sees a secret key.

import { createLoktin } from '@loktin/sdk';

const loktin = createLoktin({
  network: 'testnet',
  publicKey: userAddress,
  signer: {
    signTransaction: (xdr, opts) => wallet.signTransaction(xdr, opts),
  },
});

Here userAddress and wallet come from your app. Every write acts for publicKey. See createLoktin.

Create the modules

Each module works for one integrator, which is your app's address, and takes your integrator fee in basis points.

import { SpendSave } from '@loktin/sdk/spend-save';
import { TargetSavings } from '@loktin/sdk/target-savings';

const options = { integrator: integratorAddress, integratorFeeBps: 50 };
const targetSavings = new TargetSavings(loktin, options);
const spendSave = new SpendSave(loktin, options);

Here integratorAddress comes from your app.

Create a first goal

createGoal creates a goal and gives you its id. Amounts are bigint base units. USDC has 7 decimals, and toBaseUnits converts from a decimal string.

import { toBaseUnits } from '@loktin/sdk';

const goal = await targetSavings.createGoal({
  target: toBaseUnits('500'),
  deadline: new Date('2027-06-30T00:00:00Z'),
  cadenceSeconds: 7 * 24 * 60 * 60,
  depositSize: toBaseUnits('20'),
  rule: { kind: 'penalty', bps: 500 },
});
console.log('New goal id:', goal.result);

By default, the goal also approves an allowance for its scheduled deposits. See the Target Savings guide.

Enrol and pay

enroll sets how much of each spend is saved. payAndSave pays an address and saves the skim in the same transaction.

import { fromBaseUnits } from '@loktin/sdk';

await spendSave.enroll({
  skim: { percentBps: 500, roundUpUnit: toBaseUnits('1') },
  monthlyCap: toBaseUnits('100'),
  destination: { kind: 'goal', goalId: goal.result },
  withdrawalDay: 15,
});

const paid = await spendSave.payAndSave(shopAddress, toBaseUnits('12.50'));
const saved = paid.result.toBalance + paid.result.toGoal;
console.log('Saved', fromBaseUnits(saved), 'USDC');

Here shopAddress comes from your app. See the Spend & Save guide.