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

# Stellar

> Asset identifiers, trustlines, XLM gas, claimable-balance onramps, and transaction expiry on Stellar.

![Stellar](https://mintcdn.com/etherfuse/XRSchVFGUgreQatD/img/chains/stellar.svg?fit=max\&auto=format\&n=XRSchVFGUgreQatD\&q=85\&s=f52097ff454516ca28cdfdfae0cb559d)

We support onramps, offramps and swaps on Stellar. Stellar needs more chain-specific setup than any other supported network: assets require **trustlines**, wallets need a small **XLM** balance for reserves and fees, and a prepared transaction goes stale when the wallet's **sequence number** moves. This page covers the Stellar-specific parts. The end-to-end flows are in the [Onramps](https://docs.etherfuse.com/v2/guides/testing-onramps.md), [Offramps](https://docs.etherfuse.com/v2/guides/testing-offramps.md) and [Swaps](https://docs.etherfuse.com/v2/guides/testing-swaps.md) guides.

## Supported operations

| Operation | Supported |
| - | - |
| Onramp (fiat → token) | ✓ |
| Offramp (token → fiat) | ✓ |
| Swap (token → token) | ✓ |

## Asset identifiers

Stellar assets use the **`CODE:ISSUER`** format, for example `CETES:GC3CW7EDYRTWQ635VDIGY6S4ZUF5L6TQ7AA4MWS7LEQDBLUSZXV7UPS4`.

> [!WARNING]
>
> **Always read identifiers from [`GET /supported_assets`](https://docs.etherfuse.com/v2/api-reference/assets/list-supported-assets). Never hardcode the issuer.** The issuer account differs between **sandbox and production** and can change. A hardcoded issuer is the most common cause of "wrong asset" problems. Pass `chain=stellar` and use the token's `asset` as-is for `sourceAsset` or `destinationAsset` in your quote.

> [!TIP]
>
> **Getting testnet USDC in sandbox.** We have no faucet for sandbox USDC. To get some, **onramp CETES, then swap CETES → USDC**. You need a trustline for any asset you receive; see below.

## Stablebond addresses

Live asset issuers for every stablebond on Stellar, each linked to Stellar Expert:

## Wallet and gas requirements

Holding and receiving Stellar assets requires XLM for the account reserve and for each trustline. These are **Stellar network requirements, not Etherfuse fees**:

* **\~1 XLM** base reserve to create the account on-chain.
* **\~0.5 XLM** additional reserve per trustline (so \~1.5 XLM for an account holding one asset).
* A few **stroops** per transaction for the network fee. About 0.01 XLM on a wallet covers thousands of transactions.

> [!NOTE]
>
> **Self-custody wallets hold their own XLM.** A bring-your-own Stellar wallet pays its own reserves and network fees. The exception is an **onramp**: when the destination wallet has no account or no trustline, we price the account and trustline setup into the quote fee and deliver a claimable balance (see [Onramps: wallets without a trustline](#onramps-wallets-without-a-trustline) below).
>
> **Embedded wallets** work differently: the key holder signs an order `authorization` instead of signing XDR, and we build every transaction. We pay the network fee on every transaction from an embedded wallet and bill it at cost, so the wallet's XLM covers only its reserves. See [Fees and billing](https://docs.etherfuse.com/v2/guides/embedded-wallets.md#fees-and-billing).

### Trustlines

A wallet **must hold a trustline for any asset it receives.** For onramps, the claim transaction adds the trustline (see below). For **offramps and swaps**, the wallet must already have the trustline and enough XLM before you create the order.

## Register a Stellar wallet

Register the wallet as a payment account with `accountDetails` of kind `address` and `chain` `stellar`. Set `$ORGANIZATION_ID` to the organization that owns the wallet: your own organization or a customer organization. See [Organizations in the route](https://docs.etherfuse.com/v2/overview.md#organizations-in-the-route).

```bash theme={null}
curl -X POST https://api.sand.etherfuse.com/organization/$ORGANIZATION_ID/payment_account \
  -H "Authorization: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "wallet",
    "label": "Stellar wallet",
    "accountDetails": {
      "kind": "address",
      "address": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
      "chain": "stellar"
    }
  }'
```

Use the returned `id` as the `source` or `destination` of a [quote](https://docs.etherfuse.com/v2/api-reference/quotes/create-quote.md). A mis-copied `G...` address fails its checksum and returns `400` `invalid-request`.

## Onramps: wallets without a trustline

You do not need to set up the wallet before an onramp. The wallet is the quote's destination, so we check it on-chain when you quote. If it has no account or no trustline for the asset, the quote fee includes a one-time cost for the XLM, and we deliver the asset as a **claimable balance**.

The order then moves to `claimable`, and `claimInstructions` describes the balance:

```json theme={null}
{
  "status": "claimable",
  "claimInstructions": {
    "kind": "stellarClaimableBalance",
    "balanceId": "00000000abc123...",
    "asset": "CETES:GC3CW7EDYRTWQ635VDIGY6S4ZUF5L6TQ7AA4MWS7LEQDBLUSZXV7UPS4",
    "amount": "100.0000000",
    "claimant": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
    "expiresAt": null
  }
}
```

To claim, call [POST /organization/\{organizationId}/order/\{id}/claim](https://docs.etherfuse.com/v2/api-reference/orders/prepare-claim.md) with no body. It returns `202` with no body, and we prepare the claim. A few seconds later it arrives in an `orderUpdated` webhook and on [`GET .../order/{id}`](https://docs.etherfuse.com/v2/api-reference/orders/get-order):

* A self-held wallet gets `claimInstructions.preparedTransaction`. Its `transaction` adds the trustline and claims the balance in one step. The customer signs and submits it before `expiresAt`.
* An embedded wallet gets the order's `authorization` with `reason` `claim`. The key holder signs it and you submit it. See [Order authorization](https://docs.etherfuse.com/v2/guides/embedded-wallets.md#3-approve-the-authorization).

```json theme={null}
{
  "status": "claimable",
  "claimInstructions": {
    "kind": "stellarClaimableBalance",
    "balanceId": "00000000abc123...",
    "asset": "CETES:GC3CW7EDYRTWQ635VDIGY6S4ZUF5L6TQ7AA4MWS7LEQDBLUSZXV7UPS4",
    "amount": "100.0000000",
    "claimant": "GDUKMGUGD3V6VXTU2RLAUM7A2FABLMHCPWTMDHKP7HHJ6FCZKEY4PVWL",
    "expiresAt": null,
    "preparedTransaction": {
      "transaction": "AAAAAgAAAAA...",
      "expiresAt": "2026-11-04T18:00:00Z"
    }
  }
}
```

This applies to **onramps only**. Offramps and swaps need the wallet to exist and be funded first. See [Onramps: Stellar wallets without a trustline](https://docs.etherfuse.com/v2/guides/testing-onramps.md#stellar-wallets-without-a-trustline) for the full flow.

## Offramps and swaps: fund the wallet first

> [!WARNING]
>
> **The customer's wallet sends the funds.** For offramps and swaps from a self-held wallet, the wallet must exist on-chain, hold enough XLM for the network fee, and hold a trustline for the asset it sends. For a swap, it also needs a trustline for the asset it receives.
>
> Before creating the order, confirm the wallet exists on-chain, holds at least about 1.5 XLM, and has a trustline for the asset being sold. Use [`GET /supported_assets?chain=stellar`](https://docs.etherfuse.com/v2/api-reference/assets/list-supported-assets) to get the issuer for the trustline.

When the source is an [embedded wallet](https://docs.etherfuse.com/v2/guides/embedded-wallets.md), `fundingInstructions.destination` has no `address`. It carries an `authorizationId` instead, and the key holder approves the order's [authorization](https://docs.etherfuse.com/v2/guides/embedded-wallets.md#3-approve-the-authorization) to fund the order.

For a self-held wallet on a Stellar offramp or swap, `fundingInstructions.destination` gives the `address` to pay and a `memo` when one is needed. Fund the order in one of two ways:

1. **Sign the prepared transaction.** When `preparedTransaction` is present, sign `transaction` (an unsigned base64 transaction envelope XDR) and submit it to Horizon. The customer's account is the transaction's source and pays the fee.
2. **Build the payment yourself.** Send a payment of the order's `source.amount` of `source.asset` to `address`, with `memo` when it is present. Wallets that support [SEP-24](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md)-style withdrawals can use this path.

## Stale transactions and refresh

A prepared Stellar transaction stops being valid at the order's funding deadline, so `refreshAfter` is the same time as `fundingDeadline`. It also uses the wallet's sequence number at the time we built it, so it goes stale when the wallet sends another transaction first. Horizon then returns `tx_bad_seq`. Get a new one instead of retrying the stale one:

* **Offramp or swap:** call [`POST /organization/{organizationId}/order/{id}/funding_instructions/refresh`](https://docs.etherfuse.com/v2/api-reference/orders/refresh-funding-instructions). You can call it at any time while the order is `created`. It returns the order as it is. If the old transaction already landed, nothing changes and no webhook arrives, so the customer can't fund the order twice. The new funding instructions arrive a moment later in an `orderUpdated` webhook, and on [`GET .../order/{id}`](https://docs.etherfuse.com/v2/api-reference/orders/get-order).
* **Onramp claim:** the claim transaction uses the wallet's current sequence number, so another transaction from the wallet makes it stale. Call [`POST /organization/{organizationId}/order/{id}/claim`](https://docs.etherfuse.com/v2/api-reference/orders/prepare-claim) for a new one. The new `preparedTransaction` arrives a moment later in an `orderUpdated` webhook, and on [`GET .../order/{id}`](https://docs.etherfuse.com/v2/api-reference/orders/get-order).

> [!TIP]
>
> Get the transaction right before the customer signs it. If Horizon returns `tx_bad_seq`, refresh and have the customer sign the new one.

## Related

> [card] [Onramps](https://docs.etherfuse.com/v2/guides/testing-onramps.md)

> [card] [Offramps](https://docs.etherfuse.com/v2/guides/testing-offramps.md)

> [card] [Swaps](https://docs.etherfuse.com/v2/guides/testing-swaps.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.