Mechanisms

A — Authorize trustline

RegulatedSEP-8CAP-18

For a user who needs to hold an asset before a withdrawal arrives. The holder creates a trustline; the issuer authorizes it after a compliance check.

The transaction

One transaction creates and (for regulated assets) authorizes the trustline. As always, the reserve is sponsored so the user needs no XLM.

beginSponsoringFutureReserves({ sponsoredId: user })   (source: sponsor)
changeTrust({ asset })                                 (source: user)
endSponsoringFutureReserves()                          (source: user)
setTrustLineFlags({ trustor: user, asset,
                    setFlags: AUTHORIZED_FLAG })        (source: issuer)

From the SDK

authorize.ts

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

The approval result

Because authorization runs through the approval server, the holder’s wallet receives a SEP-8-style result. Handle each state explicitly:

success         → approved as is; submit and settle
revised         → the server modified the transaction (e.g. inserted issuer auth); re-sign
pending         → manual review; poll or await callback
action_required → the user must complete KYC first (follow the returned url)
rejected        → not approved; show the reason

True preauthorization before the trustline exists would use a draft CAP. The builder authorizes at trustline-creation time today and exposes a flag to switch to a protocol preauthorization path later without changing the public API.