> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sodax.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> SODAX is mainnet-only (no testnet chains or RPC endpoints exist) with a hub-and-spoke architecture; Sonic is the hub. SODAX is non-custodial protocol/software: it routes and settles; independent solvers on the marketplace fill — never say 'our solver', 'the SODAX solver', that SODAX trades, takes custody, or fills orders. For frontend/React integrations, prefer @sodax/dapp-kit hooks over calling @sodax/sdk directly. SDK operations — the methods that build, submit or await a transaction, and the API/quote calls — return Result<T, E> ({ ok: true, value } or { ok: false, error }): check result.ok, never wrap them in try/catch or branch on error.message; discriminate on the narrow error.code union instead. Synchronous config getters (getPartnerFee, getSupportedSwapTokens, getVault, ...) return their value directly, not a Result.

# Stellar Sponsoring: Quick Reference

> The sponsored Stellar activation flow as a dense reference card.

A new Stellar account must exist on-chain before it can receive anything, and a new user has 0 XLM.
SODAX's sponsor pays the base reserve. The user's wallet signs; the backend co-signs and submits.
Mainnet only. In swaps when destination is XLM account is has to be activated to be able to receive XLM (other assets require trustline).

**Ordered prerequisites** (a non-native destination token needs all three):

1. Activate — free, sponsored.
2. Receive XLM — the account is left with zero spendable balance, so it still can't pay a fee.
3. Add trustline — affordable only after step 2.

**Surface** — `sodax.sponsoring`: `activateStellarAccount`, `getStellarAccountStatus`,
`isStellarAccountActive`, `getStellarSponsorConfig`. All return `Result`. Config goes in
`sponsoringApiConfig` (own host, own `x-api-key`, inherits nothing).

**React** — use `useStellarGate`; it sequences all three. Pieces: `useActivateStellarAccount`,
`useStellarAccountStatus`, `useSponsorConfig`, `useEstablishTrustline`.

**Gotchas**

* `alreadyActive` is a success, not a no-op.
* Branch on `error.context.nextAction`, not status — the two 503s want opposite handling.
* A sequence conflict costs a second wallet prompt; wire `onSignatureRequired`.
* Never hardcode the sponsor account; read it from config.

**Docs** — [SPONSORING.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/SPONSORING.md) ·
[STELLAR\_TRUSTLINE.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/STELLAR_TRUSTLINE.md) ·
[CONFIGURE\_SDK.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/CONFIGURE_SDK.md)

**Examples**

* [apps/demo/src/providers.tsx](https://github.com/icon-project/sodax-sdks/blob/main/apps/demo/src/providers.tsx) — sponsoring API URL + key setup: the `sponsoringApiConfig` object reads `VITE_SPONSORING_API_BASE_URL` / `VITE_SPONSORING_API_KEY`, omits each when unset (falls back to the packaged endpoint), and is passed as `api.sponsoringApiConfig` on the `Sodax` config below. Env placeholders in [apps/demo/example.env](https://github.com/icon-project/sodax-sdks/blob/main/apps/demo/example.env).
* [apps/stellar-sponsor-example](https://github.com/icon-project/sodax-sdks/tree/main/apps/stellar-sponsor-example) — full journey + offline mock (`cp example.env .env`, `pnpm mock-sponsoring`, `pnpm dev`, Test lab → Run all)
* [swaps/SwapCard.tsx](https://github.com/icon-project/sodax-sdks/blob/main/apps/demo/src/components/swaps/SwapCard.tsx) — swap gated on a Stellar destination; also [swaps-api/SwapCard.tsx](https://github.com/icon-project/sodax-sdks/blob/main/apps/demo/src/components/swaps-api/SwapCard.tsx), [LimitOrderCard.tsx](https://github.com/icon-project/sodax-sdks/blob/main/apps/demo/src/components/swaps/LimitOrderCard.tsx), [BridgeDialog.tsx](https://github.com/icon-project/sodax-sdks/blob/main/apps/demo/src/components/bridge/BridgeDialog.tsx)
* [apps/node/src/stellar-sponsor.ts](https://github.com/icon-project/sodax-sdks/blob/main/apps/node/src/stellar-sponsor.ts) — headless
* AI skill: `packages/skills/skills/sodax-sdk/sponsoring/SKILL.md`