Stellar onboarding SDK

Send the asset now.
Activate the trustline later.

Trustline Onboarder gets a user a usable balance of any Stellar asset — with no XLM, no existing trustline, and no blockchain literacy. One SDK composes claimable balances, sponsored reserves, and SEP-8 approval into a single signature.

Read the docs Try the live demo

$pnpm add @trustline-onboarder/sdk

onboard.ts@trustline-onboarder/sdk

import { TrustlineOnboarder } from "@trustline-onboarder/sdk";

const onboarder = new TrustlineOnboarder({ network: "testnet", sponsor });

// Read the issuer's stellar.toml + the holder's state
const state = await onboarder.detect({
  account,
  asset: { code: "EURCV", issuer: "GBAD…7QFD" },
});

// One call builds the right transaction (mechanism C)
const { mode, url } = await onboarder.startOnboarding({
  account,
  asset: { code: "EURCV", issuer: "GBAD…7QFD" },
  returnUrl: "https://app.example.com/wallet",
});

mode: "claimable" · 1 signature · reserve sponsored

ComposesCAP-23 claimable balanceCAP-33 sponsored reservesSEP-8 approvalSEP-10 authSEP-12 KYC

Three mechanisms · one API

Pick how the balance lands.

The SDK exposes one call. Choose the mechanism per asset — or let discovery pick it from the issuer's stellar.toml.

CMechanism CDefault

Send now, activate later.

The asset is sent as a claimable balance and waits on-ledger until the recipient signs once. No trustline or XLM is required up front — the reserve is sponsored.

CAP-23CAP-33

onboarder.startOnboarding({ asset, mechanism: "claimable" })

On-ledger flow

Issuer

sends + sponsors

Claimable balance

waits on-ledger

Recipient

claims with 1 sig

Settles in one signature. The reserve is sponsored, so the user never needs XLM.

The flow

Detect, onboard, settle.

Four steps from a cold account to a usable balance. The SDK orchestrates the ledger operations; the user only ever signs once.

Detect

Read the issuer's stellar.toml and the holder's on-chain state to learn which mechanisms apply.

onboarder.detect({ … })

Onboard

One call builds the right transaction — claimable balance, authorize, or intermediate — wrapped in a sponsored-reserve sandwich.

onboarder.startOnboarding({ … })

Sign

The user signs once in their wallet. No XLM, no manual trustline, no second prompt.

wallet.sign(xdr)

Settle

The trustline is created and authorized; the balance lands and is immediately usable.

verifyActivation()

The SDK

Three lines to a usable balance.

Plain TypeScript or a drop-in React component. The same primitives power the issuer's approval server.

onboard.ts

import { TrustlineOnboarder } from "@trustline-onboarder/sdk";

const onboarder = new TrustlineOnboarder({ network: "testnet", sponsor });

const state = await onboarder.detect({
  account,
  asset: { code: "EURCV", issuer: "GBAD…7QFD" },
});

if (!state.authorized) {
  const { mode, url } = await onboarder.startOnboarding({
    account,
    asset: { code: "EURCV", issuer: "GBAD…7QFD" },
    returnUrl: "https://app.example.com/wallet",
  });
}

For issuers

Regulated-asset controls, built in.

The approval server gives compliance teams a MiCA-ready control surface — authorize, freeze, clawback, and a full audit trail, all from one console.

MiCASEP-8SEP-12

Explore the approval console

Authorize

setTrustLineFlags

Approve a trustline after a KYC check. Wallets receive a SEP-8 success / pending / action_required result.

Freeze

AUTHORIZED_TO_MAINTAIN_LIABILITIES

Suspend a holder's ability to transfer while keeping the balance intact, pending review.

Clawback

clawback · CAP-35

Reverse a transfer on a clawback-enabled asset. Irreversible, and always recorded in the audit log.

Audit log

append-only

Every authorize, freeze, and clawback is captured as an append-only, exportable compliance record.

Send the asset now.Activate the trustline later.