Configure the SDK

Everything runs through one object: TrustlineOnboarder. Construct it once with your network and sponsor, and reuse it.

Construct the onboarder

The SDK never holds keys, and the sponsor is always bring-your-own. You pass a network and a sponsor configuration; Horizon and RPC URLs default per network but can be overridden.

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

export const onboarder = new TrustlineOnboarder({
  network: "testnet",
  sponsor: {
    account: "GSPON…SOR1",
    sign: (xdr) => sponsorSigner.sign(xdr),
  },
  // Optional — sensible per-network defaults are used otherwise.
  horizonUrl: "https://horizon-testnet.stellar.org",
});

The sponsor

The sponsor pays the trustline reserve so the user needs no XLM. It can be a key your service controls, or a callback into a KMS/HSM. Sponsorship is bounded per account and per time window, and is only granted against a real pending onboarding.

Point at an approval server

For a regulated asset, the SDK forwards the built transaction to the issuer’s approval server, which runs the compliance check and signs the authorization. You usually don’t configure this directly — the URL is discovered from the issuer’s stellar.toml — but you can override it:

const onboarder = new TrustlineOnboarder({
  network: "testnet",
  sponsor,
  approvalServer: "https://issuer.example.com/tx-approve",
});

Discovery via stellar.toml

Point the SDK at an issuer’s stellar.toml. It advertises the asset, the approval server URL, and the supported mechanisms — so a wallet can find the onboarding service from the asset alone.

[[CURRENCIES]]
code = "EURCV"
issuer = "GBAD…7QFD"
regulated = true
approval_server = "https://issuer.example.com/tx-approve"
approval_criteria = "Holders must complete KYC (SEP-12) before authorization."

[ONBOARDING]
mechanisms = ["claimable", "authorize"]
sponsor = "GSPON…SOR1"