SEP-0058: External Account API — Provisioned Receiving Instruments for Stellar Wallets

[antb123]

Problem

SEP-6 models deposits as transactions. Each GET /deposit creates a one-time flow with its own
lifecycle. But many providers need to provision reusable receiving instruments — crypto deposit
addresses, virtual bank accounts, IBANs, CLABEs — that persist across multiple deposits and
aren't tied to a single transaction.

Some anchors work around this by returning the same address across multiple SEP-6 transactions
(#1341), but this overloads the transaction model with account semantics and creates
reconciliation ambiguity.

Proposal

SEP-58 introduces a dedicated External Account API — a single resource (account) with a clean
lifecycle (pending → active → deactivated) for provisioning inbound receiving instruments
bound to an authenticated Stellar wallet.

The API is minimal:

• GET /info — discover supported offerings (rail + country + asset combinations)
• POST /accounts — request a receiving instrument (idempotent)
• GET /accounts/:id — poll status and retrieve credentials

It reuses existing Stellar infrastructure: discovery via SEP-1, authentication via SEP-10
(G.../M...) and SEP-45 (C...), credential fields via SEP-9, and KYC remediation via SEP-12.

Key Design Choices

• Account, not transaction — the resource is reusable and user-scoped, not flow-scoped
• Idempotent creation — same parameters return the same account, no accidental duplicates
• Explicit offering matrix — clients never infer rail/country compatibility from separate lists
• Auth-protocol agnostic — consumes a valid JWT from SEP-10 or SEP-45

Why not extend SEP-6?

SEP-6 is transaction-scoped. Extending it would conflate two resource models. SEP-58 keeps both
clean: SEP-6 for transactions, SEP-58 for accounts. Providers can implement both — provision via
SEP-58, accept SEP-6 deposits into that same account. See also #1341 and #1372.

Adoption Context

Providers like Bridge (liquidation addresses) and
and on-chain ramp providers already offer reusable receiving instruments via proprietary APIs.
SEP-58 standardizes the common pattern.

Draft PR forthcoming. Looking for feedback on the API surface, offering model, and scope. We have already implemented
in an extended version of django-polaris and are in testing mode.

[antb123]

Submitted as PR #1934: #1934

Filed under the README's draft filename convention (sep_externalaccount.md) since SEP-0058 was concurrently assigned to @leighmcculloch's Contract Build Reproducibility draft (#1923 / #1933). The PR preamble still requests SEP-58 based on this discussion's precedence (March 19 vs May 1), but I'm happy to take any number maintainers assign. Coordinating with @leighmcculloch separately.

Implementation status: I've built this on top of Django Polaris and it's currently in production testing with Bridge as the anchor provider. We're also evaluating integration with Wirex next. The v0.4.0 change adding currency to crypto_address came directly out of that Bridge integration — Bridge offers USDC and USDT on the same chain_id (eip155:1) and the previous idempotency key couldn't disambiguate them.

Open question for the group / maintainers: what's the recommended pattern for inbound-transaction notifications and "more info" payloads tied to a SEP-58 account? My current thinking is to layer this on top of SEP-6 — i.e. once funds land in a SEP-58 receiving instrument, a SEP-6 transaction object materializes and the wallet polls / receives webhooks via existing SEP-6 conventions. That keeps SEP-58 strictly about provisioning and lets SEP-6 own transaction state. Does that match how others are thinking about it, or is there a better fit? Happy to fold guidance into a future SEP-58 version or into a separate SEP-6 issue.

Review and feedback welcome on the PR.