Introduction

Trustline Onboarder gets a user a usable balance of a Stellar asset without them needing XLM, an existing trustline, or any blockchain literacy. It is a reference implementation — libraries, an issuer-side approval server, and an activation UI — for “send now, activate later” onboarding.

The problem

On Stellar, an account must hold a trustline for an asset before it can receive that asset, and creating a trustline requires a small XLM reserve. For a regulated asset, the issuer must also authorize the trustline after a compliance check. That is three things a first-time user almost never has: XLM, a trustline, and a completed KYC.

The onboarder removes all three from the user’s path. The reserve is sponsored, the right transaction is built for you, and the issuer authorization is requested automatically when the asset is regulated.

How it works

The SDK orchestrates four steps. 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.
• Onboard — one call builds the right transaction, wrapped in a sponsored-reserve sandwich so the user needs no XLM.
• Sign — the user signs once in their wallet. No manual trustline, no second prompt.
• Settle — the trustline is created and (for regulated assets) authorized; the balance lands and is immediately usable.

The three mechanisms

Every onboarding resolves to one of three mechanisms. The SDK exposes a single call; discovery can pick the mechanism from the issuer’s stellar.toml, or you can choose it explicitly.

• C — Claimable balance (default). The asset is sent and waits on-ledger until the recipient claims it with one signature. Works today, no protocol change.
• A — Authorize trustline. The holder creates a trustline; the issuer authorizes it after a compliance check. The path for regulated assets that need a hold before receipt.
• B — Intermediate account. A sponsored intermediate account holds the asset and hands it off. Advanced, behind the same interface.

What’s in the box

The reference implementation is a pnpm + Turborepo monorepo with four libraries and three deployable surfaces.

• @trustline-onboarder/core — framework-free transaction builders for mechanisms A, B, and C.
• @trustline-onboarder/sdk — the adopter-facing surface for wallets and brokers.
• @trustline-onboarder/discovery — stellar.toml generation and well-known endpoint helpers.
• @trustline-onboarder/signer — issuer signing adapters (local key, KMS, HSM) behind one interface.

Next

Install the SDK and build your first zero-touch onboarding.